BMC Atrium CMDB 2.1.

00

Developers Reference Guide

August 2007

www.bmc.com

Contacting BMC Software

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

United States and Canada

Address

BMC SOFTWARE INC

2101 CITYWEST BLVD
HOUSTON TX 77042-2827
USA

Telephone

713 918 8800 or

800 841 2031

Fax

(01) 713 918 8000

Fax

713 918 8000

Outside United States and Canada

Telephone

(01) 713 918 8800

If you have comments or suggestions about this documentation, contact Information Development by email at
[email protected].
Copyright 20052007 BMC Software, Inc.
BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with
the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC
trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other
trademarks or registered trademarks are the property of their respective owners.
ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is
registered in the U.S. Patent and Trademark Office.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.
UNIX is a registered trademark of The Open Group.
BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this
information is subject to the terms and conditions of the applicable End User License Agreement for the product and the
proprietary and restricted rights notices included in this documentation.

Restricted Rights Legend

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

Customer Support
You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer
Support by telephone or email. To expedite your inquiry, please see Before Contacting BMC Software.

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

Read overviews about support services and programs that BMC Software offers.
Find the most current information about BMC Software products.
Search a database for problems similar to yours and possible solutions.
Order or download product documentation.
Report a problem or ask a question.
Subscribe to receive email notices when new product versions are released.
Find worldwide BMC Software support center locations and contact information, including email addresses, fax
numbers, and telephone numbers.

Support by telephone or email

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

Before Contacting BMC Software

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

Product information

Product name
Product version (release number)
License number and password (trial or permanent)

Operating system and environment information

Machine type
Operating system type, version, and service pack
System hardware configuration
Serial numbers
Related software (database, application, and communication) including type, version, and service pack or
maintenance level

Sequence of events leading to the problem

Commands and options that you used

Messages received (and the time and date that you received them)

Product error messages

Messages from the operating system, such as file system full
Messages from related software

Contents
Preface

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
The New icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
BMC Atrium CMDB documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Section I Developing programs with the CMDB APIs

Chapter 1

13

Introduction to the BMC Atrium CMDB APIs

15

BMC Atrium CMDB API overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Web services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using API programming compared with the CMDB Console . . . . . . . . . . . . . . . . . . .
When to use the API compared with the CMDB Console. . . . . . . . . . . . . . . . . . . .
CMDB Console and API terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16
17
18
18
19
19
20

Chapter 2

21

Getting started

New in this release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

API compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java API changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
API version requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C API package contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Header files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Library files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiler information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Link information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java API package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Library files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Header files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Version information for BMC Atrium CMDB API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Migrating to the BMC Atrium CMDB from 1.1 to 2.0 API . . . . . . . . . . . . . . . . . . . . . .

Contents

22
22
23
23
24
24
25
26
27
27
27
28
28
28
29
29

Chapter 3

Programming common BMC Atrium CMDB tasks

31

Java program requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Working with configuration item classes and instances. . . . . . . . . . . . . . . . . . . . . . . . . 32
Creating a CI class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Creating attributes for your class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Creating a CI instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Working with relationship classes and instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Creating a relationship class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Creating a relationship between two CI instances . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Retrieving instance details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Chapter 4

BMC Atrium CMDB tools

41

Working with the cmdbdriver program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

From the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Using a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Using cmdbdriver on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Migrating data between BMC Atrium CMDB servers . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Logging in to the cmdbdriver program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Step 1Exporting class data with cmdbdriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Step 2Export instance data with cmdbdriver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Step 3Import class definitions with cmdbdriver . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Step 4Import instance data with cmdbdriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Step 5Export reconciliation definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Step 6Import reconciliation definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Using the extension loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
The extension loader directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Packaging and installing BMC Atrium CMDB extensions . . . . . . . . . . . . . . . . . . . 54
Verifying your installed extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Integrating the CI Relationship Viewer with other applications. . . . . . . . . . . . . . . . . . 63
Launching the CI Relationship Viewer from AR System applications . . . . . . . . . 64
Embedding the CI Relationship Viewer in AR System applications . . . . . . . . . . . 66
Launching the CI Relationship Viewer from non-AR System applications . . . . . 67
Configuring the CI Relationship Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Working with filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Customizing the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Creating CI Relationship Viewer events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Creating CMDB status alerts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Importing data with Integration Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Working with SQL views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Debugging BMC Atrium CMDB API programs using print.c routines . . . . . . . . . . . . 78

Developers Reference Guide

Section II API reference

Chapter 5

79

C API functions and data structures

81

Related files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Data model functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Instance functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Bulk entry transaction functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Environment functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
User interface component functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Import and Export functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Free functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Reconciliation Engine functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Federation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Audit functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Class structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Attribute structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Instance structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
General purpose structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Export and import structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Graph query structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
User interface components structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Reconciliation Engine structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Federation structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Audit structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Chapter 6

Web services API operations and data structures

191

Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Instance data operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data model operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reconciliation Engine operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Federation operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Audit operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User interface component operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Utility operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Instance structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Graph query structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Attribute structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Utility structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User interface component structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reconciliation Engine structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Federation structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Audit structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents

192
192
204
215
219
222
224
225
227
227
232
236
242
250
251
253
256
258

Appendix A

CI Relationship Viewer events

261

Events from AR System to CI Relationship Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Events from CI Relationship Viewer to AR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Appendix B

Using graph queries to find related CIs

265

Representing graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

The CMDBGraphQuery API function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Glossary

275

Index

283

Developers Reference Guide

Preface
The BMC Atrium CMDB Developers 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 APIsThis section

provides an introduction to the BMC Atrium CMDB API suite, provides
instructions on how to program the BMC Atrium CMDB application using Java
methods, and provides procedures for using other BMC Atrium CMDB tools.

API referenceThis section provides descriptions of the C API functions, web

services operations, and the data structures used by each function and
operation.
The BMC Atrium CMDB application runs on top of the BMC Remedy Action
Request System application (AR System) and enables you to manage data
about your IT environment.

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

The New icon

Documentation for the BMC Atrium CMDB Developers Reference Guide contains a
New icon that identifies features or products that are new or enhanced with
version 2.1.00.

Preface
9

BMC Atrium CMDB 2.1.00

BMC Atrium CMDB documentation

The following table lists the documentation available for BMC Atrium CMDB.
Unless otherwise noted, softcopy documentation is available in the Docs directory
of the product DVD and the Support site at http://www.bmc.com/support_home.
Title

Document provides

Audience

Common Data Model

Diagram

Hierarchical diagram of all classes in the Common Administrators Print and PDF
Data Model (CDM) including unique attributes and
applicable relationships

Concepts and Best

Practices Guide

Information about CMDB concepts and best

practices for planning your BMC Atrium CMDB
implementation

Data Model Help

Description and details of superclasses, subclasses, Administrators HTML

(product DVD
attributes, and relationship classes for each class.
only)
Contains only information about the Common Data
Model at first, but can be updated to include
information about data model extensions you
install.

Developers Reference
Guide

Information about creating API programs, using C Administrators Print and PDF
and web services API functions and data structures, and
and a list of error messages
programmers

Installation and
Configuration Guide

Information about installing and configuring BMC

Atrium CMDB, including permissions, class
definitions, reconciliation, and federation

Administrators Print and PDF

Javadoc API Help

Information about Java classes, methods, and

variables that integrate with BMC Atrium CMDB

Programmers

IT leaders and
administrators

Format

Print and PDF

HTML
(product DVD
only)

Mapping Your Data to Mappings of common IT objects to the appropriate Administrators Spreadsheet,
print and PDF
class in which to store them, whether part of the
BMC Atrium CMDB
Classes
Common Data Model or an extension. Also includes
information about further categorizing instances
using key attributes.
Master Index

Combined index of all guides

Everyone

Print and PDF

Online Help

Help for using and configuring BMC Atrium

CMDB, available by clicking Help in the product
interface

Users and
administrators

Product Help
(available from
Help links
once installed)

Release Notes

Information about new features, open issues, and

resolved issues

Everyone

Print and PDF

10

Developers Reference Guide

Related documentation

Title

Document provides

Audience

Format

Troubleshooting Guide

Information about resolving issues with BMC

Atrium CMDB components, including API, filter,
and console error messages and their solutions.

Administrators, Print and PDF

programmers,
and BMC
Support
personnel

Users Guide

Information about using BMC Atrium CMDB,

including searching for and comparing CIs and
relationships, relating CIs, viewing history, and
launching federated data

Users

Print and PDF

Related documentation
The following table lists some documentation for related BMC products that might
be of interest to BMC Atrium CMDB users. This documentation is available from
the Support site at http://www.bmc.com/support_home.
Title

Document provides

Audience

Format

BMC Atrium
Integration Engine
7.1.00 Users Guide

Information about how to establish a data transfer

between third-party databases and BMC Atrium
CMDB.

Administrators Print and PDF

and developers

BMC Configuration
Management
Configuration
Discovery Integration
for CMDB 7.1
Implementation Guide

Information about the following:

Transferring configuration data from BMC
Configuration Management to BMC Atrium
CMDB

Normalizing discovered software configuration
data with the BMC Definitive Software Library
before transferring it to BMC Atrium CMDB.

Administrators Print and PDF

and developers

BMC Foundation
Discovery and BMC
Topology Discovery
Installation and
Configuration Guide

Information about the configuration of a connection Administrators Print and PDF

and developers
between BMC Atrium CMDB and the discovery
data store from BMC Foundation Discovery and
BMC Topology Discovery.

BMC Foundation
Discovery and BMC
Topology Discovery
User Guide

Information about the synchronization of the

topology datastore with BMC Atrium CMDB.

Administrators Print and PDF

and developers

BMC Remedy Action

Information about AR System data structures, C
Request System 7.1.00: API function calls, and OLE support.
C API Reference

Administrators Print and PDF

and
programmers

BMC Remedy Action

Information about configuring AR System servers
Request System 7.1.00: and clients, localizing, importing and exporting
Configuring
data, and archiving data.

Administrators Print and PDF

Information about components necessary to build

BMC Remedy Action
Request System 7.1.00: applications in AR System, including applications,
Form and Application fields, forms, and views.
Objects

Developers

Print and PDF

Preface
11

BMC Atrium CMDB 2.1.00

Title

Document provides

Audience

Format

BMC Remedy Action

Procedures for installing AR System
Request System 7.1.00:
Installing

Administrators Print and PDF

Information about the mid tier, including mid tier

BMC Remedy Action
Request System 7.1.00: installation and configuration, and web server
configuration.
Installing and
Administering BMC
Remedy Mid Tier

Administrators Print and PDF

Information about integrating AR System with

Administrators Print and PDF
BMC Remedy Action
Request System 7.1.00: external systems using plug-ins and other products, and developers
Integrating with Plug- including LDAP, OLE, and ARDBC.
ins and Third-Party
Products
Definitive Software
Library 7.1
Administrators Guide

12

Information about installing and configuring DSL, Administrators Print and PDF
updating vendor data, and connecting DSL to BMC
Configuration Management and AR System
databases

Developers Reference Guide

Section

Developing programs with the

CMDB APIs
This section explains how to use the BMC Atrium CMDB tools, such as the
cmdbdriver program and the extension loader, and how through programming,
you can extend your application using the BMC Atrium CMDB APIs.
This section is organized into the following chapters:

Chapter 1, Introduction to the BMC Atrium CMDB APIs, provides an

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

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

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

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

Section I

Developing programs with the CMDB APIs

13

BMC Atrium CMDB 2.1.00

14

Developers Reference Guide

Chapter

Introduction to the BMC

Atrium CMDB APIs
This section provides an overview of BMC Atrium CMDB programming interface
(API) suite.
The following topics are provided:

BMC Atrium CMDB API overview (page 16)

Using API programming compared with the CMDB Console (page 19)

Chapter 1 Introduction to the BMC Atrium CMDB APIs

15

BMC Atrium CMDB 2.1.00

BMC Atrium CMDB API overview

The BMC Atrium CMDB provides an API suite that allows you, through
programming, to work with class definitions, instance data, federation,
reconciliation, audit and other functions. The BMC Atrium CMDB API suite is
composed of the C, Java, and web services APIs.
The C and Java APIs provide similar data structures and functions to encapsulate
information and functionality. You can use either C or Java API depending on your
application platform.
The Web services API provides a set of platform-independent operations that
communicate with your applications to retrieve and send data.
Figure 1-1: BMC Atrium CMDB C and Java architecture
AR System
Applications
Service Impact
Manager
CMDB Console
BMC
Remedy
User

Web
Client

Topology
Discovery

CI Relationship Viewer
BMC
Remedy
User

Web Service Clients

.Net
Client

AXIS
Client

Web
Client

CMDB Web Services

API

BMC Remedy Mid Tier

(CMDB API)

CMDB Java
API

Reconciliation
Engine

CMDB C
API

AR System
API

Action Request System

BMC Atrium
CMDB
CDM
Database

NOTE
The arrows indicate the directions in which each program or process can initiate
an API function. Data can flow in any direction.
As shown in Figure 1-1, a BMC Atrium CMDB components, such as the CI
Relationship Viewer and CMDB Console use the Java API to manipulate the CDM,
whereas the external data consumers and data providers can communicate either
using the web services API or Java API.

16

Developers Reference Guide

BMC Atrium CMDB API overview

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

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

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

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

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

Features
You can use the C API functions to perform the following operations:

Create, modify, and delete classes and instances.

Retrieve CI and relationship information.

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

Components
The C API consists of a set of functions and data structures, most of which perform
a specific database or data source operation. For example, you can use a function
to retrieve information about a particular BMC Atrium CMDB class.
Most of these C API functions accept one or more BMC Atrium CMDB C data
structures as parameters that qualify the action to perform, such as type of class to
create, qualification for an instance to retrieve or delete, or class name to modify.
For more information about the C API functions and data structures, see Chapter
5, C API functions and data structures.
The sdk/samples/driver subdirectory in your BMC Atrium CMDB installation
directory contains the source code for the cmdbdriver program. This program
provides a command-line interface for calling C API functions. The cmdbdriver
program also includes print routines for every data structure in the API, making it
a useful debugging tool.
For more information about the print routines, see Debugging BMC Atrium
CMDB API programs using print.c routines on page 78.

Chapter 1 Introduction to the BMC Atrium CMDB APIs

17

BMC Atrium CMDB 2.1.00

Web services API

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

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

BMC software partnersFor developing integrated solutions with BMC

Atrium CMDB.

UsersFor developing programs that set up communication between BMC

Atrium CMDB and other products running in the environment.

Components
The BMC Atrium CMDB web services API consists of operations and data
structures. Although the web services operations correspond to the BMC Atrium
CMDB C API functions, they do not correspond one-to-one with the C API. The
web services API data structures correspond to the classes in the Java API.
For more information about the web services operations that are currently
available, see Chapter 6, Web services API operations and data structures.

Java API
The BMC Atrium CMDB Java API is a collection of Java classes and methods that
provide the C API functionality in a Java development environment. Use the Java
API if you write server-side web applications that you access through the Java
Server page (JSP) or Java servlets web tier layer.
The Java API provides an object model of BMC Atrium CMDB. You will find it
easier to use the Java API if you are already familiar with the C API.
For more information about the Java API, see the Javadoc API Help, which is
located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation
directory. To access the Javadoc API Help, open the index.html file.

18

Developers Reference Guide

Using API programming compared with the CMDB Console

Features
The following list describes the Java API features:

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

In the Java API, server access information is encapsulated in an ARServerUser

object. For more information about ARServerUser object, see BMC Remedy Action
Request System 7.1.00: Integrating with Plug-ins and Third-Party Products.

The Java API has its own naming conventions.

Using API programming compared with the

CMDB Console
The primary reason to write your own API program is to satisfy specific business
needs that you cannot meet with the CMDB Console.
In addition, API programming gives you the flexibility to customize your
application. However, API solutions are more complex to design, implement, and
maintain.
The CMDB Console provides an easy-to-use graphical user interface for
performing BMC Atrium CMDB tasks, such as creating classes, CIs, and
relationships, and viewing instance history.
For more information about performing administrator tasks using the CMDB
Console, such as using the Class Manager, Federation Manager, and, the
Reconciliation Engine Manager, see the BMC Atrium CMDB 2.1.00 Installation and
Configuration Guide.
For more information about performing user tasks using the CMDB Console, such
as viewing CI history, Viewing CI and relationship classes, and comparing
instances, see the BMC Atrium CMDB 2.1.00 Users Guide.

When to use the API compared with the CMDB Console

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

Use API Programming? Use the CMDB Console?

You want to modify the CDM.

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

Yes
Yes

Chapter 1 Introduction to the BMC Atrium CMDB APIs

19

BMC Atrium CMDB 2.1.00

Requirement

Use API Programming? Use the CMDB Console?

You need to create, delete, or search for

BMC Atrium CMDB classes.

Yes
Yes

You need to perform complex

operations that involve multiple
objects.
You need to create, delete, or search
BMC Atrium CMDB relationships.

Yes

You need a two-way interface (or

gateway) between the BMC Atrium
CMDB and another application.

Yes

The values you want to specify for

$PROCESS$ or the Run Process action
exceed the size limitation of the
command line.

Yes

CMDB Console and API terminology

The CMDB Console and the APIs use different terms to see a specific task. Table 12 list these differences.
Table 1-2: CMDB Console and API terminology

20

BMC Atrium CMDB term

API term

search

getList

create

create

modify

set

view/display

get

Developers Reference Guide

Chapter

Getting started

This section provides the information you need to know before you start using the
BMC Atrium CMDB API suite.
The following topics are provided:

New in this release (page 22)

C API package contents (page 24)
Java API package contents (page 27)
Version information for BMC Atrium CMDB API (page 28)
Sample source code (page 29)
Migrating to the BMC Atrium CMDB from 1.1 to 2.0 API (page 29)

Chapter 2 Getting started

21

BMC Atrium CMDB 2.1.00

New in this release

In BMC Atrium CMDB version 2.1.00, changes have been made to the APIs. This
section provides the API compatibility information and explains these API
changes. For more information about these changes, see the Overview page of
your Javadoc Help.

API compatibility
The following list explains the backward and forward compatibility of BMC
Atrium CMDB 2.1.00:

If you developed 2.0.x clients that use version 2.0.x DLLs and libraries, they can
continue to work with the 2.1 server.

If you use version 2.1.00 DLLs and libraries for your clients, you need to make
appropriate changes to your code and recompile it.
Table 2-1 provides a compatibility matrix for the AR System server and BMC
Atrium CMDB.
Table 2-1: BMC Atrium CMDB compatibility matrix
AR System
server

BMC Atrium
CMDB server

BMC Atrium
CMDB client

Supported

7.1.00

2.1.00

2.1.00

Yes

7.1.00

2.1.00

2.0.x

Yes

BMC Atrium CMDB backwards

compatibility: older client and newer
server.

7.1.00

2.0.x

2.1.00

No

BMC Atrium CMDB forward

compatibility: newer client and older
server.

7.1.00

2.0.1 patch x

2.0.1 patch x

Yes

AR System backwards compatibility.

7.1.00

2.0.1 patch x

2.0.1 patch x

Yes

AR System and BMC Atrium CMDB

backwards compatibility. Preferably,
upgrade to BMC Atrium CMDB 2.1
server.

7.1.00

2.0.0 patch x or 2.0.0 patch x or No

earlier
earlier

You must upgrade BMC Atrium CMDB

server to version 2.1.00.

7.0.x or earlier

2.1.00

The Foundation piece has to be of a more

recent version than the application.
Upgrade the server before upgrading
BMC Atrium CMDB.

22

Developers Reference Guide

Any

No

Remarks

New in this release

Java API changes

In version 2.1.00, the following changes have been made to the Java API:

Package name changesThe package name has been changed from

com.remedy.cmdb.api

to com.bmc.cmdb.api.

JRE version changesWith 2.1.00, the minimum JRE version required is

1.5.0_06 or greater.

Java API changesThe AR System version 7.1.00 Java API is enhanced to use
some of the features of Java, such as annotations, enumerations, and typedcollections. Therefore, the BMC Atrium CMDB Java API has also changed. For
more information about these changes, see the Overview page of your Javadoc
Help.

API version requirements

In version 2.1.00, a new feature is developed that allows you to restrict older
versions of BMC Atrium CMDB clients from connecting to a newer version of the
server. To specify the minimum API version with which the server can
communicate, you configure the Minimum-CMDB-API-Version parameter in the
ar.cfg (Windows) or ar.conf (UNIX) file. The default value for this setting is
configured to 3.
For example, if you set Minimum-CMDB-API-Version to 4, clients prior to version
2.1.00 will not be able to communicate with the server. For more information about
the ar.cfg or ar.conf configuration file, see BMC Remedy Action Request System 7.1.00
Configuring. Table 2-2 provides the BMC Atrium CMDB releases and their
corresponding API versions.
Table 2-2: BMC Atrium CMDB releases and corresponding versions
BMC Atrium CMDB release

API version

BMC Atrium CMDB 2.1.00

BMC Atrium CMDB 2.0.x

Chapter 2 Getting started

23

BMC Atrium CMDB 2.1.00

C API package contents

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

Header files
Table 2-3 displays the list of C API header files installed in the include directory:
Table 2-3: C API Header files

24

File Name

Contents

ar.h

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

cmdb.h

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

arerrno.h

Error code definitions.

arextern.h

External declarations for the API functions, specified with and

without prototypes for use with standard C, ANSI C, or C++
compilers.

arfree.h

External declarations for the FreeAR functions. These functions

recursively free all allocated memory associated with a particular
data structure.

cmdbfree.h

External declarations for the FreeCMDB functions. These functions

recursively free all allocated memory associated with a particular
data structure.

arstruct.h

Core and reserved subclasses ID definitions, database separator

characters, and labels for exporting structure definitions.

Developers Reference Guide

C API package contents

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

NOTE
The SDK contains files that are not listed here. Those files are required for Java API
or for working with the cmdbdriver program, but are not required to create a C API
program.
Table 2-4: C API library files
Platform

Files

Windows

arapi71.dll
arcatalog_eng.dll
arjni71.dll
arrpc71.dll
arutiljni71.dll
arutl71.dll
cmdbapi21.dll
cmdbjni21.dll
icudt32.dll
icudtbmc32.dll
icuinbmc32.dll
icuucbmc32.dll
mfc71.dll
msvcp71.dll
msvcr71.dll
rcmn71.dll

Solaris

libarjni71.so
libarutiljni71.so
libcmdbapi21.so
libcmdbjni21.so
libicudatabmc.so.32
libicui18nbmc.so.32
libicuucbmc.so.32
libjlicapi71.so

AIX

libarjni71.a
libarutiljni71.a
libcmdbjni21.a
libcmdbapi21.a
libicudatabmc32.a
libicui18nbmc32.a
libicuucbmc32.a
libjlicapi71.a

Chapter 2 Getting started

25

BMC Atrium CMDB 2.1.00

Platform

Files

HP-UX

libicudatabmc.sl.32
libicui18nbmc.sl.32
libicuucbmc.sl.32
libarjni71.sl
libarutiljni71.sl
libcmdbapi21.sl
libcmdbjni21.sl
libjlicapi71.sl

Linux

libicudatabmc.so.32
libicui18nbmc.so.32
libicuucbmc.so.32
libarjni71.so
libarutiljni71.so
libcmdbapi21.so
libcmdbjni21.so
libjlicapi71.so

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

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

Microsoft Visual C++ version 7.0 or later

Structure member alignment: 8

bytes

Set code generation to Multithreaded

(default)
DLL, not DebugMultithreaded DLL. Where

other included libraries cause conflicts, add

the project options to avoid using the Debug C
runtime library. If your program references this library at runtime, memory
management errors will occur when memory pointers are referenced by both
the Debug and Release C runtime libraries.

/nodefaultlib:"MSVCRTD" to

ANSI standard C or C++ compiler (for UNIX)

IMPORTANT
If you develop C++ clients that run on HP machines using the BMC Atrium CMDB
C API, you need to compile your code with the __HPACC_THREAD_SAFE_RB_TREE flag
enabled. This is because the libraries that the tree header file uses, which includes
tree.cc, are not thread safe. For more information, see the following link:
http://h21007.www2.hp.com/dspp/tech/tech_TechDocumentDetailPage_IDX/
1,1701,7866,00.html.

26

Developers Reference Guide

Java API package contents

Link information
Table 2-5 lists the libraries that your programs must use for linking to BMC Atrium
CMDB.
Table 2-5: Link files
Platform

Links

Windows

cmdbapi21.dll
arapi71.dll

Solaris, Linux

libcmdbapi21.so
libarapi71.so

HP-UX

libcmdbapi21.sl
libarapi71.sl

AIX

libcmdbapi21.a
libarapi71.a

Java API package contents

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

NOTE
In version 2.1, the BMC Atrium CMDB Java API has changed as a result of
modifications in the AR System Java API. For a list of affected CMDB Java classes,
see the Javadoc API Help, which is located in the sdk/javadoc/cmdbapi/
subdirectory of your CMDB installation directory. To access the Javadoc API Help,
open the index.html file.

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

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

J2SE Software Development Kit (SDK), version 1.5.0_06 or higher.

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

Chapter 2 Getting started

27

BMC Atrium CMDB 2.1.00

Library files
When you install BMC Atrium CMDB, a list of Java API library files are installed
with the application. For more information about these library files, see the section
Installation and deployment of the JavaAPI_Overview.html page of the Javadoc
API Help.

Header files
Table 2-6 lists the header files that are installed with the Java API.
Table 2-6: Header files for the CMDB programs
Header file name

Description

com.bmc.arsys.api.*;

AR System API functions

com.bmc.cmdb.api.*;

CMDB API functions

java.util.*;

Java utilities library

Version information for BMC Atrium CMDB API

With BMC Atrium CMDB 2.1.00, you can view version information, such as
version number, and build date and time for the BMC Atrium CMDB API. To view
the information, open a command line window and type java jar
cmdbapi21.jar. On Windows, a command line window is displayed, as shown in
Figure 2-1
Figure 2-1: API version information

Build time
Build date

28

Developers Reference Guide

Sample source code

Sample source code

The sdk/samples/driver subdirectory in the BMC Atrium CMDB installation
directory, includes the source code for a sample BMC Atrium CMDB client
program. A compiled version of the cmdbdriver program is located in the sdk/bin
directory.
When the BMC Atrium CMDB API package is installed, a series of directories is
created in the installation directory. The src directory contains subdirectories with
source code for the cmdbdriver sample program.
For more information about the cmdbdriver program, see Chapter 4, Working
with the cmdbdriver program.
After compiling the source code or locating the prebuilt program supplied with the
API, you can use cmdbdriver to:

Identify function input parameters and load them with appropriate values.

Examine the content and structure of function output parameters.

Experiment with different parameter values.

Migrating to the BMC Atrium CMDB from 1.1 to

2.0 API
In version 2.0, several API changes were made, such as modifications to the
function parameters and data structures. For the list of parameters and data
structures that were modified, see the BMC Atrium CMDB 2.0 Developers Reference
Guide.

Chapter 2 Getting started

29

BMC Atrium CMDB 2.1.00

30

Developers Reference Guide

Chapter

Programming common BMC

Atrium CMDB tasks
This section describes how to use the BMC Atrium CMDB Java methods to
perform common tasks. These tasks are explained using Java code samples.
The following topics are provided:

Java program requirements (page 32)

Working with configuration item classes and instances (page 32)

Working with relationship classes and instances (page 37)

Chapter 3 Programming common BMC Atrium CMDB tasks

31

BMC Atrium CMDB 2.1.00

Java program requirements

The procedural building blocks of a BMC Atrium CMDB program are functions or
operations that can invoke one another. For more information about specific Java
method parameters, see the Javadoc API Help, which is located in the sdk/
javadoc/cmdbapi/ subdirectory of your CMDB installation directory. To access the
Javadoc API Help, open the index.html file.
For your Java code to compile with the BMC Atrium CMDB classes, make sure you
point the class path environment variable to the BMC Atrium CMDB jar files
directory.
For the list of header files and link files required for your Java code, see Java API
package contents on page 27.

Working with configuration item classes and

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

Creating a CI class
The following example creates two classes, PhoneSystem and Socket. Both classes
are created in the ACME namespace. All class definitions that extend the CDM use a
namespace other than BMC.CORE.
Example: Creating classes
//Create variables to hold the class name data
String acmeNamespace = "ACME";
String phoneSystemClassName = "phoneSystem";
String socketClassName = "Socket";
//Create the class name key for the Phone System class.
CMDBClassNameKey phoneSystemClassNameKey = new
CMDBClassNameKey(phoneSystemClassName, acmeNamespace);
String phoneSystemClassID = "ABCD-1234";

32

Developers Reference Guide

Working with configuration item classes and instances

//Create an instance of the CMDBClass

CMDBClass phoneSystemClass = new CMDBClass(phoneSystemClassNameKey,
phoneSystemClassID, null);
try {
//Create the Phone System class in BMC Atrium CMDB
phoneSystemClass.create(currentUser);
}
catch (ARException ex) {
System.out.println(ex.toString());
}
//create the socket class
CMDBClassNameKey socketClassNameKey = new
CMDBClassNameKey(socketClassName, acmeNamespace);
String socketClassID = "ACME_SocketClass";
CMDBClass socketClass = new CMDBClass(socketClassNameKey, socketClassID,
null);
// create the socket class in BMC Atrium CMDB
try {
socketClass.create(currentUser);
}
catch (ARException ex) {
System.out.println(ex.toString());
}

In the example, the phoneSystemClassNameKey and socketClassNameKey class

variables hold the class name and namespace definitions for the phoneSystem and
Socket classes respectively. The classNameKey class variables are passed as
parameters to the constructor of the CMDBClass class. A class ID is an identification
string that uniquely identifies a particular class within the BMC Atrium CMDB.
In the try loop, the phoneSystemClass and socketClass classes are created in the
BMC Atrium CMDB. The currentUser parameter is a pre-instantiated
ARServerUser class that has valid user login credentials.
For more information about the parameters for the CMDBCreateClass function, open
index.html of the Java API Help, which is located in the sdk/javadoc/cmdbapi/
subdirectory of your CMDB installation directory.

Chapter 3 Programming common BMC Atrium CMDB tasks

33

BMC Atrium CMDB 2.1.00

Creating attributes for your class

Every class you create will have attributes that hold different values for each
instance of the class. The following example illustrates how to create attributes for
the phoneSystemClass.
Example: Creating attributes
//Create attributes for the phoneSystem class
String serialNumAttrName = "ACMESerialNumber";
int serialNumFieldId = ACME_SERIAL_NUM_FIELD_ID;
int serialNumEntryMode =
CMDBAttribute.CMDB_ATTR_ENTRYMODE_REQUIRED;
//Define a data type and limit for the attribute
CMDBAttributeLimit serialNumLimit = newCMDBCharLimit(30);
//Create a default value for the attribute
Value serialNumDefaultValue = null;
//Create a Java instance of the attribute
CMDBAttribute serialNumAttr = new
CMDBAttribute(serialNumAttrName,
serialNumFieldId, serialNumEntryMode,
serialNumLimit, null);
//Create another attribute for the phoneSystem class
String costAttrName = "Cost";
int costFieldId = ACME_COST_FIELD_ID;
int costEntryMode =
CMDBAttribute.CMDB_ATTR_ENTRYMODE_OPTIONAL;
//Create a variable of type Currency
CMDBAttributeLimit costLimit = new CMDBCurrencyLimit;
//create a Java instance of the Cost attribute
CMDBAttribute costAttr = new CMDBAttribute(costAttrName,
costFieldId, costEntryMode,
costLimit, null);
//Create a hash map to hold the attribute data
HashMap attributeHashMap = new HashMap();
//Add the two attributes to the hash map
attributeHashMap.put(serialNumAttruName, serialNumAttr);
attributeHashMap.put(costAttrName, costAttr);
//Associate these attributes to the phoneSystemClass
phoneSystemClass.setAttributes(attributeHashMap);
// Update the BMC Atrium CMDB with the new attributes
try {
phoneSystemClass.update(currentUser);
}
catch (ARException ex) {
System.out.println(ex.toString());
}

34

Developers Reference Guide

Working with configuration item classes and instances

In the example, the serialNumAttrName, serialNumFieldId, and

serialNumEntryMode variables are created to hold the attribute name, attribute field
ID, and the entry mode for the attribute, respectively.
When you specify the Required entry mode for an attribute, you must provide a
value for this attribute for every instance of the class. The field ID is a unique
numeric identifier for an attribute.
The data type and limit for the attribute is defined using the serialNumLimit class
variable, which is of type CMDBAttributeLimit class. In the example, the
serialNumAttr attribute is defined as a character data type with a limit of 30
characters.
A default value of Null is specified for the attribute in the serialNumDefaultValue
variable. This value is used if no value is provided for the ACMESerialNumber
attribute when creating an instance.
After these values are defined for the variables, they are passed as parameters to
the CMDBAttribute class constructor, which creates a Java instance of the attribute.
In the example, the Cost attribute is created to hold the cost information for the
phoneSystemClass class. Similar to the ACMESerialNumber definition, the attribute
name, field ID, entry mode, and attribute limit details are specified for the Cost
attribute.
The entry mode for the Cost attribute is defined as Optional. The attribute data
type is defined as Currency. After the attributes for a specific class are defined as
CMDBAttribute variables, these attributes are added to a hash map. These hash
maps can hold multiple attributes at a time.
The setAttributes method of the phoneSystemClass is used to set the attributes for
the class. The hash map array, which holds the attribute definitions, is passed to
this setAttributes method as a parameter. After the attributes are set in the class,
the class information is updated in the BMC Atrium CMDB using the update
method of the phoneSystemClass.
For more information about the setAttributes method of the CMDBClass Java class,
data types, and data limits, open index.html of the Java API Help, which is located
in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.

Chapter 3 Programming common BMC Atrium CMDB tasks

35

BMC Atrium CMDB 2.1.00

Creating a CI instance
After you create a class in the BMC Atrium CMDB, you can create an instance of
this class. When you create an instance, you must specify all the required attributes
for the class. The following code illustrates how to create an instance of the
phoneSystemClass.
Example: Creating a CI instance
//Create variables to hold the serial number and cost details for the
instance
String serialNum = "SN-1492-22919";
Value cost = new Value("12.95",Constants.AR_DATA_TYPE_CURRENCY);
CMDBAttributeValue serialNumAttrValue = new
CMDBAttributeValue(serialNumAttrName, serialNum);
CMDBAttributeValue costAttrValue = new
CMDBAttributeValue(costAttrName, cost);
//Create a HashMap to hold the attribute values
Map attributeHashMap = new HashMap();
attributeHashMap.put(serialNumAttrName, serialNumAttrValue);
attributeHashMap.put(costAttrName, costAttrValue);
// create an instance of a phoneSystemClass
CMDBInstance phoneInstance = new CMDBInstance(phoneSystemClassNameKey,
attributeHashMap);
//create a variable to hold the dataset ID
String acmeDatasetId = "ACME.DATASET";
try {
//Create the new instance within the BMC Atrium CMDB
phoneInstance.create(currentUser, datasetId);
}
catch (ARException ex) {
System.out.println(ex.toString());
}
//Get the instance ID of the new instance
String phoneSystemInstId = phoneInstance.getId();

In the example, the serialNum and cost variables are created to hold the serial
number and cost information for the instance. The serialNumAttrValue and
costAttrValue class variables are created of type CMDBAttributeValue.
After the attribute name and other attribute information is created as explained in
the previous section, the serialNumAttrName and serialNum variables are assigned
to the serialNumAttrValue variable, which is of type CMDBAttributeValue. The
costAttrValue class variable holds the costAttrName and cost details for the
instance.
Using a hash map, the serial number and cost details are added to the
phoneInstance instance, which is of type CMDBInstance. To create the new instance
in Java, the phoneSystemClassNameKey, which was shown in Creating a CI class
on page 32, and attributeHashMap variables are passed as parameters to the
instance.
36

Developers Reference Guide

Working with relationship classes and instances

Before creating the phoneInstance instance in the BMC Atrium CMDB, a dataset
variable is created to specify the dataset to which the instance belongs. In the
example, the acmeDatasetId variable is created that holds the dataset details.
Because an instance must reside in a dataset, you must specify a dataset ID for the
instance.
In the try loop, the phoneInstance instance is created in the BMC Atrium CMDB.
The currentUser and datasetId parameters are passed to the create method of the
instance.
After the instance is created in the BMC Atrium CMDB, the instance ID of the new
instance is retrieved using the getId method.
For more information about the parameters for the create method of the
CMDBInstance Java class, open index.html of the Java API Help, which is located in
the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.

Working with relationship classes and

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

Creating a relationship class

When defining the relationship class, you can specify several characteristics for the
relationship, such as the cardinality of the relationship, for example one-to-many
or one-to-one, or whether the class defines a weak relationship.
In the following example, a relationship class is created between the
phoneSystemClass class and the socketClass class.
Example: Creating a relationship class
//Create a variable that holds the relationship class name
String relationshipClassName = "phoneSystemToSocketRelationship";
CMDBClassNameKey relationshipClassKey = new
CMDBClassNameKey(relationshipClassName, acmeNamespace);
//Create a variable that holds the two classes that will be related
CMDBClassNameKey[] relationshipClasses = {phoneSystemClassKey,
socketClassKey};
//create a role name for each instance in the relationship
String[] roleNames = {"Source", "Destination"};
//create the relationship class

Chapter 3 Programming common BMC Atrium CMDB tasks

37

BMC Atrium CMDB 2.1.00

CMDBRelationship phoneSystemToSocketRelClass = new

CMDBRelationship(relationshipClassKey, null,
roleNames, relationshipClasses);
//set the cardinality of the relationship
phoneSystemToSocketRelClass.setCardinality(
CMDBRelationship.CMDB_CLASS_RELATIONSHIP_CARDINALITY_1_MANY);
try {
// create the relationship class in the BMC Atrium CMDB
phoneSystemToSocketRelClass.create(this.getARServerUser());
}
catch(ARException ex){
System.out.println(ex.toString());}

In the example, the relationshipClassName variable is created to hold the name of

the relationship class. The relationshipClassKey variable, which is of type
CMDBClassNameKey, is created to define the class name and namespace details for the
relationship class.
The class name and namespace information for the two classes that will be related
in the relationship class is specified in the relationshipClasses variable. The role
names for the two classes are specified in the roleNames variable.
Each of the two classes in a relationship must have its role defined. You can define
role names for Class 1 and Class 2, known respectively as the source and
destination members of the relationship. The BMC Atrium CMDB prepends these
role names to the attributes of a relationship class that pertain to its members. For
example, on any CDM relationship class the attributes that hold the class IDs of its
member CIs are named Source.ClassId and Destination.ClassId.
After the role name and class name key details are defined, the
instance of the relationship class is created,

phoneSystemToSocketRelClass Java
which of type CMDBRelationship.

The setCardinality method of the CMDBRelationship class sets the cardinality. In

this example, the cardinality for the relationship class is set to one-to-many. A oneto-many cardinality means that for each instance of the phoneSystem class, there
can be many relationships to instances of the socket class.
In the try loop, the phoneSystemToSocketRelationship relationship class is then
created in the BMC Atrium CMDB.
For more information about the parameters for the create method of the
CMDBRelationship Java class, open index.html of the Java API Help, which is
located in the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation
directory.

38

Developers Reference Guide

Working with relationship classes and instances

Creating a relationship between two CI instances

To create a relationship between two CI instances, you create a relationship
instance. An instance of a relationship class defines a specific relationship between
two particular instances of two CI classes. The following code illustrates how to
create a relationship between two CIs.
In the following example, it is assumed that the newPhoneSystem and newSocket
variables, representing existing CI instances, the phoneClassId and the
socketClassId variables are already created.
Example: Relating two CIs
//retrieve the instance IDs for the newPhoneSystem and newSocket
instances
String phoneInstId = newPhoneSystem.getId();
String socketInstId = newSocket.getId();
//create the required attributes of the relationship instance
CMDBAttributeValue srcInstId = new
CMDBAttributeValue("Source.InstanceId", new
Value(phoneInstId));
CMDBAttributeValue destInstId = new
CMDBAttributeValue("Destination.InstanceId", new
Value(socketInstId));
CMDBAttributeValue datasetId = new
CMDBAttributeValue("DatasetId", new Value(acmeDatasetId));
Map attrHashMap = new HashMap();
attrHashMap.put(srcInstId.getAttributeName(), srcInstId);
attrHashMap.put(destInstId.getAttributeName(), destInstId);
attrHashMap.put(datasetId.getAttributeName(), datasetId);
// create a Java instance of the relationship class
CMDBInstance relInstance = new
CMDBInstance(relationshipClassKey, attrHashMap);
try {
//Create an instance of the class within the BMC Atrium CMDB
relInstance.create(this.getARServerUser());
}

In the example, the phoneInstId and socketInstId variables are created to hold the
instance IDs of the newPhoneSystem and newSocket instances. The srcInstId and
destInstId variables are created to hold the IDs of the source and destination
classes, which are phoneInstId and socketInstId respectively.
The datasetId variable holds the dataset ID of the ACME dataset. These source,
destination, and dataset ID variables are written to the attrHashMap array. The Java
instance of the relationship class is then created using the constructor of the
CMDBInstance class.
In the try loop, the relationship instance is created in the BMC Atrium CMDB. The
getARServerUser method of the relInstance instance retrieves the user ID that is
currently used to log in to the AR System server. The user ID parameter is required
to create the instance in the BMC Atrium CMDB.

Chapter 3 Programming common BMC Atrium CMDB tasks

39

BMC Atrium CMDB 2.1.00

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

Retrieving instance details

You can query CI and relationship instances that exist in the BMC Atrium CMDB.
The following code illustrates how to query instances of the phoneSystemClass
class.
Example: Querying an instance
//Set specific attributes to return
String[] attributesToGet =
{"InstanceId",
"ReconciliationIdentity",
"DatasetId"};
//Specify values for the query to retrieve all instances where DatasetId
//is ACME.DATASET
String query = "'DatasetId' = \"ACME.DATASET\"";
try {
CMDBInstance[] instanceList = CMDBInstance.findObjects(
this.getARServerUser(),
phoneSystemClassKey,
query,
attributesToGet,
null, //do not sort
CMDB_START_WITH_FIRST_INSTANCE,
CMDB_NO_MAX_LIST_RETRIEVE,
Null);
}
catch(ARException ex){
System.out.println(ex.toString());
}

In the example, the attributes to retrieve in the query are specified in the
attributesToGet array of type String. The query in this example retrieves the
InstanceID, ReconciliationIdentity, and DatasetID attributes from all instances.
If no attributes are specified to return in the query, all attributes of the instances
will be returned by default.
The query variable specifies a qualification that will retrieve all instances where the
dataset ID is ACME.DATASET. In the try loop, the findObjects method of the
CMDBInstance Java class is used to retrieve instances. The retrieved instances are
placed in the instanceList array, which is of type CMDBInstance.
For more information about the parameters for the findObjects method of the
CMDBInstance Java class, open index.html of the Java API Help, which is located in
the sdk/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.

40

Developers Reference Guide

Chapter

BMC Atrium CMDB tools

This section describes how to use the various BMC Atrium CMDB tools.
The following topics are provided:

Working with the cmdbdriver program (page 42)

Migrating data between BMC Atrium CMDB servers (page 45)
Using the extension loader (page 53)
Integrating the CI Relationship Viewer with other applications (page 63)
Configuring the CI Relationship Viewer (page 69)
Creating CMDB status alerts (page 75)
Importing data with Integration Engine (page 76)
Working with SQL views (page 77)
Debugging BMC Atrium CMDB API programs using print.c routines (page 78)

Chapter 4

BMC Atrium CMDB tools

41

BMC Atrium CMDB 2.1.00

Working with the cmdbdriver program

The cmdbdriver program, which prompts you one at a time for parameters to each
command you type, enables you to execute various BMC Atrium CMDB API
functions from a command line, such as class, instance, and attribute data
manipulation. Figure 4-1 on page 43 displays the list of tasks that you can perform
with the cmdbdriver program.
The parameters that are required for cmdbdriver commands are the same as the
parameters that are required for the equivalent C API functions. For more
information about API functions and their parameters, see Chapter 5, C API
functions and data structures.

From the command line

Once you compile the source code or locate the prebuilt program supplied with the
API, you are ready to use the cmdbdriver program. When you execute the program,
the system displays the list of cmdbdriver commands.
You must provide the necessary login information and perform initialization
operations for connecting to the BMC Atrium CMDB. You can then use the
cmdbdriver commands to call any number of API functions. When you are working
with the specific commands, see Chapter 5, C API functions and data structures,
to enter the appropriate values for the function parameters. If you are working
with specific entries, use leading zeros to see the entry ID of those entries.

To use the cmdbdriver program (Windows and UNIX)

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

Windows

Navigate to C:\Program

Files\AR System Applications\<server_name>\BMC

Atrium CMDB\sdk\bin.

Double-click cmdbdriver.exe.

UNIX

Navigate to /usr/arsystem/<server_name>/cmdb/sdk/bin.

Type the command cmdbdriver.

42

Developers Reference Guide

Working with the cmdbdriver program

Figure 4-1: Initial screen of cmdbdriver

2 Initialize an API session with the init command.

3 Specify the login parameters with the log command.

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

Type a valid user name and password.

Type the name of your server.
You can skip the other parameters. After you specify the login parameters, the
command prompt appears.
4 Type the abbreviation of the function and provide the appropriate input parameter

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

Chapter 4

BMC Atrium CMDB tools

43

BMC Atrium CMDB 2.1.00

Using a script
You can also use a script file that contains the cmdbdriver commands and execute
it at the cmdbdriver prompt. You can create this script file using any text editor,
such as Notepad or Wordpad.
Example 1: cmdbdriver script fileImport definitions command
impdf
2
1
BMC.CORE
BMC_ComputerSystem
1
BMC.CORE
BMC_SystemComponent
1
C:\ImportClasses

This example uses a script to import the BMC_ComputerSystem and

BMC_SystemComponent classes from the BMC.CORE namespace. To accept a
default value for a parameter in the cmdbdriver script, insert a blank line.
Example 2: cmdbdriver script fileGet List Class command
glc
BMC.CORE
BMC.CORE
BMC_System
BMC.CORE
BMC_Component
T

This example uses a script to retrieve the destination CI for the BMC_System
source class. BMC_Component is the relationship between these CIs and both
these classes exist within the BMC.CORE namespace. To accept a default value for
a parameter in the cmdbdriver script, insert a blank line. The blank line in this
example accepts the default value for the Number of characteristics parameter.
The default for this parameter is set to 0 (none).
You can use the rec and srec commands of the cmdbdriver program to record
cmdbdriver commands. The rec command starts recording the commands you use
at the prompt and srec stops recording these commands.
When you type the rec command, you are prompted for the name of the file in
which to store these commands. After you record the commands in a file, you can
execute it at the cmdbdriver program using the execute command.

44

Developers Reference Guide

Migrating data between BMC Atrium CMDB servers

Using cmdbdriver on UNIX

The cmdbdriver program requires specific shared libraries in the bin subdirectory
of the BMC Atrium CMDB installation directory. By default, this subdirectory is
located at /usr/arsystem/<server_name>/cmdb/sdk/bin.
These shared libraries are not added in the library path when you install BMC
Atrium CMDB. To add them to the library path, you need to set the appropriate
library path variable using setenv or export command.
The variable that you need to set varies for each UNIX platform. Table 4-1 lists the
various UNIX platforms and their corresponding variables.
Table 4-1: UNIX platforms and corresponding Library Path variables
UNIX platform

Variable name

Solaris and Linux

LD_LIBRARY_PATH

HPUX

SHLIB_PATH

AIX

LIBPATH

Migrating data between BMC Atrium CMDB

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

NOTE
The procedure explained in this section covers the steps for migrating only BMC
Atrium CMDB definitions and data. If you have other BMC Software applications
installed on your development server that access the BMC Atrium CMDB, such as
BMC Remedy Asset Management, you need to migrate that data separately.
Migrating your BMC Atrium CMDB from a development server to a production
server requires the following high-level steps:
Step 1 Export class data with cmdbdriver (see page 47).
Step 2 Export instance data with cmdbdriver (see page 48).
Step 3 Import class data with cmdbdriver (see page 49).
Step 4 Import instance data with cmdbdriver (see page 50).

Chapter 4

BMC Atrium CMDB tools

45

BMC Atrium CMDB 2.1.00

Step 5 Export reconciliation information with BMC Remedy User (see page 50).
Step 6 Import reconciliation information with BMC Remedy Import (see page 52).

For information about known issues regarding the procedure explained in this
section, see Known issues on page 52.
You can use cmdbdriver scripts to perform some of these steps.

Logging in to the cmdbdriver program

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

To log in to the cmdbdriver program

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

Windows

Navigate to C:\Program

Files\AR System Applications\<server_name>\BMC

Atrium CMDB\sdk\bin.

Double-click cmdbdriver.exe.

UNIX

Navigate to /usr/arsystem/<server_name>/cmdb/sdk/bin.

Type the command cmdbdriver.
2 Type the command init to initialize the driver.
3 Type the command log to log into your development server.

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

Type a valid user name and password.

Type the name of your server.
You can leave the other parameters blank. After you specify the login parameters
the command prompt appears.
4 Type the abbreviation of the function and provide the appropriate input parameter

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

46

Developers Reference Guide

Migrating data between BMC Atrium CMDB servers

Step 1Exporting 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 3Import class definitions with cmdbdriver on page 49.

To export definitions for a class and its subclasses

1 Log in to your development server.
2 Start the cmdbdriver program and specify your user credentials.

For more information about logging in to the cmdbdriver program, see Logging in
to the cmdbdriver program on page 46.
3 Type the xexpdf command.
4 At the Export all class? (F): prompt, type T to export all class definitions from

the BMC Atrium CMDB.

If you press Enter to accept the default value of F, you need to specify the
namespace, class, and attribute details for which you want to export the class
definitions.
5 At the Export all attributes with classes? (T): prompt, press Enter to accept

the default value of True.

6 At the Filename for exported data: prompt, specify the file name in which to save

the exported definitions.

Make sure you specify the exact path for the file name, for example,
you specify a file
name that already exists, the contents of the file is overwritten.

c:\ExportedClassDefinitions\CoreClassDefinitions.xml. If

Chapter 4

BMC Atrium CMDB tools

47

BMC Atrium CMDB 2.1.00

Step 2Export instance data with cmdbdriver

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

To export instance data for a class

1 Log in to your development server.
2 Start the cmdbdriver program and specify your user credentials.

For more information about starting the cmdbdriver program, see Logging in to
the cmdbdriver program on page 46.
3 Type the xexpdt command to export instance data from the BMC Atrium CMDB.
4 At the Export instance data from all classes? (F): prompt, type T to export all

instance data.
If you press Enter to accept the default value of F, you need to specify the
namespace, class, and attribute details for which you want to export the class
definitions.
5 At the Dataset ID (): prompt, type the dataset ID from which you want to export

the instance data.

6 At the Filename for exported data: prompt, specify the file name in which to save

the exported instance data.

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

48

Developers Reference Guide

Migrating data between BMC Atrium CMDB servers

Step 3Import class definitions with cmdbdriver

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

To import class definitions

1 Log in to your production server.
2 Start the cmdbdriver program and specify your user credentials.

For more information about logging in to the cmdbdriver program, see Logging in
to the cmdbdriver program on page 46.
3 Type the impdf command to import class definitions into the BMC Atrium CMDB.
4 Specify the directory path where the import data is located, such as
c:\ExportedClassDefinitions.

5 To import all class definitions contained in the source folder (recommended),

accept the default of 0 and skip to step 8. To import definitions for a specific class,
type 1 for the Number of Import Items.

NOTE
When you enter a number other than 0, you cannot automatically import the
subclasses of a specified class. Each subclass must be specified as a separate import
item, either by increasing the number you specify here or by running the impdf
command multiple times.
6 To import a class from the source folder, accept the default value of 1.

To import attributes for the class, run the impdf command again and type 2 at this
prompt.
7 At the Class Name prompt, type the namespace and class name for the class, for

example, BMC.CORE. and BMC_BaseElement respectively.

8 Accept the default value of 1 to import Metadata.
9 Type any of the following import options:

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

2 (Overwrite)Overwrite

the existing class in the BMC Atrium CMDB.

The definition is imported.

Chapter 4

BMC Atrium CMDB tools

49

BMC Atrium CMDB 2.1.00

Step 4Import instance data with cmdbdriver

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

To import instances of a class or classes

1 Log in to your production server.
2 Start the cmdbdriver program and specify your user credentials.

For more information about logging in to the cmdbdriver program, see Logging in
to the cmdbdriver program on page 46.
3 Type the impdt command to import instance data into the BMC Atrium CMDB.
4 Type any of the following import options to specify the action to take when an

instance to be imported has the same Instance ID as an existing instance in the

BMC Atrium CMDB:

1 (Error on dup)If

2 (Generate new ID on dup) If the instance already exists with the same
Instance ID, generate a new Instance ID and import the instance.

3 (Merge on dup) If the instance already exists with the same Instance ID,
merge the new instance and the existing instance.

4 (Generate new ID for all)Create a new Instance ID for the instance to

import even if the new instance is not a duplicate.

the instance already exists with the same Instance ID,

generate an error message and do not import the instance.

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

The data is imported into the BMC Atrium CMDB.

Step 5Export reconciliation definitions

You can export reconciliation definitions from one server and import them onto
another server instead of manually recreating all your definitions. You can export
all your reconciliation definitions, or select one or more definitions of a certain
type.

NOTE
When exporting definitions, make sure you save them in an AR Export (.arx)
format. If you use comma-separated values (.csv), or XML (.xml) formats, the
resulting files will not import correctly using the arimportcmd command. For more
information about AR Export files, see the BMC Remedy Action Request System
7.1.00: Form and Application Objects guide.

50

Developers Reference Guide

Migrating data between BMC Atrium CMDB servers

Any definitions used by those you select are also exported. For example, if you
select a job, the export will include that job plus all the activities in it, plus all the
rulesets in those activities, and so on.
You can export reconciliation definitions either using BMC Remedy User or a
browser. When exporting definitions from a browser, several file dialogs might
appear, depending on the definitions you export. Each dialog box requires you to
enter an export filename for a particular definition.

NOTE
Due to the browser limitation, BMC recommends that you use BMC Remedy User
for exporting reconciliation definitions.

To export reconciliation definitions

1 Using BMC Remedy User, open the CMDB Console.
2 Click the Reconciliation Manager tab and choose the Export Definitions link from

the left navigation pane.

3 Select an Export Type:

EverythingAll definitions.

JobSelected jobs and the definitions used by them.

GroupSelected Identification groups, Qualification groups, Precedence
groups, and Workflow Execution groups and the definitions used by them.

DatasetAll datasets.

DatasetMergePrecedenceSetSelected 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 5Export reconciliation definitions on page 50.
If you include no path or a relative path, the file is placed in or under the BMC
Remedy User application folder.
6 Click Export.

The definitions are exported.

TIP
If you encounter errors when exporting reconciliation definitions, see the BMC
Atrium CMDB 2.1.00 Troubleshooting Guide to correct them.

Chapter 4

BMC Atrium CMDB tools

51

BMC Atrium CMDB 2.1.00

Step 6Import reconciliation definitions

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

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

To import reconciliation definitions

1 Open a command prompt.
2 If using Windows, change to the directory where BMC Remedy Import and other

AR System clients are installed.

The default directory is c:\Program Files\AR System.
3 Enter the command:
arimportcmd -x <server_name> -u <user_name> -p <password> -o <import_file>
-l <log_file> -e 179 -D 4

For <import_file>, specify the full path to the file containing the exported
definitions from the procedure To export reconciliation definitions on page 51.
Specifying a log file is optional, but recommended in case there are any errors with
the import.
The -e 179 option enables you to verify whether a definition you are importing
already exists. This check is performed based on the globally unique identifier
(GUID) values. Specifying the -D4 option updates an entry if a match is found. If
no match is found, a new entry is created. For more information about the various
options for the arimportcmd command, click the Help menu in BMC Remedy
Administrator and search for the command.

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

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

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

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

Developers Reference Guide

Using the extension loader

Using the extension loader

The cmdbExtLoader program enables you to install one or more of BMC Atrium
CMDB classes from one server to another. You use the extension loader either to
extend the BMC Atrium CMDB or to install an extension pack. For information
about the guidelines for extending the CDM, see the Concepts and Best Practices
Guide.
The extension loader program can also install objects other than the data model
extensions. However, this guide covers only the instructions for installing class
and attribute extensions. For more information about importing data into
AR System forms, see the BMC Remedy Action Request System 7.1.00: Configuring
guide.
If you encounter errors when using the extension loader to install the extensions,
see the Troubleshooting Guide to correct the issues.

The extension loader directory structure

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

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

NOTE
You must name the directory that contains the extension subdirectories as
extensions. If you specify any other name for this directory, the extension loader
will not recognize it.
After you copy the extension loader files into the extension loader directory you
created, you create an extensions directory, as displayed in Figure 4-2. The
extensions directory can contain one or more extension subdirectories.
Each extension subdirectory can contain a package.xml file, an installation activity
file, and one or more class XML files. These class files are obtained when you use
the expdf command of the cmdbdriver program to export the class or attribute
definitions.

Chapter 4

BMC Atrium CMDB tools

53

BMC Atrium CMDB 2.1.00

The following naming convention is used for extension subdirectories:

<install-order>-<name>

where:

<install-order> is a three-digit number ranging from 000 to 999. The <installorder> instructs the extension loader to install the objects in the extensions
directory in ascending order. Therefore, you must specify a lower <installorder> for the object that you want to install first.

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

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

<name>

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

Packaging and installing BMC Atrium CMDB extensions

Packaging and installing your BMC Atrium CMDB extensions requires the
following high-level steps:
Step 1 Export the class definitions with cmdbdriver (see page 54).
Step 2 Create the package.xml file (see page 55).
Step 3 Create an installation activity file (see page 57).
Step 4 Start the cmdbExtLoader program (see page 59).

Step 1Export the class definitions using the

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

To export class definitions

1 Create an extension subdirectory.

See The extension loader directory structure on page 53. This directory will
contain all the extension loader files.
2 Export the class definitions using the cmdbdriver expdf command.

For more information about exporting class definitions with the cmdbdriver
program, see Step 1Exporting class data with cmdbdriver on page 47.
The expdf command creates several XML files that contain the class definition
information for the specified class.

54

Developers Reference Guide

Using the extension loader

Step 2Create the package.xml file

The package.xml file contains the registration and dependency information for the
extension. The registration information defines the extension that you are creating.
When the extension loader runs, it stores the extension registration values that you
specify in the package.xml file, such as the extension name, version, and GUID in
the SHARE:Application_Properties AR System form.
A GUID is a unique ID for the extension. This ID is used by the extension loader
program to determine if an extension is already installed. After you create an
extension with a specific GUID, you can only change the version number to update
the extension. The GUID will remain the same for the life span of an extension.
Example: package.xml
<?xml version="1.0" standalone="yes" ?>
<package>
<!-- This extension adds a class.-->
<name> ComSys Hardware Component</name>
<guid>OS005056C0000898YWQgUsMLAAKwAA</guid>
<version>1.0</version>
<dependencies>
<applications>
<list>cmdb</list>
<!-- Requires CMDB -->
<cmdb>
<guid>OB00C04FA081BABZlxQAmyflAg1wEA</guid>
<name>BMC Atrium CMDB</name>
<minversion>2.1.00</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.1.00. The first line of code is an xml version tag that is
required for all XML files.

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

Chapter 4

BMC Atrium CMDB tools

55

BMC Atrium CMDB 2.1.00

To create the package.xml file

1 Depending on whether you are creating a new extension or modifying an existing

extension, perform one of the following steps:

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

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

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

Registration informationSpecify the following registration information for the

extension:

<name>The

<guid>The

<version>The version number for the extension. Modify the version

number only if you are modifying an extension.

name for the extension.

GUID for the extension. For new extensions, specify the GUID
that you created in step 1. For existing extensions, specify the currently
existing GUID.

DependenciesSpecify 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 1Export the class definitions using the cmdbdriver.

56

Developers Reference Guide

Using the extension loader

Step 3Create 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 655EXClass, 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:

IMPImport data into an AR System form

ARDAR System driver script

OSDcmdbdriver script

RIKRemedy Installation Kit

<suffix> is the file extension for the installation activity file. The file extensions
for the activity file include:

XMLThe file extension for the RIK file must be of type XML.

Other typesThe file extension for all other activities (IMP, ARD, and OSD)
can be of any type such as txt.
An example of an activity file name is 500-CLASS-OSD.txt.
Every installation activity file you create must contain the oout and cout
commands. The oout command instructs the extension loader to log the script
actions. You must specify the OSDriver.out output filename with the oout
command, as illustrated in the example, to save the script actions.
After the script stops executing the activity file, the extension loader reads these
log comments to verify whether the script execution was successful. The cout
command closes the log entry file.

Chapter 4

BMC Atrium CMDB tools

57

BMC Atrium CMDB 2.1.00

Example: Activity file

oout
OSDriver.out
imp
//activity type
1
// Number of class or instance defintions to import
TEST
// Class name
SampleClass // Namespace
1
// metadata or instance data choice. 1 indicates
metdata.
.
cout
term
q

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

To create an installation activity file

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

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

IMPORTANT
If you create the activity file in Windows format, make sure you use the DostoUnix
command to convert the file from Windows format to UNIX before you run it.
2 Type oout and OSDriver.out output file name in the beginning of the file as shown

in the previous example.

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

IMPORTANT
You must name the output file for the oout command as OSDriver.out. If you
specify any other file name, the extension loader program generates an error.
3 Specify the type of activity the extension loader must perform, such as ARD or OSD.
4 Specify the number of class definitions or instance data objects you want to export

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

58

Developers Reference Guide

Using the extension loader

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

You can use the cmdbdriver program for the import and export function
parameters. For more information about the cmdbdriver program, see Working
with the cmdbdriver program on page 42.
7 Save the activity file under the extension subdirectory you created in step 1 with

an xml, txt, or any other type of extension, depending on the activity type.
For more information about the activity file extensions, see Step 3Create an
installation activity file on page 57.
The Extensions subdirectories will now contain a package.xml file, an installation
activity file, and the XML files, which were created when you exported your
classes using the cmdbdriver program.

Step 4Start the cmdbExtLoader program

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

To start the cmdbExtLoader program

1 Depending on your environment, perform any of the following steps to start the

extension loader:

On Windows

Double-click cmdbExtLoader.exe from the directory in which you copied the
extension loader program.

On UNIX

Using the command prompt, navigate to the directory in which you copied
the extension loader program.

Type ./cmdbExtLoader to run the extension loader program.

NOTE
To install the extension loader on a UNIX machine, follow the prompts. For
information about the parameters you need to provide, see step 4 on page 60.
The Welcome screen of the extension loader installation wizard appears.
2 Click Next.

The Software License Agreement screen appears.

3 Click I Agree.

The AR Server Connection Information screen appears, as displayed in Figure 4-3

on page 60.

Chapter 4

BMC Atrium CMDB tools

59

BMC Atrium CMDB 2.1.00

Figure 4-3: AR Server Connection Information screen

4 Specify the following details:

AR Server NameType the AR System server on which you want to install the
extensions.

Port NumberIf you specified a port number when installing the AR System
server, type that number in this field. If the server uses a portmapper to
automatically select a port to use, leave this field blank.

RPC Port NumberIf you specified an RPC port number when installing the
AR System server, type that number in this field.
5 Click Next.

The Administrator Logon Information Required screen appears.

6 Specify an Administrator user name and password in the User Name and

Password fields respectively.

The extension loader program begins installing the extensions. Depending on
whether the installation was successful, one of the following installation status is
displayed in the Package Load Summary screen:

SUCCESSThe extensions are successfully installed on the server.

DEPENDENCY FAILUREThe dependency details that you specified in the
package.xml file such as, guid and minversion is incorrect. For specific details
about the failure, see the cmdbext_install.log, which is located in the %temp%
directory of your machine.

60

Developers Reference Guide

Using the extension loader

NOTE
%temp% is an environment variable that is already set when you install the operating

system. To access this folder, open Windows Explorer and type %temp% in the
Address list.

SKIPPEDThe extensions that you are attempting to install on the specified

server is already installed.

NOTHING TO LOADThe extensions folder did not contain any extensions to

be installed. When you use only the package.xml file, excluding the extensions,
to add an entry in the SHARE:Application_Properties form, this message is
displayed. You could use this option when one of the components of your
application did not change, but you want to update its version number to match
the version of the changed components.

FAILUREThe extensions installation failed because of an error in any of the

activity files. For more information about the activity files, see the section,
Step 3Create an installation activity file on page 57.
Figure 4-4: Installation statusPackage Load Summary screen

Chapter 4

BMC Atrium CMDB tools

61

BMC Atrium CMDB 2.1.00

7 Click Next.

The Setup Complete screen is displayed.

8 Click Finish.

To view the installation log files, open Windows Explorer and type %temp% in the
Address list. The log file is named as cmdbext_install.log.

Verifying your installed extensions

If your extensions are successfully installed on the server, you can view an entry
for the application that added the extensions in the
SHARE:Application_Properties form, as displayed in Figure 4-5.
Figure 4-5: SHARE:Application_properties formInstalled extensions

To verify whether your extensions installed successfully

1 Log on to the AR System server on which you installed the extensions using BMC

Remedy User.
For more information about how to log on to the BMC Remedy User, see the Users
Guide.
2 Press CTRL+O on your keyboard to display the Object List window.
3 In the Search what keywords? field, type share.

62

Developers Reference Guide

Integrating the CI Relationship Viewer with other applications

4 From the list below, double-click the entry for SHARE:Application_Properties.

The SHARE:Application_Properties is displayed in Search mode.

5 In the Property Name field, type name and click Search.

A list of entries for various applications that are installed on the server is displayed
in the result section of the SHARE:Application_Properties form.
6 Click the entry that pertains to the application for which you installed the

extensions.
7 Verify the details of the extension such as Name and Version.

Integrating the CI Relationship Viewer with

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

AR System applications

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

Embed CI Relationship Viewer in AR System applications. In this method, the

CI Relationship Viewer field is embedded in the AR System application itself
(see page 66).

Non-AR System applications

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

TIP
To view version details for the CI Relationship Viewer, type java jar
civiewer.jar at the command line prompt. For information about version details,
see the Troubleshooting Guide.

Chapter 4

BMC Atrium CMDB tools

63

BMC Atrium CMDB 2.1.00

Launching the CI Relationship Viewer from AR System

applications
When you launch the CI Relationship Viewer form from other AR System
applications, the BMC Atrium CMDB performs the initialization function for the
CI Relationship Viewer. You must specify the initialization parameters, such as
Namespace, Class Name, Dataset ID, CI ID, and Filters of the CI for which the
relationship data will be displayed.
Table 4-2 lists the parameters required to launch the CI Relationship Viewer form
from other AR System applications.
Table 4-2: CI Relationship Viewer parametersAR System applications

64

Parameter name

Description

Namespace

The namespace to which the instance

belongs.

Class Name

The class name to which the instance belongs.

CI ID

The Instance ID of the CI for which the

relationship data will be displayed.

Dataset ID

The ID of the dataset where the instance

resides.

Filter Name

The filter name for the CI Relationship

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

Developers Reference Guide

Integrating the CI Relationship Viewer with other applications

To launch the CI Relationship Viewer from AR System applications

1 With BMC Remedy Administrator, log in to the BMC Atrium CMDB server and

create a new active link for launching the CI Relationship Viewer.

The properties for the active link are displayed in a tab form. For more information
about creating active links, see the BMC Software Remedy Action Request System
7.1.00: Workflow Objects guide.
2 On the Basic tab, specify details, such as the Form Name and Execute On criteria.
Figure 4-6: Setting CI Relationship Viewer parameters

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

From the New Action list, select Open Window.

From the Window Type list, select Search.

From the Target Location list, select New.

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

Chapter 4

BMC Atrium CMDB tools

65

BMC Atrium CMDB 2.1.00

From the Form Name list, select CMDB:CIViewer.

In the Field Mapping section, specify the parameters listed in Table 4-2 on
page 64.
4 Click Add Action.
5 On the Permissions tab, specify permissions for the active link.
6 On the BMC Remedy Administrator toolbar, click the Save icon.

Your active link is now saved.

Embedding the CI Relationship Viewer in AR System

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

To embed the CI Relationship Viewer in your AR System form

1 Using BMC Remedy Administrator, open the form in which you want to embed

the CI Relationship Viewer.

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

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

From the Module type list, select CI Viewer.

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

From the Definition Name list, select the data visualization definition you
created for the CI Viewer.
Select Default if you did not create any customized definitions. For more
information about creating definitions, see Creating a definition for the CI
Relationship Viewer on page 73.
4 On the Database tab, specify a name for the Data Visualization field in the Name

text box.
5 Create an active link that will be executed when the Data Visualization field is

initialized and specify the following details for the active link:

On the Basic tab:

Specify a name for the active link.

From the Form Name list, select the form name.

66

Developers Reference Guide

Integrating the CI Relationship Viewer with other applications

On the If Action tab:

From the New Action list, select Set Fields.

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

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

In the Value field, set the required parameters for launching the CI
Relationship Viewer, for example:
(((((((( "namespace=" + $Namespace$) + ",classname=") + $Class
Name$) + ",datasetid=") + $Dataset ID$) + ",instanceid=") + $CI
ID$) + ",filtername=") + Components and Dependencies

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

IMPORTANT
The namespace, classname, datasetid, instanceid, and filtername parameters are
CI Relationship Viewer-defined keywords.
6 Click Add Action to save the settings for the action.
7 Click Save to save the active link.

Launching the CI Relationship Viewer from non-AR System

applications
You can launch the CI Relationship Viewer directly from any non-AR System
applications using a browser. To launch the CI Relationship Viewer from a nonAR System application, you must specify the initialization parameters for the
viewer in the URL format.
In the URL for launching the CI Relationship Viewer, constants, such as
F490001100, indicate the field ID on the CI Relationship Viewer form. These IDs
are fixed values for the initialization parameters. Table 4-3 lists the parameters and
field ID mappings that are required to launch the CI Relationship Viewer form.
Table 4-3: CI Relationship Viewer parametersnon-AR System applications
Field ID

Parameter name

Description

F49000110f0

Namespace

The namespace to which the

instance belongs.

F400109900

Class Name

The class name to which the instance

belongs.

F431400000

CI ID

The Instance ID of the CI for which

the relationship data will be
displayed.

Chapter 4

BMC Atrium CMDB tools

67

BMC Atrium CMDB 2.1.00

Field ID

Parameter name

Description

F431400001

Dataset ID

The dataset from where the instance

data will be selected.

F431400003

Filter Name

The filter name for the CI

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

To launch the CI Relationship Viewer from a browser

1 Open a browser and type the following URL in the address field:
http://<midtier>/arsys/apps/<arserver>/AtriumCMDBConsole/
CMDB:CIViewer?F490001100=<namespace>&F400109900=<classname>&F431400000=<c
iid>&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 opens, as shown in Figure 4-7.

68

Developers Reference Guide

Configuring the CI Relationship Viewer

Figure 4-7: CI Relationship ViewerFrom 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 filtersAll and Components and
Dependencies. You can create custom filters using the Manage Filters link on the
CMDB Console. For more information about creating filters, see the Installation and
Configuration Guide.

Chapter 4

BMC Atrium CMDB tools

69

BMC Atrium CMDB 2.1.00

Customizing the configuration file

The settings that specify the visual and display definitions for the CI Relationship
Viewer are encapsulated in a configuration file. Although the CI Relationship
Viewer provides a default configuration file (config.xml) that contains standard
settings for the viewer, you can create a custom configuration file to suit your
needs.
After you create a configuration file, you add it as an attachment to the CI
Relationship Viewer definition, which is an entry in the Data Visualization
Definition form.
You customize the CI Relationship Viewer settings using the following steps:

Creating a configuration file on page 70

Creating a definition for the CI Relationship Viewer on page 73

Creating a configuration file

This section explains how to create a custom configuration file, which includes
settings, such as the context menu that displays various menu options, launch in
context, and color settings for the CI Relationship Viewer.
The following example specifies the format for defining a menu item:
Example: Menu item definition
<menuitem id="MNU_VIEW" textid=48070 text="View" enabled="false"/>

Where:

idUniquely

textidThe ID that is used in the AR

identifies the menu item.

System Message Catalog form to localize

the text.

textThe text string for the menu that will be displayed in the CI Relationship

Viewer. Enter a meaningful name for this attribute.

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

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

70

enabledUsed

to enable or disable the menu item. If you do not define this

attribute, the default value of true is accepted.

Developers Reference Guide

Configuring the CI Relationship Viewer

You can create submenus up to any number of levels. The example that follows,
shows a submenu definition.
Example: Submenu definition
<submenu id="SUBMENU_ID1" textid=48071 text="sub menu1">
<menuitem id="MNU_ID1" textid=48173 text="item1" action="action1"/>
<menuitem id="MNU_ID2" textid=48174 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-4 lists the menu or submenu items of the
CI Relationship Viewer along with their functions.

NOTE
The menu items listed in Table 4-4 are displayed in the context menu by default.
To hide any of submenus in the context menu pop-up, modify the config.xml file
or create a custom configuration file.
Table 4-4: Menu items and their functions
Action value

Function

Text displayed in the CI

Relationship Viewer

MNU_VIEW

Open the class form for the

selected instance

View

MNU_SET_AS_ROOT

Sets the currently selected CI as Set as Root

root

SUBMENU_LAUNCH

Submenu for showing the items Launch in Context

for Launch in Context

MNU_SEPARATOR

Separator

MNU_GRP_SHOWCI

Displays a window with a list of Select Items to Show

CIs

MNU_GRP_SHOWALL

Displays all the CIs for the

selected group

MNU_GRP_HIDEALL

Hides all the items for the group Hide all Items

SUBMENU_GRPITEMS

Lists all expanded groups for a

selected CI

Group Items

SUBMENU_LAYOUT

Submenu for showing the

layouts

Layout

MNU_LAYOUT_TREE

Tree Layout

Tree

MNU_LAYOUT_RADIAL

Radial Layout

Radial

MNU_REFRESH

Refreshes the Relationship

Graph

Refresh

A line

Chapter 4

Show all Items

BMC Atrium CMDB tools

71

BMC Atrium CMDB 2.1.00

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

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

NOTE
Do not add any menu items for the SUBMENU_LAUNCH menu option in the
configuration file. Based on the federation definitions, the menu items will be
dynamically added to SUBMENU_LAUNCH at run time.
The configuration, style, and context menu information must be placed within the
<config>, <style>, <contextmenu> element tags respectively. Table 4-5 explains the
various style attributes for the CI Relationship Viewer context menu.
Table 4-5: Context menu style attributes.
Style attribute name

Description

fontSize

The font size for the CI labels.

nodeSize

The default icon size for CI representation.

fill

The color for the links. When used in the link

element, it represents the default color.

width

The width of the link. When used in the link

element, it represents the default width.

text

The text to display in the legend.

The color scheme for the different relationship types should be placed inside the
<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.
Example: config.xml file
<config>
<style fontSize="10" nodeSize="35.f">
<link fill="#000000" width="1">
<BMC_Component textid="48060" text="Component" fill="#6C8A28"/>
<BMC_Dependency textid="48061" text="Dependency" fill="#9E0000"/>
<BMC_ElementLocation textid="48062" text="Element Location"
fill="#0069A5"/>
<BMC_MemberOfCollection textid="48063" text="Member of
Collection" fill="#1B2837"/>
</link>
</style>
<contextmenu>
<menuitem id="MNU_VIEW" textid="48070" text="View" enabled="false"/>
<menuitem id="MNU_SET_AS_ROOT" textid="48071" text="Set as Root"
enabled="false"/>
<submenu id="SUBMENU_LAUNCH" textid="48072" text="Launch in Context"

72

Developers Reference Guide

Configuring the CI Relationship Viewer

enabled="false"/>
<menuitem id="MNU_SEPARATOR"/>
<menuitem id="MNU_GRP_SHOWCI" textid="48078" text="Select Items to
Show" enabled="false" action="CIRV_NOTIFY_CIRV"/>
<menuitem id="MNU_GRP_SHOWALL" textid="48079" text="Show all Items"
enabled="false" action="CIRV_NOTIFY_CIRV"/>
<menuitem id="MNU_GRP_HIDEALL" textid="48080" text="Hide all Items"
enabled="false" action="CIRV_NOTIFY_CIRV"/>
<submenu id="SUBMENU_GRPITEMS" textid="48081" text="Group Items"
enabled="false"/>
<menuitem id="MNU_SEPARATOR"/>
<submenu id="SUBMENU_LAYOUT" textid="48073" text="Layout">
<menuitem id="MNU_LAYOUT_TREE" textid="48074" text="Tree"/>
<menuitem id="MNU_LAYOUT_RADIAL" textid="48075" text="Radial"/>
</submenu>
<menuitem id="MNU_REFRESH" textid="48077" 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-8 on page 73 is displayed in the CI
Relationship Viewer.
Figure 4-8: CI Relationship Viewer context Menu

Creating a definition for the CI Relationship Viewer

This section explains how to attach a configuration file to a CI Relationship Viewer
definition. You create a definition for the CI Relationship Viewer to apply the
settings you specified in the custom configuration file. This definition is created
using the Data Visualization Definition form.
After you create a definition for the custom configuration file, you must then
change the Definition Name on the Advanced tab of the CI Relationship Viewer
field properties to override the default definitions provided with the BMC Atrium
CMDB application.
For more information about creating a configuration XML file, see Customizing
the configuration file on page 70.

Chapter 4

BMC Atrium CMDB tools

73

BMC Atrium CMDB 2.1.00

To create a CI Relationship Viewer definition

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

mode.
2 Click Search on the form toolbar.

All existing Data Visualization Definition entries are listed in the results pane, as
displayed in Figure 4-9 on page 74.
Figure 4-9: Data Visualization Definition form

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

The default definition is displayed.

4 Choose Edit > Copy to New.

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

74

Developers Reference Guide

Creating CMDB status alerts

5 Specify the following details for the definition:

Definition NameA unique name for the definition.

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

DescriptionA description for the definition.

Complex DefinitionYour 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.

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

PriorityThe priority for the alert. You can choose from Low, Medium, or High.

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

Chapter 4

BMC Atrium CMDB tools

75

BMC Atrium CMDB 2.1.00

Importing data with Integration Engine

The BMC Atrium Integration Engine (Integration Engine) application enables you
to transfer data between a third-party data source and the BMC Atrium CMDB.
With Integration Engine, you perform scheduled bulk data transfers and eventbased integrations. You can use Integration Engine for initial data load,
incremental data transfers, and data synchronization.
Figure 4-10: Data exchange process

Third-party
data source

Data
object

AR System
database

BMC Atrium
Integration
Engine

CMDB
class

When you transfer data into the BMC Atrium CMDB, a database table and its
columns from the third-party data source are mapped to a BMC Atrium CMDB
class and its attributes respectively.
In general, this relationship is many-to-many because you can map different
columns from different data sources to different attributes in the same BMC
Atrium CMDB class.
For more information about EIE data transfer between a third-party data source
and the BMC Atrium CMDB, see the BMC Atrium Integration Engine 7.1.00
Administrators Guide.

76

Developers Reference Guide

Working with SQL views

Working with SQL views

SQL views are available to facilitate data access to the BMC Atrium CMDB from
third-party database clients. These views provide direct access to the database
tables for the various BMC Atrium CMDB classes, without having to know the
hierarchy of a given class.
For each database table in the AR System (except for the attachment tables), a
corresponding SQL view is automatically created. These views, which have the
same name as their underlying forms, are created using the following naming
rules:

Alphabetic and numeric characters remain as defined.

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

A leading A is appended to all view names that do not begin with an

alphanumeric character.

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

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

Abstract classes do not store any data. Therefore, abstract classes do not have
corresponding views.
For more information about SQL views and table naming conventions, see the
BMC Remedy Action Request System 7.1.00: Database Reference guide.

Chapter 4

BMC Atrium CMDB tools

77

BMC Atrium CMDB 2.1.00

Debugging BMC Atrium CMDB API programs

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

NOTE
See the function definitions in print.c to determine the specific parameters and
their types for these routines.
The print.h file contains a complete list of these routines.

78

Developers Reference Guide

Section

II

API reference

This section provides reference information for the C and web services APIs. The
Java API documentation is available in the Javadoc HTML files.
This section is organized into the following chapters:

Chapter 5, C API functions and data structures, provides information about

the functions and the data structures used in the C APIs.

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

Section II

API reference

79

BMC Atrium CMDB 2.1.00

80

Developers Reference Guide

Chapter

C API functions and data

structures
This section describes the C API functions.
The following topics are provided:

Related files (page 82)

Functions (page 82)

Data structures (page 158)

Chapter 5

C API functions and data structures

81

BMC Atrium CMDB 2.1.00

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

Functions
The CMDB C API functions are categorized by the type of actions these functions
perform. The function categories include data model, instance, and general
purpose functions, such as session, authentication, and import or export definition
functions.

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

Data model functions

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

CMDBCreateAttribute (page 83)

CMDBCreateMultipleAttribute (page 86)

CMDBDeleteAttribute (page 88)

CMDBGetAttribute (page 89)

CMDBGetMultipleAttribute (page 92)

CMDBSetAttribute (page 95)

CMDBSetMultipleAttribute (page 97)

CMDBCreateClass (page 99)

CMDBDeleteClass (page 101)

CMDBGetClass (page 102)

CMDBGetListClass (page 104)

CMDBSetClass (page 105)

82

Developers Reference Guide

Functions

CMDBCreateAttribute
Description
Privileges
Synopsis

Creates a new attribute with the specified name for the specified class.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBCreateAttribute(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

classNameID,

ARNameType

attributeName,

ARNameType

attributeId,

unsigned int

dataType,

ARInternalId

*arsubclassesId,

unsigned int

entryMode,

CMDBAttributeLimit

*attributeLimit,

ARValueStruct

*defaultValue,

ARPropList

*characList,

ARPropList

*customCharacList,

ARStatusList

*status)

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

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

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

attributeID
The ID of the attribute to create.

dataType
The datatype of the attribute to create.
1: Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD)
2:

Integer (CMDB_ATTR_DATA_TYPE_INTEGER)

3:

Real (CMDB_ATTR_DATA_TYPE_REAL)

Chapter 5

C API functions and data structures

83

BMC Atrium CMDB 2.1.00

4:

Character (CMDB_ATTR_DATA_TYPE_CHAR)

5:

Diary (CMDB_ATTR_DATA_TYPE_DIARY)

6:

Selection (CMDB_ATTR_DATA_TYPE_ENUM)

7:

Time (CMDB_ATTR_DATA_TYPE_TIME)

10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL)

11: Attachment (CMDB_ATTR_DATA_TYPE_ATTACH)
12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY)
13: Date (CMDB_ATTR_DATA_TYPE_DATE)
14: Time
37:

of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY)

Attachment pool (CMDB_ATTR_DATA_TYPE_ATTACH_POOL)

arsubclassesId
The AR System subclasses ID of the attribute to create. The IDs of all attributes
must be unique within the class. Specify 0 for this parameter if you want the
system to generate the ID.

entryMode
The entry mode for the attribute. Entry mode can be set to any one of the following:
required, optional, or display only.
1: Users must enter data when the
(CMDB_ATTR_ENTRYMODE_REQUIRED).

entry mode is set to required

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

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

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

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

84

Developers Reference Guide

Functions

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

1:

Users can specify a list of groups or roles that have permissions to view and
modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).

2:

3: Users can set the flag to false so that this attribute is hidden
(CMDB_ATTR_CHARAC_HIDDEN). This setting marks the atribute as hidden for a group

or a role. When querying for classes, you can retrieve hidden attributes. You can
specify one or more group IDs or role IDs for the permissions separated by a
semicolon, for example, 20;3.
The class ID and the attribute ID of the lead class attribute from which the
attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for
this value is <leadclassID>|<lead attribute>.

5:

6: CMDB_ATTR_CHARAC_CREATE_MODE
7:Users can set the audit option on
CMDB_ATTR_CHARAC_AUDIT_OPTION
9:Users can

to store the audit history for the attribute.

set the description for the attribute. CMDB_ATTR_CHARAC_DESCRIPTION

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

The number of items in the properties list.

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.

Chapter 5

C API functions and data structures

85

BMC Atrium CMDB 2.1.00

CMDBCreateMultipleAttribute
Description
Privileges
Synopsis

Creates multiple new attributes with the specified names for the specified class.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBCreateMultipleAttribute(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameID,

ARNameList

*attributeNameList,

ARNameList

*attributeIdList,

ARUnsignedIntList

*dataTypeList,

ARInternalIdList

*arsubclassesIdList,

ARUnsignedIntList

*entryModeList,

CMDBAttributeLimitList

*attributeLimitList,

ARValueList

*defaultValueList,

ARPropListList

*characListList,

ARPropListList

*customCharacListList,

ARStatusList

*status)

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

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

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

attributeIdList
The list of attribute IDs for the attributes being created.

dataTypeList
The list of data types for the attributes being created.

arsubclassesIdList
The AR System subclasses IDs of the attributes being created.

86

Developers Reference Guide

Functions

entryModeList
The list of entry modes for the attributes being created. Options include display
only, required, and optional.
1: Users must enter data when the
(CMDB_ATTR_ENTRYMODE_REQUIRED).

entry mode is set to required

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

4: Users cannot enter data when the entry

(CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).

mode is set to display only

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

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

characListList
A list of characteristics for each attribute. Characteristics include View
Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner,
Create Mode, Audit Option, and Description.
Users can specify a list of groups or roles that have permissions to view this
attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).When querying for attributes, you will
see all attributes, including the hidden attributes. You can specify one or more
group IDs or role IDs for the permissions separated by a semicolon, for example,
20;-5.
1:

Users can specify a list of groups or roles that have permissions to view and
modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).

2:

3: Users can set the flag to false so that this attribute is hidden
(CMDB_ATTR_CHARAC_HIDDEN). Marks a list of atributes as hidden

for a group or a
role. When querying for classes, you can choose to retrieve hidden attributes. You
can specify one or more group IDs or role IDs for the permissions separated by a
semicolon, for example, 20;3.
The class ID and the attribute ID of the lead class attribute from which the
attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for
this value is <leadclassID>|<lead attribute>.

5:

6: CMDB_ATTR_CHARAC_CREATE_MODE

Chapter 5

C API functions and data structures

87

BMC Atrium CMDB 2.1.00

7:Users can set the audit option on

CMDB_ATTR_CHARAC_AUDIT_OPTION
9:Users can

to store the audit history for the attribute.

set descriptions for the attributes. CMDB_ATTR_CHARAC_DESCRIPTION

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

The number of items in the properties list.

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.

CMDBDeleteAttribute
Description

Privileges
Synopsis

Deletes the attribute with the specified ID. Depending on the value you specify for
the deleteOption parameter, the attribute is deleted immediately and is not
returned to users who request information about attributes.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBDeleteAttribute(
ARControlStruct

Input
arguments

88

*control,

CMDBClassNameId

classNameID,

ARNameType

attributeName,

unsigned int

deleteOption,

ARStatusList

*status)

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

Developers Reference Guide

Functions

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

attributeName
The name of the attribute to delete.

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

Do not delete the attribute (AR_ATTRIBUTE_CLEAN_DELETE).

1: Delete if the attribute contains

(AR_ATTRIBUTE_DATA_DELETE).
2: Delete the attribute even if it
(AR_ATTRIBUTE_FORCE_DELETE).

Return values

data but not if it is inherited by subclasses

has subclasses that are associated with it

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

CMDBGetAttribute
Description
Privileges
Synopsis

Retrieves a single attribute.

CMDB administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetAttribute(
ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

attributeName,

ARNameType

attributeId,

unsigned int

*dataType,

unsigned int

*attributeType,

CMDBClassNameId

*baseClassNameId,

ARInternalId

*arsubclassesId,

unsigned int

*entryMode,

CMDBAttributeLimit

*attributeLimit,

ARValueStruct

*defaultValue,

ARPropList

*characList,

ARPropList

*customCharacList,

ARStatusList

*status)

Chapter 5

C API functions and data structures

89

BMC Atrium CMDB 2.1.00

Input
arguments

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

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

attributeName
The name of the attribute to retrieve.
Return values

attributeId
The ID of the attribute.

dataType
The datatype of the attribute.
1:

Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD)

2:

Integer (CMDB_ATTR_DATA_TYPE_INTEGER)

3:

Real (CMDB_ATTR_DATA_TYPE_REAL)

4:

Character (CMDB_ATTR_DATA_TYPE_CHAR)

5:

Diary (CMDB_ATTR_DATA_TYPE_DIARY)

6:

Selection (CMDB_ATTR_DATA_TYPE_ENUM)

7:

Time (CMDB_ATTR_DATA_TYPE_TIME)

10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL)

12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY)
13: Date (CMDB_ATTR_DATA_TYPE_DATE)
14: Time
37:

of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY)

Attachment pool (CMDB_ATTR_DATA_TYPE_ATTACH_POOL)

attributeType
The type of attribute to retrieve.
1: CMDB_ATTR_TYPE_CORE_INTERNAL
2: CMDB_ATTR_TYPE_CORE
3: CMDB_ATTR_TYPE_REGULAR

baseClassNameId
The name of the class that owns this attribute.

arsubclassesId
The internal ID of the attribute to retrieve.

90

Developers Reference Guide

Functions

entryMode
The entry mode for the attribute list. Entry mode can be set to any one of the
following: display only, required, optional.
1: CMDB_ATTR_ENTRYMODE_REQUIRED
2: CMDB_ATTR_ENTRYMODE_OPTIONAL
4: CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY

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

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

characList
A list of characteristics for each attribute. Characteristics include View
Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner,
Create Mode, Audit Option, and Description.
1: List of groups or roles that have
(CMDB_ATTR_CHARAC_VIEW_PERMS).

permissions to view this attribute

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

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

3:

4: Specifies whether the attribute is

(CMDB_ATTR_CHARAC_PRIMARY_KEY).

a part of the primary key of the class

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

5:

6: CMDB_ATTR_CHARAC_CREATE_MODE

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

9:

The description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION

Chapter 5

C API functions and data structures

91

BMC Atrium CMDB 2.1.00

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

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

CMDBGetMultipleAttribute
Description
Privileges
Synopsis

Retrieves multiple attributes.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetMultipleAttribute(

Input
arguments

92

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARBoolean

getHiddenAttrs,

ARBoolean

getDerivedAttrs,

ARNameList

*nameList,

ARPropList

*attrCharacQueryList,

ARBooleanList

*existList,

ARNameList

*attributeNameList,

ARNameList

*attributeIdList,

ARUnsignedIntList

*dataTypeList,

ARUnsignedIntList

*attributeTypeList,

CMDBClassNameIdList

*baseClassNameIdList,

ARInternalIdList

*arsubclassesIdList,

ARUnsignedIntList

*entryModeList,

CMDBAttributeLimitList

*attributeLimitList,

ARValueList

*defaultValueList,

ARPropListList

*characList,

ARPropListList

*customCharacList,

ARStatusList

*status)

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

Developers Reference Guide

Functions

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

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

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

nameList
A list of attributes to retrieve.

attrCharacQueryList
A list of attribute characteristic queries to retrieve.
Return values

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

attributeNameList
The list of attribute names retrieved.

attributeIdList
The list of attribute IDs retrieved.

dataTypeList
The list of data types for the attribute.

attributeTypeList
The list of the attributes type.

baseClassNameIdList
The name of the base class attribute to retrieve.

arsubclassesIdList
The AR System subclasses ID of the attribute.

entryModeList
The entry mode for the attribute list. Options include display only, required, and
optional.
1: Users must enter data when the entry
(CMDB_ATTR_ENTRYMODE_REQUIRED ).
2: Users do not have to enter data
(CMDB_ATTR_ENTRYMODE_OPTIONAL).

mode is set to required

when the entry mode is set to optional

Chapter 5

C API functions and data structures

93

BMC Atrium CMDB 2.1.00

4: Users cannot enter data when the entry

(CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).

mode is set to display only

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

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

characList
A list of characteristics for each attribute. Characteristics include View
Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner,
Create Mode, Audit Option, and Description.
1: List of groups or roles that have
(CMDB_ATTR_CHARAC_VIEW_PERMS).

permissions to view this attribute

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

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

3:

4: Specifies whether the attributes are

(CMDB_ATTR_CHARAC_PRIMARY_KEY).

a part of the primary key of the class

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

5:

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

The description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION

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

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

94

Developers Reference Guide

Functions

CMDBSetAttribute
Description
Privileges
Synopsis

Sets an attribute with the specified name for the specified class.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBSetAttribute(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

attributeName,

ARNameType

newAttributeName,

unsigned int

*entryMode,

CMDBAttributeLimit

*attributeLimit,

ARValueStruct

*defaultValue,

ARPropList

*characList,

ARPropList

*customCharacList,

ARStatusList

*status)

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

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

attributeName
The name of the attribute to set.

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

entryMode
The entry mode for the attribute. Options include display only, required, and
optional.
1: Users must enter data when the
(CMDB_ATTR_ENTRYMODE_REQUIRED).

entry mode is set to required

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

Chapter 5

mode is set to display only

C API functions and data structures

95

BMC Atrium CMDB 2.1.00

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

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

characList
A list of characteristics for each attribute. Characteristics include View
Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner,
Create Mode, Audit Option, and Description.
1: Users can view but not modify
(CMDB_ATTR_CHARAC_VIEW_PERMS).

the characteristics of the attribute

2: Users can view and modify the characteristics of

(CMDB_ATTR_CHARAC_CHANGE_PERMS).
3: Users can set the flag to false
(CMDB_ATTR_CHARAC_HIDDEN).

the attribute

so they cannot see hidden attributes

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

5:

6: CMDB_ATTR_CHARAC_CREATE_MODE
7:Users can set the audit option on
CMDB_ATTR_CHARAC_AUDIT_OPTION
9:Users can

to store the audit history for the attribute.

set the description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION

customCharacList
A list of user-defined custom characteristics for the attribute. The attributes must
be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999
(CMDB_ATTR_CUSTOM_CHARAC_MAX).
In version 2.0 of the BMC Atrium CMDB, the custom characteristic list was
overwritten when you specified new values. With version 2.0.1, the new values are
appended to the existing list. To delete a custom characteristic, set its datatype to
NULL.
Return values

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

96

Developers Reference Guide

Functions

CMDBSetMultipleAttribute
Description
Privileges
Synopsis

Sets multiple attributes with the specified names for the specified class.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBSetMultipleAttribute(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameList

*attributeNameList,

ARNameList

*newAttributeNameList,

ARUnsignedIntList

*entryModeList,

CMDBAttributeLimitList

*attributeLimitList,

ARValueList

*defaultValueList,

ARPropListList

*characListList,

ARPropListList

*customCharacListList,

ARStatusList

*status)

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

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

attributeNameList
The list of attribute names to set.

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

entryModeList
The list of entry modes for the attributes being created. Entry mode can be set to
any one of the following modes: display only, required, optional.
1: Users must enter data when the entry
(CMDB_ATTR_ENTRYMODE_REQUIRED ).

mode is set to required

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

Chapter 5

mode is set to display only

C API functions and data structures

97

BMC Atrium CMDB 2.1.00

attributeLimitList
The list of value limits for the attributes being created and other properties specific
to the attributes' types. See CMDBAttributeLimit on page 162 to find the
contained structure that applies to the type of attribute list you are modifying. The
limits and properties you assign must be of the same data type as the attribute.
Specify NULL for this parameter if you do not want to change the limits and
properties for the attribute list.

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

characListList
A list of characteristics for each attribute. Characteristics include View
Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner,
Create Mode, Audit Option, and Description.
Users can specify a list of groups or roles that have permissions to view this
attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).

1:

Users can specify a list of groups or roles that have permissions to view and
modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).

2:

3: Users can set the flag to false

(CMDB_ATTR_CHARAC_HIDDEN).

so that this attribute is hidden

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

5:

6: CMDB_ATTR_CHARAC_CREATE_MODE
7:User can set the audit option on
CMDB_ATTR_CHARAC_AUDIT_OPTION
9:Users can

to store the audit history for the attribute.

set descriptions of the attributes. CMDB_ATTR_CHARAC_DESCRIPTION

customCharacListList
A list of user-defined custom characteristics list for the attribute. The value can be
set to any user-defined characteristic but must be in the range between 100000
(CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX).
Specify NULL for this parameter if you do not want to associate custom
characteristics with this attribute.
In version 2.0 of the BMC Atrium CMDB, the custom characteristic list was
overwritten when you specified new values. With version 2.0.1, the new values are
appended to the existing list. To delete a custom characteristic, set its datatype to
NULL.

98

Developers Reference Guide

Functions

Return values

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

CMDBCreateClass
Description

Privileges
Synopsis

Creates a class with the core attributes in the OBJSTR:Class. The data model is
stored in the OBJSTR:Class form and the attribute information is stored in the
OBJSTR:AttributeDefinition form.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBCreateClass(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameID,

ARNameType

classID,

CMDBClassTypeInfo

*classTypeInfo,

CMDBClassNameId

*superclassNameId,

CMDBIndexList

*indexList,

CMDBAuditInfoStruct

*auditInfo,

ARPropList

*characList,

ARPropList

*customCharacList,

ARStatusList

*status)

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

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

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

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

Indicates a regular class (CMDB_CLASS_TYPE_REGULAR).

2:

Indicates a class of type relationship (CMDB_CLASS_TYPE_RELATIONSHIP).

Chapter 5

C API functions and data structures

99

BMC Atrium CMDB 2.1.00

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

indexList
A list of indexes defined for the class.

auditInfo
The audit information for the class.

characList
A list of characteristics for the class. Specify NULL for this parameter if you do not
want to associate characteristics with this class.
1: Used to specify if this is a singleton class. This characteristic is an integer value
where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a
singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a
singleton class (CMDB_CLASS_CHARAC_SINGLETON).
2: This property does not allow you to create instances for this abstract class
(CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the attribute,

you cannot create instances for it. All the attributes are propagated to the
subclasses.
3:

You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL).

4:

The author of the class (CMDB_CLASS_CHARAC_AUTHOR).

5:

The class description (CMDB_CLASS_CHARAC_DESCRIPTION).

6: Gives you the permissions to modify the class

(CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks the class as hidden for a group

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

or a role. When querying for classes, you will see all classes, including the hidden
classes. You can specify one or more group IDs or role IDs for the permissions
separated by a semicolon, for example, 20;-5.
8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS
9: CMDB_CLASS_CHARAC_FORM_NAME

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

100

Is the number of items in the properties list.

Developers Reference Guide

Functions

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

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

Return values

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

CMDBDeleteClass
Description
Privileges
Synopsis

Deletes a specified class. Also deletes the associated attributes of the class.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBDeleteClass(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

unsigned int

deleteOption,

ARStatusList

*status)

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

classNameID
The name of the class to delete.

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

Delete the class only if the class contains no instances and has no subclasses or
dependent relationships (CMDB_DELETE_CLASS_OPTION_NONE).
Delete the class only if the class has no subclasses or dependent relationships.
This applies only to regular classes (CMDB_DELETE_CLASS_OPTION_WITH_DATA).

1:

2: Delete the class, including all the subclasses and dependent relationship classes

that are associated with it. All the dependencies for the specified class are deleted
(CMDB_DELETE_CLASS_OPTION_ALL_DEPENDENCIES). This option overrides the
CMDB_CLASS_DATA_DELETE option.

Chapter 5 C API functions and data structures

101

BMC Atrium CMDB 2.1.00

Return values

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

CMDBGetClass
Description
Privileges
Synopsis

Retrieves the class information from the OBJSTR:Class form.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetClass(

Input
arguments

ARControlStruct

*control,

CMDBClassNameID

*classNameId,

ARNameType

*classId,

CMDBClassTypeInfo

*classTypeInfo,

CMDBClassNameId

*superclassNameId,

CMDBIndexList

*indexList,

CMDBAuditInfoStruct

auditInfo,

ARPropList

*characList,

ARPropList

*customCharacList,

ARStatusList

*status)

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

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

classId
The ID used to identify the class.

classTypeInfo
Information about the type of class.

superclassNameId
The name of the superclass.

indexList
The list of indexes defined for the class.

102

Developers Reference Guide

Functions

auditInfo
The audit information for the class.

characList
A list of characteristics for this class. Specify NULL for this parameter if you do not
want to associate characteristics with this class.
1: Used to specify if this is a singleton class. This characteristic is an integer value
where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a
singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a
singleton class (CMDB_CLASS_CHARAC_SINGLETON).
2: This property does not allow you to create instances for this abstract class
(CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the attribute,

you cannot create instances for it. All the attributes are propagated to the
subclasses.
3:

You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL).

4:

The author of the class (CMDB_CLASS_CHARAC_AUTHOR).

5:

The class description (CMDB_CLASS_CHARAC_DESCRIPTION).

6: Gives you the permissions to modify the class

(CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks

the class as hidden for the

users in the group. When querying for classes, you can choose to retrieve hidden
classes.

7: Gives you the permissions to modify the class

(CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class

as visible for the

users in the group. When querying for classes, you will see all classes including the
hidden classes.
8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS
9: CMDB_CLASS_CHARAC_FORM_NAME

customCharacList
A list of user-defined custom characteristics for the class. The value retrieved must
be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999
(CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not
want to retrieve custom characteristics with this class.

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

Chapter 5 C API functions and data structures

103

BMC Atrium CMDB 2.1.00

CMDBGetListClass
Description

Privileges
Synopsis

Retrieves information about relationship classes for a specified class. The classes
that are retrieved will have the class that is specified in the classNameIdRelation
parameter as part of the relationship.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetListClass(

Input
arguments

ARControlStruct

*control,

ARNameType

namespaceName,

CMDBClassNameId

*classNameIdRelation,

CMDBClassNameId

*superclassName,

ARPropList

*characQueryList,

ARBoolean

getHiddenClasses,

CMDBClassNameIdList

*classNameIdList,

ARStatusList

*status)

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

namespaceName
The name of the namespace. Namespaces are a way of partitioning your data
model to create logical groups of classes. The Class Manager namespaces are
implemented using a prefix-based naming convention on classes.

classNameIdRelation
Retrieves the relationship classes that have a class specified in this parameter as
part of the relationship.

superclassName
Retrieves the classes that are derived from the superclass.

characQueryList
Retrieves all the classes that match the criteria.

getHiddenClasses
Retrieves the hidden classes.

104

Developers Reference Guide

Functions

Return values

classNameIdList
A list of class names that match the specified criteria.

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

CMDBSetClass
Description

Privileges
Synopsis

Sets the class properties in the OBJSTR:Class form. After you create a class, you
cannot modify the following properties: classId, classType (regular, relationship),
and persistence provider.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBSetClass(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

CMDBClassNameId

*newclassNameId,

CMDBClassTypeInfo

*classTypeInfo,

CMDBIndexList

*indexList,

CMDBAuditInfoStruct

*auditInfo,

ARPropList

*characList,

ARPropList

*customCharacList,

ARStatusList

*status)

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

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

newclassNameId
The new name of the class.

classTypeInfo
Information about the type of class.

Chapter 5 C API functions and data structures

105

BMC Atrium CMDB 2.1.00

indexList
The list of indexes defined for the class. When this parameter is specified, all
previously existing indexes are replaced by its contents. If you want to add indexes
without losing existing indexes, include the existing indexes in this list.

auditInfo
The audit information for the class.

characList
A list of characteristics for this class. Specify NULL for this parameter if you do not
want to associate characteristics with this class.
Used to specify if this is a singleton class. This characteristic is an integer value,
where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a
singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a
singleton class (CMDB_CLASS_CHARAC_SINGLETON).

1:

2: This property does not allow you to create instances for this abstract class
(CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the class, you

cannot create instances for it. All the attributes are propagated to the subclasses.
3:

You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL).

4:

The author of the class (CMDB_CLASS_CHARAC_AUTHOR).

5:

The class description (CMDB_CLASS_CHARAC_DESCRIPTION).

6: Gives you the permissions to modify the class

(CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks

the class as hidden for the

users in the group. When querying for classes, you can choose to retrieve hidden
classes.

7: Gives you the permissions to modify the class

(CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class

as visible for the

users in the group. When querying for classes, you will see all classes, including
the hidden classes.
8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS
9: CMDB_CLASS_CHARAC_FORM_NAME

customCharacList
A list of user-defined custom characteristics for the class. The value can be set to
any user-defined characteristic but must be in the range between 100000
(CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX).
Specify NULL for this parameter if you do not want to associate custom
characteristics with this class.
In version 2.0 of the BMC Atrium CMDB, the custom characteristic list was
overwritten when you specified new values. With version 2.0.1, the new values are
appended to the existing list. To delete a custom characteristic, set its datatype to
NULL.

106

Developers Reference Guide

Functions

Return values

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

Instance functions
The C APIfunctions for instance include:

CMDBCreateInstance (page 107)

CMDBDeleteInstance (page 108)

CMDBGetInstance (page 109)

CMDBGetListInstance (page 110)

CMDBGetMultipleInstances (page 112)

CMDBGraphQuery (page 115)

CMDBSetInstance (page 117)

CMDBCreateInstance
Description
Privileges
Synopsis

Creates a CI or relationship instance of the specified class.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBCreateInstance(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

CMDBAttributeValueList

*attributeValueList,

ARNameType

instanceId,

ARStatusList

*status)

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

classNameId
The name of the class from which the instance is derived. It is a two-part structure
that contains the namespace and the classname.

Chapter 5 C API functions and data structures

107

BMC Atrium CMDB 2.1.00

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

attributeValueList
A list of one or more subclasses/value pairs (specified in any order) that identifies
the data for the new attribute. You must specify values for all required subclasses
that do not have defined defaults. Values must be of the data type defined for the
subclasses or have a data type of 0. NULL values can be specified for optional
subclasses only. An error is generated if a subclasses does not exist or the user
specified by the control parameter does not have write permission for a subclasses.
Return values

instanceId
The unique identifier for the new attribute (system-generated).

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

CMDBDeleteInstance
Description
Privileges
Synopsis

Deletes the instance of the class.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBDeleteInstance(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

ARNameType

instanceId,

unsigned int

deleteOption,

ARStatusList

*status)

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

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

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

Developers Reference Guide

Functions

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

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

0:

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

exist.
Return values

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

CMDBGetInstance
Description
Privileges
Synopsis

Retrieves information about the instance.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetInstance(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

usigned int

getMask,

ARNameType

instanceId,

ARNameList

*attributeGetList,

CMDBAttributeValueList

*attributeValueList,

ARStatusList

*status)

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

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

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

Chapter 5 C API functions and data structures

109

BMC Atrium CMDB 2.1.00

getMask
The identifier for specifying the dataset type.
0: Based on the datasetId being passed, instances are retrieved from either the
overlay or the original dataset.
1:

Allows you to retrieve instances from the current dataset only.

instanceId
The unique identifier for the instance to retrieve.

attributeGetList
The list of attributes to retrieve.
Return values

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

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

CMDBGetListInstance
Description
Privileges
Synopsis

Retrieves a list of instances. You can limit the instance list to entries that match
particular conditions by specifying the qualifier parameter.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetListInstance(

110

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

usigned int

getMask,

CMDBQualifierStruct

*qualifier,

ARNameList

*attributeGetList,

CMDBSortList

*sortList,

unsigned int

firstRetrieve,

unsigned int

maxRetrieve,

ARNameList

*instanceIdList,

CMDBAttributeValueListList

*attributeValueListList,

unsigned int

*numMatches,

ARStatusList

*status)

Developers Reference Guide

Functions

Input
arguments

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

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

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

getMask
The identifier for specifying the dataset type.
Based on the datasetId being passed, instances are retrieved from either the
overlay or the original dataset.
0:

1:

Allows you to retreive instances from the current dataset only.

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

attributeGetList
A list of attribute names to retrieve.

sortList
The sort order for the retrieved data.

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

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

instanceIdList
The list of instance IDs that match the criteria.

attributeValueListList
A list of the attribute value list.

Chapter 5 C API functions and data structures

111

BMC Atrium CMDB 2.1.00

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

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

CMDBGetMultipleInstances
Description
Privileges
Synopsis

Retrieves multiple instances.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetMultipleInstances(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

unsigned int

getMask,

ARNameList

*instanceIds,

ARNameList

*attributeGetList,

ARBooleanList

*existList,

CMDBAttributeValueListList

*attributeValueListList,

ARStatusList

*status)

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

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

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

getMask
The identifier for specifying the dataset type.
0: Based on the datasetId being passed, a list of instances are retrieved from either

the overlay or the original dataset.

112

Developers Reference Guide

Functions

1:

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

instanceIds
A list of instance IDs to retrieve.

attributeGetList
A list of attributes to retrieve.
Return values

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

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

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

CMDBGetInstanceBLOB
Description
Privileges
Synopsis

Retrieves the attachment, or binary large object (BLOB), stored for the attachment
subclasses. The BLOB can be returned in a file or in an in-memory buffer.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetInstanceBLOB(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

unsigned int

getMask,

ARNameType

instanceId,

ARNameType

attributeName,

ARLocStruct

*loc,

ARStatusList

*status)

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

Chapter 5 C API functions and data structures

113

BMC Atrium CMDB 2.1.00

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

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

getMask
The identifier for specifying the dataset type.
0: Based on the datasetId being passed, instances are retrieved from either the
overlay or the original dataset.
1:

Allows you to retreive instances from the current dataset only.

instanceId
The unique identifier for the instance.

attributeName
The name of the attribute that contains the attachment.
Return values

loc
The location where the BLOB is stored.

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

114

Developers Reference Guide

Functions

CMDBGraphQuery
Description
Privileges
Synopsis

Searches related instances.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGraphQuery(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*startClassNameId,

ARNameType

datasetId,

unsigned int

getMask,

ARNameType

startExtensionId,

ARNameType

startInstanceId,

int

numLevels,

int

direction,

ARBoolean

noMatchProceed,

ARBoolean

onMatchProceed,

CMDBGraphList

*queryGraph,

CMDBGetObjectList

*objects,

CMDBGetRelationList

*relations,

ARStatusList

*status)

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

startClassNameId
The name of the starting node class.

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

getMask
The identifier for specifying the dataset type.
0: Based on the datasetId being passed, instances are retrieved from either the
overlay or the original dataset.
1:

Allows you to retreive instances from the current dataset only.

Chapter 5 C API functions and data structures

115

BMC Atrium CMDB 2.1.00

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

startInstanceId
The ID of the starting node.

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

direction
The direction in which the graph is to traverse.
CMDB_RELATIONSHIP_DIRECTION_OUT (0):

Return the node that exists on the right side of the relationship.
CMDB_RELATIONSHIP_DIRECTION_IN (1):

Return the node that exists on the left side of the relationship.
CMDB_RELATIONSHIP_DIRECTION_BOTH (2):

Return the nodes that exist on both left and right side of the relationship.

noMatchProceed
T (1):

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

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

onMatchProceed
T (1):

When the node returned for a given relationship instance matches the criteria
specified, proceed to the next relationship.
F (0):

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

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

116

Developers Reference Guide

Functions

Return values

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

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

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

CMDBSetInstance
Description
Privileges
Synopsis

Sets a CI or relationship instance of the specified class.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBSetInstance(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

ARNameType

instanceId,

CMDBAttributeValueList

*attributeValueList,

ARStatusList

*status)

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

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

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

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

Chapter 5 C API functions and data structures

117

BMC Atrium CMDB 2.1.00

attributeValueList
A list of one or more attribute value pairs (specified in any order) that identifies the
data for the new attribute. You must specify values for all required subclasses that
do not have defined defaults.
Values must be of the data type defined for the subclasses or have a data type of 0.
NULL values can be specified for optional subclasses only. An error is generated if a
subclasses does not exist or the user specified by the control parameter does not
have write permission for a subclasses.
Return values

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

Bulk entry transaction functions

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

CMDBBeginBulkEntryTransaction (page 118)

CMDBEndBulkEntryTransaction (page 119)

CMDBBeginBulkEntryTransaction
Description

Privileges
Synopsis

Indicates that subsequent API functions are part of the bulk transaction. Any API
calls that arrive after this function call are placed in a queue. Data model functions
are not part of the bulk transaction.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBBeginBulkEntryTransaction(

Input
argument

Return value

ARControlStruct

*control,

ARStatusList

*status)

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

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

118

Developers Reference Guide

Functions

CMDBEndBulkEntryTransaction
Description

Privileges
Synopsis

This function commits or rolls back the bulk transaction, depending on the action
type. For an action type of SEND, the API call will be executed as part of the
transaction. For an action type of CANCEL, the transaction will be canceled.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBEndBulkEntryTransaction(
ARControlStruct

Input
arguments

*control,

unsigned int

actionType,

ARBulkEntryReturnList

*bulkEntryReturnList,

ARStatusList

*status)

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

actionType
The type of action. Action type can be SEND or CANCEL.
Return values

bulkEntryReturnList
Returns the status of the entry calls.

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

Chapter 5 C API functions and data structures

119

BMC Atrium CMDB 2.1.00

Environment functions
The Class Manager includes the following environment functions:

CMDBInitialization (page 120)

CMDBSystemInit (page 121)

CMDBSynchMetaData (page 121)

CMDBGetServerPort (page 122)

CMDBSetServerPort (page 123)

CMDBTermination (page 124)

CMDBInitialization
Description
Privileges
Synopsis

Initializes the C API session. This function must be called before any C API calls
are made.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBInitialization(

Input
arguments

Return values

ARControlStruct

*control,

ARStatusList

*status)

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

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

120

Developers Reference Guide

Functions

CMDBSystemInit
Description
Privileges
Synopsis

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

BMC.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBSystemInit(

Return values

ARPropList

*propList,

ARStatusList

*status)

propList
A list of properties that need to be initialized.

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

CMDBSynchMetaData
Description
Privileges
Synopsis

Creates AR System forms from the data model definitions that hold instance data,
and workflow, which enforces class hierarchy and data integrity.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBSynchMetaData(

Input
arguments

ARControlStruct

*control,

ARNameType

pendingId,

CMDBClassNameIdList

*classNameIdList,

ARStatusList

*status)

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

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

Chapter 5 C API functions and data structures

121

BMC Atrium CMDB 2.1.00

Return values

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

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

CMDBGetServerPort
Description
Privileges
Synopsis

Retrieves information about the server port.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetServerPort(

Input
arguments

Return values

ARControlStruct

*control,

int

*tcpPort,

int

*rpcPort,

ARStatusList

*status)

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

tcpPort
Retrieves the CMDB server TCP port information.

rpcPort
Retrieves the CMDB server RPC port information.

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

122

Developers Reference Guide

Functions

CMDBSetServerPort
Description
Privileges
Synopsis

Sets the specified server port.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBSetServerPort(

Input
arguments

ARControlStruct

*control,

int

*tcpPort,

int

*rpcPort,

ARStatusList

*status)

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

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

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

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

Chapter 5 C API functions and data structures

123

BMC Atrium CMDB 2.1.00

CMDBTermination
Description

Privileges
Synopsis

Performs environment-specific cleanup routines and disconnects from the

specified session. All API programs that interact with the Class Manager session
should call this function upon completing work in a given session.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBTermination(

Input
arguments

Return values

ARControlStruct

*control,

ARStatusList

*status)

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

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

124

Developers Reference Guide

Functions

User interface component functions

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

CMDBGetCMDBUIComponents (page 125)

CMDBRunQualificationForCI (page 126)

CMDBExpandParametersForCI (page 127)

CMDBGetCMDBUIComponents
Description
Privileges
Synopsis

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

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetCMDBUIComponents(
ARControlStruct

Input
arguments

*control,

CMDBUIComponentInfo

*inputInfo,

ARNameType

instanceId,

CMDBUIComponentResultList

*outputInfo,

ARStatusList

*status)

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

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

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

outputInfo
The CMDBUIComponents result set for the specified qualifications.

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

Chapter 5 C API functions and data structures

125

BMC Atrium CMDB 2.1.00

CMDBRunQualificationForCI
Description

Privileges
Synopsis

Performs validation on a list of attributes for a specified CI. The

CMDBRunQualificationForCI function takes qualification parameters in both
structured and encoded modes.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBRunQualificationForCI(
ARControlStruct

Input
arguments

*control,

CMDBQualifierStruct

*qualifier,

CMDBAttributeValueList

*attValueList,

ARBoolean*

passed,

ARStatusList

*status)

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

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

attValueList
The list of attributes to validate.
Return Values

passed
A Boolean value that specifies whether the qualification passed.

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

126

Developers Reference Guide

Functions

CMDBExpandParametersForCI
Description
Privileges
Synopsis

Accepts an unexpanded string that contains parameters and substitutes values

from the attribute value list provided in the CMDBAttributeValueList structure.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBQualificationForCI(
ARControlStruct

Input
arguments

*control,

char

*paramString,

CMDBAttributeValueList

*attValueList,

char

**expandedStr,

ARStatusList

*status)

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

paramString
The string that contains the unexpanded parameters.

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

expandedStr
The string that contains the expanded parameters.

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

Chapter 5 C API functions and data structures

127

BMC Atrium CMDB 2.1.00

Import and Export functions

The export and import functions enable you to export or import CMDB data. The
Class Manager includes the following export and import functions:

CMDBExport (page 128)

CMDBExportDef (page 129)

CMDBExportData (page 130)

CMDBImport (page 131)

CMDBImportDef (page 132)

CMDBImportData (page 133)

CMDBExport
Description
Privileges
Synopsis

Exports the specified class definitions from the specified server. This function is
deprecated in the 2.0 release of the BMC Atrium CMDB.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBExport(

Input
arguments

ARControlStruct

*control,

CMDBExportItemList

*exportItemList,

unsigned int

exportFormat,

char

*directoryPath,

ARStatusList

*status)

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

exportItemList
The list of items to export.

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

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

128

Developers Reference Guide

Functions

Return values

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

CMDBExportDef
Description
Privileges
Synopsis

Exports a list of specified class definitions.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBExportDef(

Input
arguments

ARControlStruct

*control,

CMDBExportItemList

*exportItemList,

char

*exportBuf,

ARStatusList

*status)

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

exportItemList
A list of zero or more classes or attributes to export.
Return values

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

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

Chapter 5 C API functions and data structures

129

BMC Atrium CMDB 2.1.00

CMDBExportData
Description
Privileges
Synopsis

Exports the specified class data for a specific qualification.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBExportData(
ARControlStruct

Input
arguments

*control,

ARQualifierStruct

*qualifier,

ARNameList

*attributeGetList,

CMDBSortList

*sortList,

unsigned int

firstRetrieve,

unsigned int

maxRetrieve,

char

*exportBuf,

ARStatusList

*status)

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

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

attributeGetList
The list of attributes names to retrieve.

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

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

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

130

Developers Reference Guide

Functions

Return values

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

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

CMDBImport
Description

Privileges
Synopsis

Imports the specified class definitions to the specified server. Use this function to
copy structure definitions from one server to another. This function is deprecated
in the 2.0 release of the BMC Atrium CMDB.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBImport(

Input
arguments

ARControlStruct

*control,

CMDBImportItemList

*importItemList,

char

*directoryPath,

ARStatusList

*status)

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

importItemList
A list of zero or more items to import.

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

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

Chapter 5 C API functions and data structures

131

BMC Atrium CMDB 2.1.00

CMDBImportDef
Description
Privileges
Synopsis

Imports a list of specified class definitions.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBImportDef(

Input
arguments

ARControlStruct

*control,

CMDBXMLImportItemList

*importItemList,

unsigned int

importOption,

char

*importBuf,

ARStatusList

*status)

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

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

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

Generate an error if an item to import already exists

CMDB_DEF_IMPORT_OPT_CREATE.
2:

Overwrite if an item to import already exists

CMDB_DEF_IMPORT_OPT_OVERWRITE.

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

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

132

Developers Reference Guide

Functions

CMDBImportData
Description
Privileges
Synopsis

Imports the specified instance data.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBImportData(
ARControlStruct

Input
arguments

*control,

unsigned int

importOption,

char

*importBuf,

ARStatusList

*status)

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

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

Generate an error

(CMDB_DATA_IMPORT_OPT_ERROR_FOR_DUP).
2:

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

(CMDB_DATA_IMPORT_OPT_NEWID_FOR_DUP).

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

(CMDB_DATA_IMPORT_OPT_MERGE_FOR_DUP).

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

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

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

Chapter 5 C API functions and data structures

133

BMC Atrium CMDB 2.1.00

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

CMDBCreateGuid (page 134)

CMDBGetVersions (page 134)

CMDBCreateGuid
Description
Privileges
Synopsis

Creates a globally unique identifier.

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBCreateGuid(

Return values

ARGuid

guid,

ARStatusList

*status)

guid
The unique identifier (system-generated).

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

CMDBGetVersions
Description
Privileges
Synopsis

Retrieves the version information for any BMC Atrium CMDB component that is
installed.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
int CMDBGetVersions(

134

ARControlStruct

*control,

ARNameList

*appIdList

ARBooleanList

*existList

CMDBVersionInfoList

*versionInfoList

ARStatusList

*status)

Developers Reference Guide

Functions

Input
arguments

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

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

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

versionInfoList
A list of BMC Atrium CMDB version structures.

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

Chapter 5 C API functions and data structures

135

BMC Atrium CMDB 2.1.00

Free functions
The free functions release the memory allocated to a specified function. The Class
Manager includes the following free functions:

FreeCMDBVersionInfoList (page 137)

FreeCMDBClassNameIdList (page 137)

FreeCMDBAttributeLimit (page 138)

FreeCMDBAttributeLimitList (page 139)

FreeCMDBAttributeLimitStruct (page 138)

FreeCMDBIndexList (page 139)

FreeCMDBExportItemStruct (page 140)

FreeCMDBExportItemList (page 140)

FreeCMDBImportItemList (page 141)

FreeCMDBAttributeGetStruct (page 141)

FreeCMDBGraphAdjacentStruct (page 142)

FreeCMDBGraphAdjacentList (page 142)

FreeCMDBGraphStruct (page 143)

FreeCMDBGraphList (page 143)

FreeCMDBClassTypeInfo (page 144)

FreeCMDBQualifierStruct (page 144)

FreeCMDBGetRelationList (page 145)

FreeCMDBGetObjectList (page 145)

FreeCMDBAttributeValueList (page 146)

FreeCMDBAttributeValueListList (page 146)

FreeCMDBSortList (page 147)

FreeCMDBREJobRunInfoList (page 147)

136

Developers Reference Guide

Functions

FreeCMDBVersionInfoList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBVersionInfoList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBVersionInfoList(

Input
arguments

CMDBVersionInfoList

*value,

ARBoolean

freestruct)

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

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

FreeCMDBClassNameIdList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBClassNameIdList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBClassNameIdList(

Input
arguments

CMDBClassNameIdList

*value,

ARBoolean

freestruct)

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

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

Chapter 5 C API functions and data structures

137

BMC Atrium CMDB 2.1.00

FreeCMDBAttributeLimit
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBAttributeLimit structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBAttributeLimit(

Input
arguments

CMDBAttributeLimit

*value,

ARBoolean

freestruct)

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

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

FreeCMDBAttributeLimitStruct
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBAttributeLimitStruct structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBAttributeLimitStruct(

Input
arguments

CMDBAttributeLimit

*value,

ARBoolean

freestruct)

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

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

138

Developers Reference Guide

Functions

FreeCMDBAttributeLimitList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBAttributeLimitList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBAttributeLimitList(

Input
arguments

CMDBAttributeLimitList

*value,

ARBoolean

freestruct)

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

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

FreeCMDBIndexList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBIndexList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBIndexList(

Input
arguments

CMDBIndexList

*value,

ARBoolean

freestruct)

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

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

Chapter 5 C API functions and data structures

139

BMC Atrium CMDB 2.1.00

FreeCMDBExportItemStruct
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBExportItemStruct structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBExportItemStruct(

Input
arguments

CMDBExportItemStruct

*value,

ARBoolean

freestruct)

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

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

FreeCMDBExportItemList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBExportItemList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBExportItemList(

Input
arguments

CMDBExportItemList

*value,

ARBoolean

freestruct)

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

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

140

Developers Reference Guide

Functions

FreeCMDBImportItemList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBImportItemList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBImportItemList(

Input
arguments

CMDBImportItemList

*value,

ARBoolean

freestruct)

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

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

FreeCMDBAttributeGetStruct
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBAttributeGetStruct structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBAttributeGetStruct(

Input
arguments

CMDBAttributeGetStruct

*value,

ARBoolean

freestruct)

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

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

Chapter 5 C API functions and data structures

141

BMC Atrium CMDB 2.1.00

FreeCMDBGraphAdjacentStruct
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBGraphAdjacentStruct structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBGraphAdjacentStruct(

Input
arguments

CMDBGraphAdjacentStruct

*value,

ARBoolean

freestruct)

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

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

FreeCMDBGraphAdjacentList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBGraphAdjacentList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBGraphAdjacentList(

Input
arguments

CMDBGraphAdjacentList

*value,

ARBoolean

freestruct)

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

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

142

Developers Reference Guide

Functions

FreeCMDBGraphStruct
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBGraphStruct structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBGraphStruct(

Input
arguments

CMDBGraphStruct

*value,

ARBoolean

freestruct)

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

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

FreeCMDBGraphList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBGraphList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBGraphList(

Input
arguments

CMDBGraphList

*value,

ARBoolean

freestruct)

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

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

Chapter 5 C API functions and data structures

143

BMC Atrium CMDB 2.1.00

FreeCMDBClassTypeInfo
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBClassTypeInfo structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBClassTypeInfo(

Input
arguments

CMDBClassTypeInfo

*value,

ARBoolean

freestruct)

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

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

FreeCMDBQualifierStruct
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBQualifierStruct structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBQualifierStruct(

Input
arguments

CMDBQualifierStruct

*value,

ARBoolean

freestruct)

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

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

144

Developers Reference Guide

Functions

FreeCMDBGetRelationList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBGetRelationList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBGetRelationList(

Input
arguments

CMDBGetRelationList

*value,

ARBoolean

freestruct)

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

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

FreeCMDBGetObjectList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBGetObjectList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBGetObjectList(

Input
arguments

CMDBGetObjectList

*value,

ARBoolean

freestruct)

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

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

Chapter 5 C API functions and data structures

145

BMC Atrium CMDB 2.1.00

FreeCMDBAttributeValueList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBAttributeValueList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBAttributeValueList(

Input
arguments

CMDBAttributeValueList

*value,

ARBoolean

freestruct)

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

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

FreeCMDBAttributeValueListList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBAttributeValueListList

structure.
CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBAttributeValueListList(

Input
arguments

CMDBAttributeValueListList

*value,

ARBoolean

freestruct)

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

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

146

Developers Reference Guide

Functions

FreeCMDBSortList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBSortList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBSortList(

Input
arguments

CMDBSortList

*value,

ARBoolean

freestruct)

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

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

FreeCMDBREJobRunInfoList
Description
Privileges
Synopsis

Releases the memory space allocated to the CMDBREJobRunInfoList structure.

CMDB Administrator
#include "ar.h"
#include "arfree.h"
#include "cmdbfree.h"
FreeCMDBREJobRunInfoList(

Input
arguments

CMDBREJobRunInfoList

*value,

ARBoolean

freestruct)

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

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

Chapter 5 C API functions and data structures

147

BMC Atrium CMDB 2.1.00

Reconciliation Engine functions

The Reconciliation Engine functions manipulate Reconciliation Engine jobs. The C
API functions for the Reconciliation Engine include:

CMDBStartJobRun (page 148)

CMDBGetJobRun (page 149)

CMDBGetListJobRun (page 150)

CMDBCancelJobRun (page 151)

CMDBStartJobRun
Description

Privileges
Synopsis

Starts an existing Reconciliation Engine job. Before starting a job, make sure the job
is defined and exists in an Active state. If no job for the specified job name exists,
or the job is not Active, the CMDBStartJobRun function returns an error. Only one
instance of the same job can be executed at a given time.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBStartJobRun(

Input
arguments

ARControlStruct

*control,

ARNameType

jobName,

CMDBClassQualList

*classQualList,

CMDBREDatasetList

*datasetList

ARNameType

jobRunId,

ARStatusList

*status)

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

jobName
The name of the reconciliation job.

classQualList
The list of class qualifications with which to substitute the Qualification group
defined for the job. In the qualification list, specify the class ID and the
qualification that applies to it, for example, BMC_ComputerSystem, {1,
('ReconciliationId' = NULL AND'CreateDate' > ($TIMESTAMP$ - 86400))}.

148

Developers Reference Guide

Functions

datasetList
The list of dataset pairs, where the first one represents the substitution dataset
(working dataset) and the second represents the dataset defined in the
Reconciliation Engine job (defined dataset), for example, 2,
{BMC.IMPORT.CONFIG, BMC.SAMPLE}.
Return values

jobRunId
A unique job identifier.

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

CMDBGetJobRun
Description

Privileges
Synopsis

Gets information about the currently running reconciliation job and retrieves a job
log. For information about interpreting job run logs and job run information, see
the section Viewing job status, results, and history in the Installation and
Configuration Guide.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetJobRun(

Input
arguments

ARControlStruct

*control,

ARNameType

jobRunId,

ARREJobRunInfoStruct

*jobRunInfo,

char

**jobRunLog

ARStatusList

*status)

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

jobRunId
A unique job identifier.
Return values

jobRunInfo
The job run information to retrieve.

jobRunLog
The job run log to retrieve.

Chapter 5 C API functions and data structures

149

BMC Atrium CMDB 2.1.00

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

CMDBGetListJobRun
Description
Privileges
Synopsis

Get a list of running Reconciliation Engine jobs. The job list will be retrieved based
on the qualification passed to the function.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetListJobRun(

Input
arguments

ARControlStruct

*control,

CMDBQualifierStruct

*jobQualifier,

ARREJobRunInfoList

*jobRunInfoList,

unsigned int

*numMatches,

ARStatusList

*status)

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

jobQualifier
A query that determines the set of entries to retrieve. The qualification can include
one or more subclasses and any combination of conditional, relational, and
arithmetic operations. The following qualifiers are currently supported:
Run Status*, Run Start Time, Run End Time, Job Instance ID*, Job Run ID,
Submitter.

Return values

and

jobRunInfoList
The list of running jobs that match the qualification criteria.

numMatches
The total number of jobs that match the qualification criteria.

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

150

Developers Reference Guide

Functions

CMDBCancelJobRun
Description
Privileges
Synopsis

Cancels a currently running Reconciliation Engine job. Depending on the system

resources, Reconciliation Engine might cancel a job with a certain delay.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBCancelJobRun(

Input
arguments

ARControlStruct

*control,

ARNameType

jobRunId,

ARStatusList

*status)

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

jobRunId
A unique job identifier.
Return values

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

Chapter 5 C API functions and data structures

151

BMC Atrium CMDB 2.1.00

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

CMDBGetRelatedFederatedInContext (page 152)

CMDBActivateFederatedInContext (page 153)

CMDBGetRelatedFederatedInContext
Description
Privileges
Synopsis

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

CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetRelatedFederatedInContext(

Input
arguments

ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

ARNameType

instanceId,

ARNameList

*attributeGetList,

ARNameList

*instanceIdList,

CMDBAttributeValueListList

*attrValueListList,

ARStatusList

*status

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

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

datasetId
The dataset ID of the instance to retrieve.

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

attributeGetList
The list of attribute names to retrieve.

152

Developers Reference Guide

Functions

Return values

instanceIdList
The list of instance GUIDs.

attrValueListList
The list of attribute value list.

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

CMDBActivateFederatedInContext
Description

Privileges
Synopsis

Expands the FederatedInterface instance for a specific CI and federated interface.

Depending on a flag you specify when you call this function, your federated
instance might either be only expanded, or expanded and launched.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBActivateFederatedInContext(
ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

datasetId,

ARNameType

instanceId,

ARNameType

federatedInstanceId,

unsigned int

activateOption,

CMDBFederatedActivateInfo

*federatedInfo,

ARStatusList

*status

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

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

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

instanceId
The instance ID of the specified instance for which the federated instance is to be
expanded or launched.
Chapter 5 C API functions and data structures

153

BMC Atrium CMDB 2.1.00

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

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

Activate none.
CMDB_FEDERATION_ACTIVATION_EXPAND 1 << 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
A list of zero or more notes, warnings, or errors generated from a call of this
function.

154

Developers Reference Guide

Functions

Audit functions
The audit functions retrieve audit data for a class. The C API functions for audit
include:

CMDBGetCopyAuditData (page 155)

CMDBGetLogAuditData (page 157)

CMDBGetCopyAuditData
Description

Privileges
Synopsis

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 attributes characteristic to get the
audit data.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetCopyAuditData(
ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

instanceId,

ARTimestamp

auditTimestamp,

CMDBQualifierStruct

*qualifier,

ARNameList

*attributeGetList,

CMDBSortList

*sortList,

unsigned int

firstRetrieve,

unsigned int

maxRetrieve,

CMDBAuditValueListList

*auditValueListList,

unsigned int

*numMatches,

ARStatusList

*status)

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

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.

Chapter 5 C API functions and data structures

155

BMC Atrium CMDB 2.1.00

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
A list of zero or more notes, warnings, or errors generated from a call of this
function.

156

Developers Reference Guide

Functions

CMDBGetLogAuditData
Description
Privileges
Synopsis

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.
CMDB Administrator
#include "ar.h"
#include "arextern.h"
#include "cmdb.h"
int CMDBGetLogAuditData(
ARControlStruct

*control,

CMDBClassNameId

*classNameId,

ARNameType

instanceId,

ARTextString

*auditLog,

ARStatusList

*status)

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

classNameId
The class name (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
A list of zero or more notes, warnings, or errors generated from a call of this
function.

Chapter 5 C API functions and data structures

157

BMC Atrium CMDB 2.1.00

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

CMDBClassRelationship (page 159)

CMDBIndexList (page 160)

CMDBIndexStruct (page 160)

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.

1The class type is regular. (CMDB_CLASS_TYPE_REGULAR).
2The class type is relationship.
(CMDB_CLASS_TYPE_RELATIONSHIP).

relationshipInfo

158

Developers Reference Guide

If the class type specified in the classType parameter is

relationship, then the relationship information is retrieved.

Data structures

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:
1One-to-one, one instance of a class is associated with
a single instance of another class
(CMDB_CLASS_RELATIONSHIP_CARDINALITY_1).
2Many-to-one, one or more instances of a class are
associated with one instance of another class
(CMDB_CLASS_RELATIONSHIP_CARDINALITY
_MANY_1).
3One-to-many, one instance of a class is associated
with one or more instances of another class
(CMDB_CLASS_RELATIONSHIP_CARDINALITY_1
_MANY).
4Many-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:
TRUEThe role 2 class is a weak reference. Role 2 is a
weak entity and it uses role 1s primary key as part of its
own key. If the value is TRUE, cardinality must be one-toone or many-to-many.
FALSEThe role 2 class is not a weak reference.

Chapter 5 C API functions and data structures

159

BMC Atrium CMDB 2.1.00

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:
TRUEA cascade delete is allowed. Deleting an instance
in one class also deletes the instance in the related class.
FALSEA cascade delete is not allowed.
Note: This item is applicable only for one-to-one and one-

to-many relationships.

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:

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:

TRUEThe index key is unique.
FALSEThe index key is not unique.

160

Developers Reference Guide

Data structures

isPrimaryKey

A Boolean value indicating whether to make this index a

primary key index:
TRUEThe index key is a primary key index.
FALSEThe 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 161)

CMDBAttributeLimitList (page 162)

CMDBAttributeLimit (page 162)

CMDBAttributeNameId (page 166)

CMDBAttributeValueList (page 166)

CMDBAttributeValueListList (page 166)

CMDBAttributeValueStruct (page 167)

CMDBWeakPropagatedAttrs (page 167)

CMDBWeakPropagatedAttrsList (page 167)

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.

1Retrieve all attributes in attributeNameList
(CMDB_GET_ATTR_CUSTOM_LIST).
2Retrieve all attributes except hidden attributes
(CMDB_GET_ATTR_NONHIDDEN).
3Retrieve all attributes (CMDB_GET_ATTR_ALL).

attributeNameList

The name of the attribute list.

Chapter 5 C API functions and data structures

161

BMC Atrium CMDB 2.1.00

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:

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.

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;
char
*rangeHigh;
int
precision;
} decimalLimits;
struct
{
int
minDate;
int
maxDate;

162

Developers Reference Guide

Data structures

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

CMDB_ATTR_DATA_TYPE_NULL

Specifies a NULL value.

CMDB_ATTR_DATA_TYPE_KEYWORD

An integer identifying the

particular keyword (defined in
cmdb.h).

CMDB_ATTR_DATA_TYPE_INTEGER

A 32-bit signed integer value.

CMDB_ATTR_DATA_TYPE_REAL

A 64-bit floating-point value.

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.

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.

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.

Chapter 5 C API functions and data structures

163

BMC Atrium CMDB 2.1.00

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

Defining character limits

The charLimits structure is used to hold data limit definitions for the character
data type. It consists of the following elements:
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.

Defining real limits

The realLimits structure is used to hold data limit definitions for the real data
type. It consists of the following elements:

164

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.

Developers Reference Guide

Data structures

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

The minimum limit for the date data type.

maxDate

The maximum limit for the date data type.

Defining enum limits

The enumLimits structure is used to hold data limit definitions for the enum data
type. It consists of the following element:
regularList

A name list of possible selection values for the enum data type.

Defining currency limits

The currencyLimits structure is used to hold data limit definitions for the currency
data type. It consists of the following elements:
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.

Defining attachment limits

The attachLimits structure is used to hold data limit definitions for the attachment
data type. It consists of the following elements:
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.

Chapter 5 C API functions and data structures

165

BMC Atrium CMDB 2.1.00

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

namespaceName

The namespace name for the class.

className

The name of the class.

attributeName

The name of the attribute.

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:

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:

166

numItems

An integer value indicating the number of

CMDBAttributeValueList items in the list.

attributeValueListList

A list of CMDBAttributeValueList items.

Developers Reference Guide

Data structures

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:

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:

sourceAttributeName

The name of the attribute on the role one class.

targetAttributeName

The name of the attribute on the role two class.

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:

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.

Chapter 5 C API functions and data structures

167

BMC Atrium CMDB 2.1.00

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:

numItems

An integer value indicating the number of CMDBSortStruct

items in the list.

sortList

A list of CMDBSortStruct items.

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:

attributeName

The name of the attribute to sort.

sortOrder

An integer value indicating sort order.

1Sort attributes in ascending order
(CMDB_SORT_ASCENDING).
2Sort attributes in descending order
(CMDB_SORT_DESCENDING).

168

Developers Reference Guide

Data structures

Instance structures
Instance structures are data structures for instance data. The instance data
structures include:

CMDBClassNameId (page 169)

CMDBClassNameIdList (page 169)

CMDBQualifierStruct (page 170)

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:

namespaceName

The namespace name of the class.

className

The name of the class.

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:

numItems

An integer value indicating the number of

CMDBClassNameIditems in the list.

classNameIdList

The list of class names.

Chapter 5 C API functions and data structures

169

BMC Atrium CMDB 2.1.00

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.

1The qualifier is a string
(CMDB_QUALIFIER_TYPE_STRING).
2The qualifier is a structure
(CMDB_QUALIFIER_TYPE_STRUCT).

170

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.

Developers Reference Guide

Data structures

General purpose structures

General purpose structures are structures for miscellaneous uses. The general
purpose data structures include:

CMDBVersionInfo (page 171)

CMDBVersionInfoList (page 171)

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:

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.

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;

The CMDBVersionInfoList structure consists of the following elements:

numItems

The number of items in the list.

versionInfoList

A list of version information.

Chapter 5 C API functions and data structures

171

BMC Atrium CMDB 2.1.00

Export and import structures

Export/Import structures are used for export and import functions. The export
and import structures include:

CMDBItemTypeClass (page 172)

CMDBItemTypeAttribute (page 173)

CMDBExportItem (page 173)

CMDBExportItemList (page 174)

CMDBExportItemStruct (page 174)

CMDBXMLExportItemList (page 174)

CMDBImportItem (page 175)

CMDBImportItemList (page 176)

CMDBImportItemStruct (page 176)

CMDBXMLImportItemList (page 176)

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:

classNameId

172

Developers Reference Guide

The ID for the class.

Data structures

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:

classNameId

The ID of the class name.

attributeNameList

The list of attribute names.

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
CMDBItemTypeAttribute
}
}CMDBExportItem;

classItem;
attributeItem;

The CMDBExportItem structure consists of the following elements:

itemType

The type of item to export.

0No item to export
(CMDB_ITEM_TYPE_NONE).
1Export class
(CMDB_ITEM_TYPE_CLASS).
2Export attribute

(CMDB_ITEM_TYPE_ATTRIBUTE).
classItem
attributeItem

The class items to import, if the itemType is

CMDB_ITEM_TYPE_CLASS.
The attribute items to import, if the itemType is
CMDB_ITEM_TYPE_ATTRIBUTE.

Chapter 5 C API functions and data structures

173

BMC Atrium CMDB 2.1.00

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:

numItems

An integer value indicating the number of

CMDBExportItemStruct items in the list.

exportItemList

The list of items to export.

CMDBXMLExportItemList
The CMDBXMLExportItemList data structure is used to hold a list of items to export.
typedef struct CMDBXMLExportItemList
unsigned int
CMDBXMLExportItemStruct
}CMDBXMLExportItemList;

numItems;
*exportItemList;

The CMDBXMLExportItemList structure consists of the following elements:

numItems

An integer value indicating the number of

CMDBXMLExportItem items in the list.

exportItemList

A structure that holds the list of items to export.

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;

The CMDBExportItemStruct structure consists of the following elements:

itemType

An integer value indicating the type of information to export.

1Export (CMDB_ITEM_TYPE_META_DATA).
2Export instance data.
(CMDB_ITEM_TYPE_INSTANCE_DATA).

classNameId

174

Developers Reference Guide

The namespace name and the class name of the class that
contains the items to export.

Data structures

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.
1Export the class only
(CMDB_EXPORT_OPTION_CLASS_ONLY).
2Export superclasses
(CMDB_EXPORT_OPTION_SUPER_CLASSES).
4Export subclasses (CMDB_EXPORT_OPTION_SUB_CLASSES).
Note: This item is applicable only if
CMDB_ITEM_TYPE_META_DATA is set.

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
CMDBItemTypeAttribute
}
}CMDBImportItem;

classItem;
attributeItem;

The CMDBImportItem structure consists of the following elements:

itemType

The type of item to import.

0No item to import
(CMDB_ITEM_TYPE_NONE).
1Import class
(CMDB_ITEM_TYPE_CLASS).
2Import attribute

(CMDB_ITEM_TYPE_ATTRIBUTE).
classItem

The class item to import.

attributeItem

The attribute item to import.

Chapter 5 C API functions and data structures

175

BMC Atrium CMDB 2.1.00

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:

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.

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;

The CMDBXMLImportItemList 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.

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:

itemType

An integer value indicating the type of information to

import.
1Import (CMDB_ITEM_TYPE_META_DATA).
2Import instance data (CMDB_ITEM_TYPE_INSTANCE_DATA)

classNameId

176

Developers Reference Guide

The namespace name and the class name of the class that
contains the items to import.

Data structures

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.
1Generate an error (AR_MERGE_ENTRY_DUP_ERROR).
2Create 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).
3Delete 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).
4Update 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).
5Create 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.

Chapter 5 C API functions and data structures

177

BMC Atrium CMDB 2.1.00

Graph query structures

Graph query structures are data structures used in graph queries. The export and
import data structures include:

CMDBGetObjectList (page 178)

CMDBGetObjectStruct (page 178)

CMDBGetRelationList (page 179)

CMDBGetRelationStruct (page 179)

CMDBGraphAdjacentList (page 179)

CMDBGraphAdjacentStruct (page 180)

CMDBGraphList (page 180)

CMDBGraphStruct (page 181)

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:

numItems

An integer value indicating the number of

CMDBGetObjectStruct items in the list.

objectList

The list of CI instances.

CMDBGetObjectStruct
The CMDBGetObjectStruct data structure is used to hold a CI instance.
typedef struct CMDBGetObjectStruct
{
CMDBClassNameId
classNameId;
ARNameType
instanceId;
CMDBAttributeValueList attributeValueList;
} CMDBGetObjectStruct;

The CMDBGetObjectStruct structure consists of the following elements:

178

classNameId

The class name ID for the class.

instanceId

The instance ID of the object.

attributeValueList

The list of attribute values.

Developers Reference Guide

Data structures

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:

numItems

An integer value indicating the number of

CMDBGetRelationStruct items in the list.

relationList

The list of relationships.

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

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.

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;

Chapter 5 C API functions and data structures

179

BMC Atrium CMDB 2.1.00

The CMDBGraphAdjacentList structure consists of the following elements:

numItems

An integer value indicating the number of

CMDBGraphAdjacentStruct items in the list.

adjacents

The list of adjacent nodes.

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:

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.

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.

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:

180

numItems

An integer value indicating the number of CMDBGraphStruct

items in the list.

graph

The graph structure.

Developers Reference Guide

Data structures

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:

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

CMDBUIComponentResult (page 182)

CMDBUIComponentResultList (page 183)

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.

Chapter 5 C API functions and data structures

181

BMC Atrium CMDB 2.1.00

componentType

The integer value indicating the component type.

0No component information to retrieve
(CMDB_COMPONENT_TYPE_NONE).
1The icon type component to retrieve
(CMDB_COMPONENT_TYPE_ICON).
2The localized label type component to retrieve
(CMDB_COMPONENT_TYPE_LOCALIZED_LABEL).
3The tooltip type component to retrieve
(CMDB_COMPONENT_TYPE_TOOLTIP).
4The 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.

tag2

Information tag used to filter a specific component type.

tag3

Information tag used to filter a specific component type.

tag4

Information tag used to filter a specific component type.

tag5

Information tag used to filter a specific component type.

encodedQual

The encoded qualifier for the UI component query.

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:

182

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.

Developers Reference Guide

Data structures

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:

numItems

An integer value indicating the number of

CMDBUIComponent items in the list.

componentResultList

Contains a list of UI components.

Reconciliation Engine structures

Reconciliation Engine structures are data structures used in Reconciliation Engine
queries. The Reconciliation Engine data structures include:

CMDBREJobRunInfoList (page 183)

CMDBREJobRunInfo (page 184)

CMDBREClassQualStruct (page 184)

CMDBREClassQualList (page 185)

CMDBREDatasetPair (page 185)

CMDBREDatasetList (page 185)

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;

The CMDBREJobRunInfoList structure consists of the following elements:

numItems

An integer value indicating the number of

CMDBREJobRunInfo items in the list.

jobRunList

The list of Reconciliation Engine jobs to execute.

Chapter 5 C API functions and data structures

183

BMC Atrium CMDB 2.1.00

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:

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.

CMDBREClassQualStruct
The CMDBREClassQualStruct data structure is used to hold information about the
class qualification.
typedef struct CMDREBClassQualStruct
{
ARNameType
classId;
CMDBQualifierStruct
*qual;
}CMDBREClassQualStruct;

The CMDBREClassQualStruct structure consists of the following elements:

184

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.

Developers Reference Guide

Data structures

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:

numItems

An integer value indicating the number of

CMDBREClassQualStruct structure items in the list.

classQualList

A list of CMDBClassQualStruct structures.

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:

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:

numItems

An integer value indicating the number of

CMDBREDatasetPair items in the list.

datasetList

A list of CMDBREDatasetPair items.

Chapter 5 C API functions and data structures

185

BMC Atrium CMDB 2.1.00

Federation structures
Federation structures are data structures used in federation functions. The
federation structures include:

CMDBFederatedARInfo (page 186)

CMDBFederatedActivateInfo (page 186)

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;

The CMDBFederatedARInfo structure consists of the following elements:

arAccessType

The access type for the AR System.

0Retrieve AR System URL
(CMDB_FEDERATED_ACCESS_TYPE_AR_URL).
1Retrieve 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.

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;

186

Developers Reference Guide

Data structures

The CMDBFederatedActivateInfo structure consists of the following elements:

actionType

The action to perform.

0Activate none.
(CMDB_FEDERATION_ACTIVATION_NONE).
1<<0Return the expanded federated interface data.
(CMDB_FEDERATION_ACTIVATION_EXPAND).
1<<0Expand and launch the federated interface.
(CMDB_FEDERATION_ACTIVATION_LAUNCH).

accessType

The type of access required.

0Access an AR System form for the federated interface
(CMDB_FEDERATED_ACCESS_TYPE_AR).
1Access a URL for the federated interface
(CMDB_FEDERATED_ACCESS_TYPE_URL).
2Use a web service for the federated interface
(CMDB_FEDERATED_ACCESS_TYPE_WEBSERVICE).
3Start a process for the federated interface
(CMDB_FEDERATED_ACCESS_TYPE_PROCESS).
4Access a manual launch link information for the federated

interface
(CMDB_FEDERATED_ACCESS_TYPE_MANUAL).
5Access 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.

Chapter 5 C API functions and data structures

187

BMC Atrium CMDB 2.1.00

Audit structures
Audit structures are data structures used in audit functions. The audit structures
include:

CMDBAuditValueList (page 188)

CMDBAuditValueListList (page 189)

CMDBAuditInfoStruct (page 189)

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.

0No audit operation performed.
(CMDB_AUDIT_OPERATION_NONE).
1The modify operation performed
(CMDB_AUDIT_OPERATION_SET).
2The create operation performed
(CMDB_AUDIT_OPERATION_CREATE).
3The delete operation performed
(CMDB_AUDIT_OPERATION_DELETE).
4The merge operation performed
(CMDB_AUDIT_OPERATION_MERGE).

188

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.

Developers Reference Guide

Data structures

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:

numItems

An integer value indicating the number of

CMDBAuditValueList structure items in the list.

attrAuditValueList

The list of audit value list.

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:

type

The type of audit option to set.

0None

No auditing option set.

1Copy

Create a copy of an instance when an attribute is modified.

2Log

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 5 C API functions and data structures

189

BMC Atrium CMDB 2.1.00

190

Developers Reference Guide

Chapter

Web services API operations

and data structures
This section provides reference information for the web services API operations
and data structures.
The following topics are provided:

Operations (page 192)

Data structures (page 227)

Chapter 6 Web services API operations and data structures

191

BMC Atrium CMDB 2.1.00

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

SetInstance (page 195)

CreateInstance (page 196)

DeleteInstance (page 197)

CreateRelationInstance (page 199)

GraphQuery (page 201)

192

Developers Reference Guide

Operations

GetInstances
Description
Privileges
Synopsis

Input
arguments

Retrieves a list of instances. You can limit the retrieved instance result-set by
specifying a qualification.
CMDB Administrator
<wsdl:operation name="GetInstances" parameterOrder="inargs">
<wsdl:input message="tns:GetInstancesRequest"
name="GetInstancesRequest"/>
<wsdl:output message="tns:GetInstancesResponse"
name="GetInstancesResponse"/>
</wsdl:operation>
<wsdl:message name="GetInstancesRequest">
<wsdl:part element="tns:GetInstances" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetInstancesResponse">
<wsdl:part element="tns:GetInstancesOutput" name="outargs"/>
</wsdl:message>
<element name="GetInstances">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="query" type="xsd:string"/>
<element name="attributes" type="impl:ArrayOf_String"/>
<element name="firstRetrieve" type="xsd:int"/>
<element name="maxRetrieve" type="xsd:int"/>
<element name="sortOrder" type="tns:SortOrderList"/>
<element name="aDatasetId" type="xsd:string"/>
<element name="aGetMask" type="tns:GetMask"/>
</sequence>
</complexType>
</element>
<element name="GetInstancesOutput">
<complexType>
<sequence>
<element name="instanceInfo" type="impl:InstanceInfoList"/>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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.

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.
Chapter 6 Web services API operations and data structures

193

BMC Atrium CMDB 2.1.00

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
The unique identifier for the dataset. The data in the return values are based on the
dataset ID specified in this parameter.

aGetMask
The identifier for specifying the dataset type.
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.

194

Developers Reference Guide

Operations

SetInstance
Description
Privileges

Sets a CI or relationship instance of the specified class.

CMDB Administrator
<wsdl:operation name="SetInstance" parameterOrder="inargs">
<wsdl:input message="tns:SetInstanceRequest"
name="SetInstanceRequest"/>
<wsdl:output message="tns:SetInstanceResponse"
name="SetInstanceResponse"/>
</wsdl:operation>
<wsdl:message name="SetInstanceRequest">
<wsdl:part element="tns:SetInstance" name="inargs"/>
</wsdl:message>
<wsdl:message name="SetInstanceResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="SetInstance">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="instanceId" type="xsd:string"/>
<element name="aDatasetId" type="xsd:string"/>
<element name="attributes" type="impl:AttributeValueList"/>
</sequence>
</complexType>
</element>
<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

classNameId
The class for which the instance is to be set. It is a two-part structure that contains
the namespace and the class name.

instanceId
The unique identifier for the instance.

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

Chapter 6 Web services API operations and data structures

195

BMC Atrium CMDB 2.1.00

attributes
A list of one or more name and value pairs (specified in any order) that identifies
the data for the new attribute. You must specify values for all required subclasses
that do not have defined defaults.
Values must be of the data type defined for the subclasses or have a data type of 0.
NULL values can be specified for optional attribute names only. An error is
generated if an attribute does not exist or the user specified in the loginInfo
parameter does not have the write permission for an attribute name.
Return values

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

CreateInstance
Description
Privileges
Synopsis

Input
arguments

196

Creates a CI instance of the specified class.

CMDB Administrator
<wsdl:operation name="CreateInstance" parameterOrder="inargs">
<wsdl:input message="tns:CreateInstanceRequest"
name="CreateInstanceRequest"/>
<wsdl:output message="tns:CreateInstanceResponse"
name="CreateInstanceResponse"/>
</wsdl:operation>
<wsdl:message name="CreateInstanceRequest">
<wsdl:part element="tns:CreateInstance" name="inargs"/>
</wsdl:message>
<wsdl:message name="CreateInstanceResponse">
<wsdl:part element="tns:CreateInstanceOutput" name="outargs"/>
</wsdl:message>
<element name="CreateInstance">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="aDatasetId" type="xsd:string"/>
<element name="attributes" type="impl:AttributeValueList"/>
</sequence>
</complexType>
</element>
<element name="CreateInstanceOutput">
<complexType>
<sequence>
<element name="instanceId" type="xsd:string"/>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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.

Developers Reference Guide

Operations

classNameId
The class for which the instance is to be created. It is a two-part structure that
contains the namespace and the class name.

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

attributes
A list of one or more name and value pairs (specified in any order) that identifies
the data for the new attribute. You must specify values for all required subclasses
that do not have defined defaults. Values must be of the data type defined for the
subclasses or have a data type of 0. NULL values can be specified for optional
attribute names only. An error is generated if an attribute does not exist or the user
specified in the loginInfo parameter does not have the write permission for an
attribute name.
Return values

instanceId
The unique identifier for the new attribute.

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

DeleteInstance
Description
Privileges
Synopsis

Deletes an instance of a class.

CMDB Administrator
<wsdl:operation name="DeleteInstance" parameterOrder="inargs">
<wsdl:input message="tns:DeleteInstanceRequest"
name="DeleteInstanceRequest"/>
<wsdl:output message="tns:DeleteInstanceResponse"
name="DeleteInstanceResponse"/>
</wsdl:operation>
<wsdl:message name="DeleteInstanceRequest">
<wsdl:part element="tns:DeleteInstance" name="inargs"/>
</wsdl:message>
<wsdl:message name="DeleteInstanceResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="DeleteInstance">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="instanceId" type="xsd:string"/>
<element name="aDatasetId" type="xsd:string"/>
<element name="deleteOption" type="impl:InstanceDeleteOption"/>
</sequence>
</complexType>

Chapter 6 Web services API operations and data structures

197

BMC Atrium CMDB 2.1.00

</element>
<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

classNameId
The class from which the instance is to be deleted. It is a two-part structure that
contains the namespace and the class name.

instanceId
The unique identifier for the instance.

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

deleteOption
DERIVED_INSTANCE_FOUND:

Allows you to delete only the specified instance, if the

instance is retrieved.
Allows you to delete the instance even when the instance
cannot be retrieved . Errors will be ignored for instances that do not exist.

UNCONDITIONALLY:

Return values

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

198

Developers Reference Guide

Operations

CreateRelationInstance
Description
Privileges
Synopsis

Input
arguments

Creates relationship instances for the specified CIs.

CMDB Administrator
<wsdl:operation name="CreateRelationInstance">
<wsdlsoap:operation soapAction="CreateRelationInstance"
style="document"/>
<wsdl:input name="CreateRelationInstanceRequest">
<wsdlsoap:body parts="inargs" use="literal"/>
</wsdl:input>
<wsdl:output name="CreateRelationInstanceResponse">
<wsdlsoap:body parts="outargs" use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:message name="CreateRelationInstanceRequest">
<wsdl:part element="tns:CreateRelationInstance" name="inargs"/>
</wsdl:message>
<wsdl:message name="CreateRelationInstanceResponse">
<wsdl:part element="tns:CreateInstanceOutput" name="outargs"/>
</wsdl:message>
<xsd:element name="CreateRelationInstance">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="loginInfo" type="tns:LoginInfo"/>
<xsd:element name="classNameId" type="tns:ClassNameId"/>
<xsd:element name="role1Name" type="xsd:string"/>
<xsd:element name="instance1Id" type="xsd:string"/>
<xsd:element name="class1Id" type="xsd:string"/>
<xsd:element name="role2Name" type="xsd:string"/>
<xsd:element name="instance2Id" type="xsd:string"/>
<xsd:element name="class2Id" type="xsd:string"/>
<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>

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

classNameId
The class in which the relationship instance is to be created. It is a two-part
structure that contains the namespace and the class name.

Chapter 6 Web services API operations and data structures

199

BMC Atrium CMDB 2.1.00

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
A list of zero or more notes, warnings, or errors generated from a call of this
operation.

200

Developers Reference Guide

Operations

GraphQuery
Description
Privileges
Synopsis

Input
arguments

Queries related instances for the specified CI.

CMDB Administrator
<wsdl:operation name="GraphQuery" parameterOrder="inargs">
<wsdl:input message="tns:GraphQueryRequest"
name="GraphQueryRequest"/>
<wsdl:output message="tns:GraphQueryResponse"
name="GraphQueryResponse"/>
</wsdl:operation>
<wsdl:message name="GraphQueryRequest">
<wsdl:part element="tns:GraphQuery" name="inargs"/>
</wsdl:message>
<wsdl:message name="GraphQueryResponse">
<wsdl:part element="tns:GraphQueryOutput" name="outargs"/>
</wsdl:message>
<element name="GraphQuery">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="startClassNameId" type="impl:ClassNameId"/>
<element name="startExtensionId" type="xsd:string"/>
<element name="startInstanceId" type="xsd:string"/>
<element name="numLevels" type="xsd:int"/>
<element name="direction" type="impl:GraphDirection"/>
<element name="noMatchProceed" type="xsd:boolean"/>
<element name="onMatchProceed" type="xsd:boolean"/>
<element name="graph" type="impl:GraphList"/>
<element name="aGetMask" type="tns:GetMask"/>
<element name="aDatasetId" type="xsd:string"/>
</sequence>
</complexType>
</element>
<element name="GraphQueryOutput">
<complexType>
<sequence>
<element name="objects" type="impl:ObjectQueryInfoList"/>
<element name="relations"
type="impl:RelationQueryInfoList"/>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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.

startClassNameId
The name of the starting node class in the CI graph.

Chapter 6 Web services API operations and data structures

201

BMC Atrium CMDB 2.1.00

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.

noMatchProceed
T (1):

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

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

onMatchProceed
T (1):

When the node returned for a given relationship instance matches the criteria
specified, proceed to the next relationship.
F (0):

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

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

aGetMask
The identifier for specifying the dataset type.

202

Developers Reference Guide

Operations

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
The unique identifier for the dataset. The data in the return values are based on the
dataset ID specified in this parameter.
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 links the CIs
returned.

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

Chapter 6 Web services API operations and data structures

203

BMC Atrium CMDB 2.1.00

Data model operations

The data model operations act on classes and their attributes in the data model. The
data model operations include:

GetClass (page 204)

SetClass (page 205)

CreateClass (page 206)

ListClasses (page 207)

DeleteClass (page 209)

GetAttributes (page 210)

SetAttribute (page 212)

CreateAttribute (page 211)

Delete Attribute (page 213)

GetClass
Description
Privileges
Synopsis

204

Retrieves the class information.

CMDB Administrator
<wsdl:operation name="GetClass" parameterOrder="inargs">
<wsdl:input message="tns:GetClassRequest" name="GetClassRequest"/>
<wsdl:output message="tns:GetClassResponse"
name="GetClassResponse"/>
</wsdl:operation>
<wsdl:message name="GetClassRequest">
<wsdl:part element="tns:GetClass" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetClassResponse">
<wsdl:part element="tns:GetClassOutput" name="outargs"/>
</wsdl:message>
<element name="GetClass">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
</sequence>
</complexType>
</element>
<element name="GetClassOutput">
<complexType>
<sequence>
<element name="classInfo" type="impl:ClassInfoOut"/>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

Developers Reference Guide

Operations

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

classNameID
The class 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
A list of zero or more notes, warnings, or errors generated from a call of this
operation.

SetClass
Sets the properties for a specified class.
Privileges
Synopsis

Input
arguments

CMDB Administrator
<wsdl:operation name="SetClass" parameterOrder="inargs">
<wsdl:input message="tns:SetClassRequest" name="SetClassRequest"/>
<wsdl:output message="tns:SetClassResponse"
name="SetClassResponse"/>
</wsdl:operation>
<wsdl:message name="SetClassRequest">
<wsdl:part element="tns:SetClass" name="inargs"/>
</wsdl:message>
<wsdl:message name="SetClassResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="SetClass">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="newClassNameId" type="impl:ClassNameId"/>
<element name="classInfo" type="impl:ClassInfoIn"/>
</sequence>
</complexType>
</element>
<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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.

Chapter 6 Web services API operations and data structures

205

BMC Atrium CMDB 2.1.00

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.
Return values

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

CreateClass
Creates a class with core attributes.
Privileges
Synopsis

Input
arguments

206

CMDB Administrator
<wsdl:operation name="CreateClass" parameterOrder="inargs">
<wsdl:input message="tns:CreateClassRequest"
name="CreateClassRequest"/>
<wsdl:output message="tns:CreateClassResponse"
name="CreateClassResponse"/>
</wsdl:operation>
<wsdl:message name="CreateClassRequest">
<wsdl:part element="tns:CreateClass" name="inargs"/>
</wsdl:message>
<wsdl:message name="CreateClassResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="CreateClass">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="superclassNameId" type="impl:ClassNameId"/>
<element name="classId" type="xsd:string"/>
<element name="classInfo" type="impl:ClassInfoIn"/>
</sequence>
</complexType>
</element>
<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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.

Developers Reference Guide

Operations

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.
Return values

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

ListClasses
Description

Privileges
Synopsis

Retrieves information about relationship classes for a specified class. The classes
that are retrieved will have the class that is specified in the relatedClass parameter
as part of the relationship.
CMDB Administrator
<wsdl:operation name="ListClasses">
<wsdlsoap:operation soapAction="ListClasses" style="document"/>
<wsdl:input name="ListClassesRequest">
<wsdlsoap:body parts="inargs" use="literal"/>
</wsdl:input>
<wsdl:output name="ListClassesResponse">
<wsdlsoap:body parts="outargs" use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:message name="ListClassesRequest">
<wsdl:part element="tns:ListClassesInput" name="inargs"/>
</wsdl:message>
<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"/>

Chapter 6 Web services API operations and data structures

207

BMC Atrium CMDB 2.1.00

</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ListClassesOutput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="classList" type="tns:ClassNameIdList"/>
<xsd:element name="status" type="tns:StatusList"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

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.
Return values

classList
A list of class names that match the specified criteria.

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

208

Developers Reference Guide

Operations

DeleteClass
Description
Privileges
Synopsis

Input
arguments

Deletes a specified class. Also deletes the associated attributes of the class.
CMDB Administrator
<wsdl:operation name="DeleteClass" parameterOrder="inargs">
<wsdl:input message="tns:DeleteClassRequest"
name="DeleteClassRequest"/>
<wsdl:output message="tns:DeleteClassResponse"
name="DeleteClassResponse"/>
</wsdl:operation>
<wsdl:message name="DeleteClassRequest">
<wsdl:part element="tns:DeleteClass" name="inargs"/>
</wsdl:message>
<wsdl:message name="DeleteClassResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="DeleteClass">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="option" type="impl:ClassDeleteOption"/>
</sequence>
</complexType>
</element>
<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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

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.
OPTION_ALL_DEPENDENCIES:

Chapter 6 Web services API operations and data structures

209

BMC Atrium CMDB 2.1.00

Return values

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

GetAttributes
Description
Privileges
Synopsis

Input
arguments

Retrieves information about a list of attributes

CMDB Administrator
<wsdl:operation name="GetAttributes" parameterOrder="inargs">
<wsdl:input message="tns:GetAttributesRequest"
name="GetAttributesRequest"/>
<wsdl:output message="tns:GetAttributesResponse"
name="GetAttributesResponse"/>
</wsdl:operation>
<wsdl:message name="GetAttributesRequest">
<wsdl:part element="tns:GetAttributes" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetAttributesResponse">
<wsdl:part element="tns:GetAttributesOutput" name="outargs"/>
</wsdl:message>
<element name="GetAttributes">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="attributeNames" type="impl:ArrayOf_String"/>
</sequence>
</complexType>
</element>
<element name="GetAttributesOutput">
<complexType>
<sequence>
<element name="attributeInfoList" type="impl:AttributeInfoList"/>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

classNameId
The class for which the 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

attributeInfoList
The information about the list of attributes.

210

Developers Reference Guide

Operations

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

CreateAttribute
Description
Privileges
Synopsis

Input
arguments

Creates an attribute for the specified class.

CMDB Administrator
<wsdl:operation name="CreateAttribute" parameterOrder="inargs">
<wsdl:input message="tns:CreateAttributeRequest"
name="CreateAttributeRequest"/>
<wsdl:output message="tns:CreateAttributeResponse"
name="CreateAttributeResponse"/>
</wsdl:operation>
<wsdl:message name="CreateAttributeRequest">
<wsdl:part element="tns:CreateAttribute" name="inargs"/>
</wsdl:message>
<wsdl:message name="CreateAttributeResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="CreateAttribute">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="attributeName" type="xsd:string"/>
<element name="attributeId" type="xsd:string"/>
<element name="fieldId" type="xsd:long"/>
<element name="attributeInfo" type="impl:AttributeInfoIn"/>
</sequence>
</complexType>
</element>
<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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

Chapter 6 Web services API operations and data structures

211

BMC Atrium CMDB 2.1.00

attributeId
The 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.

attributeInfo
The value limits for the attribute and other properties specific to the attributes
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.
Return values

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

SetAttribute
Description
Privileges
Synopsis

212

Sets an attribute for the specified class.

CMDB Administrator
<wsdl:operation name="SetAttribute" parameterOrder="inargs">
<wsdl:input message="tns:SetAttributeRequest"
name="SetAttributeRequest"/>
<wsdl:output message="tns:SetAttributeResponse"
name="SetAttributeResponse"/>
</wsdl:operation>
<wsdl:message name="SetAttributeRequest">
<wsdl:part element="tns:SetAttribute" name="inargs"/>
</wsdl:message>
<wsdl:message name="SetAttributeResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="SetAttribute">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="attributeName" type="xsd:string"/>
<element name="newAttributeName" type="xsd:string"/>
<element name="attributeInfo" type="impl:AttributeInfoIn"/>
</sequence>
</complexType>
</element>
<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

Developers Reference Guide

Operations

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

classNameId
The class 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 attributes
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.
Return values

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

Delete Attribute
Description
Privileges
Synopsis

Deletes the attribute with the specified name.

CMDB Administrator
<wsdl:operation name="DeleteAttribute" parameterOrder="inargs">
<wsdl:input message="tns:DeleteAttributeRequest"
name="DeleteAttributeRequest"/>
<wsdl:output message="tns:DeleteAttributeResponse"
name="DeleteAttributeResponse"/>
</wsdl:operation>
<wsdl:message name="DeleteAttributeRequest">
<wsdl:part element="tns:DeleteAttribute" name="inargs"/>
</wsdl:message>
<wsdl:message name="DeleteAttributeResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="DeleteAttribute">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="classNameId" type="impl:ClassNameId"/>
<element name="attributeName" type="xsd:string"/>
</sequence>
</complexType>
</element>

Chapter 6 Web services API operations and data structures

213

BMC Atrium CMDB 2.1.00

<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

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

attributeName
The name of the attribute to delete.
Return values

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

214

Developers Reference Guide

Operations

Reconciliation Engine operations

The Reconciliation Engine operations act on reconciliation jobs. The Reconciliation
Engine operations include:

ExecuteJobRun (page 215)

GetJobRun (page 216)

GetListJobRun (page 217)

CancelJobRun (page 218)

ExecuteJobRun
Description
Privileges
Synopsis

Input
arguments

Starts a job.
CMDB Administrator
<wsdl:operation name="ExecuteJobRun" parameterOrder="inargs">
<wsdl:input message="tns:ExecuteJobRunRequest"
name="ExecuteJobRunRequest"/>
<wsdl:output message="tns:ExecuteJobRunResponse"
name="ExecuteJobRunResponse"/>
</wsdl:operation>
<wsdl:message name="ExecuteJobRunRequest">
<wsdl:part element="tns:ExecuteJobRun" name="inargs"/>
</wsdl:message>
<wsdl:message name="ExecuteJobRunResponse">
<wsdl:part element="tns:ExecuteJobRunOutput" name="outargs"/>
</wsdl:message>
<element name="ExecuteJobRun">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="jobName" type="xsd:string"/>
<xsd:element name="qualifierList"
type="tns:ClassQualifierList"/>
<xsd:element name="datasetList"
type="tns:DatasetPairList"/>
</sequence>
</complexType>
</element>
<element name="ExecuteJobRunOutput">
<complexType>
<sequence>
<element name="jobId" type="xsd:string"/>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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.

Chapter 6 Web services API operations and data structures

215

BMC Atrium CMDB 2.1.00

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
A list of zero or more notes, warnings, or errors generated from a call to this
operation.

GetJobRun
Description

Privileges
Synopsis

216

Retrieves information about a currently running job. For information about

interpreting job run logs and job run information, see the section Viewing job
status, results, and history in the Installation and Configuration Guide.
CMDB Administrator
<wsdl:operation name="GetJobRun" parameterOrder="inargs">
<wsdl:input message="tns:GetJobRunRequest"
name="GetJobRunRequest"/>
<wsdl:output message="tns:GetJobRunResponse"
name="GetJobRunResponse"/>
</wsdl:operation>
<wsdl:message name="GetJobRunRequest">
<wsdl:part element="tns:GetJobRun" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetJobRunResponse">
<wsdl:part element="tns:GetJobRunOutput" name="outargs"/>
</wsdl:message>
<element name="GetJobRun">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="jobId" type="xsd:string"/>
</sequence>
</complexType>
</element>
<element name="GetJobRunOutput">
<complexType>
<sequence>
<element name="jobRunInfo" type="impl:JobRunInfo"/>
<element name="jobLog" type="xsd:string"/>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

Developers Reference Guide

Operations

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

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
A list of zero or more notes, warnings, or errors generated from a call to this
operation.

GetListJobRun
Description
Privileges
Synopsis

Retrieves information about a list of currently running jobs.

CMDB Administrator
<wsdl:operation name="GetListJobRun" parameterOrder="inargs">
<wsdl:input message="tns:GetListJobRunRequest"
name="GetListJobRunRequest"/>
<wsdl:output message="tns:GetListJobRunResponse"
name="GetListJobRunResponse"/>
</wsdl:operation>
<wsdl:message name="GetListJobRunRequest">
<wsdl:part element="tns:GetListJobRun" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetListJobRunResponse">
<wsdl:part element="tns:GetListJobRunOutput" name="outargs"/>
</wsdl:message>
<element name="GetListJobRun">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="qualifier" type="xsd:string"/>
</sequence>
</complexType>
</element>
<element name="GetListJobRunOutput">
<complexType>
<sequence>
<element name="jobRunInfo" type="impl:JobRunInfoList"/>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

Chapter 6 Web services API operations and data structures

217

BMC Atrium CMDB 2.1.00

Input
argument

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.

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
A list of zero or more notes, warnings, or errors generated from a call to this
operation.

CancelJobRun
Description
Privileges
Synopsis

Input
arguments

218

Stops a currently running job.

CMDB Administrator
<wsdl:operation name="CancelJobRun" parameterOrder="inargs">
<wsdl:input message="tns:CancelJobRunRequest"
name="CancelJobRunRequest"/>
<wsdl:output message="tns:CancelJobRunResponse"
name="CancelJobRunResponse"/>
</wsdl:operation>
<wsdl:message name="CancelJobRunRequest">
<wsdl:part element="tns:CancelJobRun" name="inargs"/>
</wsdl:message>
<wsdl:message name="CancelJobRunResponse">
<wsdl:part element="tns:StatusOutput" name="outargs"/>
</wsdl:message>
<element name="CancelJobRun">
<complexType>
<sequence>
<element name="loginInfo" type="impl:LoginInfo"/>
<element name="jobId" type="xsd:string"/>
</sequence>
</complexType>
</element>
<element name="StatusOutput">
<complexType>
<sequence>
<element name="status" type="impl:StatusList"/>
</sequence>
</complexType>
</element>

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.

Developers Reference Guide

Operations

jobId
The ID of the job.
Return values

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

Federation operations
The federation functions manipulate the federated data for an instance. The web
services functions for federation includes:

ActivateFederatedInContext (page 219)

GetRelatedFederatedInContext (page 221)

ActivateFederatedInContext
Description

Privileges
Synopsis

Expands the FederatedInterface instance for a specific CI and federated interface.

Depending on a flag you specify when you call this function, your federated
instance might either be only expanded or expanded and launched.
CMDB Administrator
<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"

Chapter 6 Web services API operations and data structures

219

BMC Atrium CMDB 2.1.00

type="tns:FederatedActivateInfo"/>
<xsd:element name="status" type="tns:StatusList"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

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

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

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

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

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

No specific operation to be performed.

ACTIVATION_EXPAND:

Only expand the federated interface.

ACTIVATION_LAUNCH:

Expand and launch the federated interface.

Return values

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

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

220

Developers Reference Guide

Operations

GetRelatedFederatedInContext
Description
Privileges
Synopsis

Input
arguments

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

CMDB Administrator
<wsdl:operation name="GetRelatedFederatedInContext"
parameterOrder="inargs">
<wsdl:input message="tns:GetRelatedFederatedInContextRequest"
name="GetRelatedFederatedInContextRequest"/>
<wsdl:output message="tns:GetRelatedFederatedInContextResponse"
name="GetRelatedFederatedInContextResponse"/>
</wsdl:operation>
<wsdl:message name="GetRelatedFederatedInContextRequest">
<wsdl:part element="tns:FederatedRelatedInfoInput" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetRelatedFederatedInContextResponse">
<wsdl:part element="tns:FederatedRelatedInfoOutput"
name="outargs"/>
</wsdl:message>
<xsd:element name="FederatedRelatedInfoInput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="loginInfo" type="tns:LoginInfo"/>
<xsd:element name="classNameId" type="tns:ClassNameId"/>
<xsd:element name="instanceId" type="xsd:string"/>
<xsd:element name="attributeNames"
type="tns:ArrayOf_String"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="FederatedRelatedInfoOutput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="instanceInfo"
type="tns:InstanceInfoList"/>
<xsd:element name="status" type="tns:StatusList"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

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

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

attributeNames
The list of attribute names to retrieve.
Chapter 6 Web services API operations and data structures

221

BMC Atrium CMDB 2.1.00

Return values

instanceIdList
The list of instance GUIDs.

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

Audit operations
The audit functions manipulate the audit option for the classes and attributes. The
web services API for audit includes:

GetCopyAuditData (page 222)

GetCopyAuditData
Description

Privileges
Synopsis

222

Retrieves a copy of the specified CI instance if the attribute data for the instance is
modified. The audit option must be set for the attributes characteristic to get the
audit data.
CMDB Administrator
<wsdl:operation name="GetCopyAuditData">
<wsdlsoap:operation soapAction="GetCopyAuditData"
style="document"/>
<wsdl:input name="GetCopyAuditDataRequest">
<wsdlsoap:body parts="inargs" use="literal"/>
</wsdl:input>
<wsdl:output name="GetCopyAuditDataResponse">
<wsdlsoap:body parts="outargs" use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:message name="GetCopyAuditDataRequest">
<wsdl:part element="tns:GetCopyAuditDataInput" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetCopyAuditDataResponse">
<wsdl:part element="tns:GetCopyAuditDataOutput" name="outargs"/>
</wsdl:message>
<xsd:element name="GetCopyAuditDataInput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="loginInfo" type="tns:LoginInfo"/>
<xsd:element name="classNameId" type="tns:ClassNameId"/>
<xsd:element name="instanceId" type="xsd:string"/>
<xsd:element name="datasetId" type="xsd:string"/>
<xsd:element name="query" type="xsd:string"/>
<xsd:element name="attributes"
type="tns:ArrayOf_String"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

Developers Reference Guide

Operations

<xsd:element name="GetCopyAuditDataOutput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="auditValueListList"
type="tns:AuditValueListList"/>
<xsd:element name="status" type="tns:StatusList"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

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

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

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

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

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

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

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

Chapter 6 Web services API operations and data structures

223

BMC Atrium CMDB 2.1.00

User interface component operations

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

GetUIComponents (page 224)

GetUIComponents
Description
Privileges
Synopsis

Input
arguments

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

CMDB Administrator
<wsdl:operation name="GetUIComponents" parameterOrder="inargs">
<wsdl:input message="tns:GetUIComponentsRequest"
name="GetUIComponentsRequest"/>
<wsdl:output message="tns:GetUIComponentsResponse"
name="GetUIComponentsResponse"/>
</wsdl:operation>
<wsdl:message name="GetUIComponentsRequest">
<wsdl:part element="tns:GetUIComponentsInput" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetUIComponentsResponse">
<wsdl:part element="tns:GetUIComponentsOutput" name="outargs"/>
</wsdl:message>
<xsd:element name="GetUIComponentsInput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="loginInfo" type="tns:LoginInfo"/>
<xsd:element name="componentInfo"
type="tns:UIComponentInfo"/>
<xsd:element name="datasetId" type="xsd:string"/>
<xsd:element name="instanceId" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="GetUIComponentsOutput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="uiComponentResultList"
type="tns:UIComponentResultList"/>
<xsd:element name="status" type="tns:StatusList"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

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

Developers Reference Guide

Operations

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

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

uiComponentResultList
The CMDBUIComponents result set for the specified qualifications.

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

Utility operations
The utility operations enable you to use CMDB utilities such as get version
information of the BMC Atrium CMDB application. The web services API includes
the following utility operations:

GetVersions (page 225)

GetVersions
Description
Privileges
Synopsis

Retrieves the version information for any BMC Atrium CMDB component that is
installed.
CMDB Administrator
<wsdl:operation name="GetVersions" parameterOrder="inargs">
<wsdl:input message="tns:GetVersionsRequest"
name="GetVersionsRequest"/>
<wsdl:output message="tns:GetVersionsResponse"
name="GetVersionsResponse"/>
</wsdl:operation>
<wsdl:message name="GetVersionsRequest">
<wsdl:part element="tns:GetVersionsInput" name="inargs"/>
</wsdl:message>
<wsdl:message name="GetVersionsResponse">
<wsdl:part element="tns:GetVersionsOutput" name="outargs"/>
</wsdl:message>
<xsd:element name="GetVersionsInput">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="loginInfo" type="tns:LoginInfo"/>
<xsd:element name="appIdList"
type="tns:ArrayOf_String"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="GetVersionsOutput">
<xsd:complexType>

Chapter 6 Web services API operations and data structures

225

BMC Atrium CMDB 2.1.00

<xsd:sequence>
<xsd:element name="versionInfoList"
type="tns:VersionInfoList"/>
<xsd:element name="status" type="tns:StatusList"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

Input
arguments

loginInfo
The login information for the operation, such as the user ID, password, and the
language to be used for the session. The userId is a required element.

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

versionInfoList
A list of BMC Atrium CMDB version structures.

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

226

Developers Reference Guide

Data structures

Data structures
The web services data structures are used as parameters for web services
operations. The data structure categories include Instance, Graph query, Class,
and Reconciliation Engine structures.

Instance structures
Instance structures are data structures for the instance data. Instance structures
include:

LoginInfo (page 227)

ClassNameIdList (page 228)

ClassNameId (page 228)

ArrayOf_String (page 228)

SortOrderList (page 229)

SortOrder (page 229)

InstanceInfoList (page 229)

InstanceInfo (page 230)

StatusList (page 230)

Status (page 231)

LoginInfo
The LoginInfo data structure is used to hold the login information for a user.
<complexType name="LoginInfo">
<sequence>
<element name="userId" type="xsd:string"/>
<element name="password" type="xsd:string"/>
<element name="lang" type="xsd:string"/>
</sequence>
</complexType>

The LoginInfo structure consists of the following elements:

userId

The login ID for the user.

password

The password for the user.

lang

The language to use for the current session of the application.

Chapter 6 Web services API operations and data structures

227

BMC Atrium CMDB 2.1.00

ClassNameIdList
The ClassNameIdList data structure is used to hold a list of ClassNameID structures.
<xsd:complexType name="ClassNameIdList">
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
name="items" type="tns:ClassNameId"/>
</xsd:sequence>
</xsd:complexType>

The ClassNameIdList structure consists of the following element:

ClassNameId

The list of class name IDs.

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"/>
</sequence>
</complexType>

The ClassNameId structure consists of the following elements:

namespaceName

The namespace name for the class.

className

The name of the class.

ArrayOf_String
The ArrayOf_String data structure is used to hold a list of string values.
<complexType name="ArrayOf_String">
<sequence>
<element maxOccurs="unbounded" minOccurs="0" name="items"
type="xsd:string"/>
</sequence>
</complexType>

The ArrayOf_String structure consists of the following element:

items

228

Developers Reference Guide

The value of the attribute.

Data structures

SortOrderList
The SortOrderList data structure is used to hold a list of attributes on which to
sort.
<complexType name="SortOrderList">
<sequence>
<element maxOccurs="unbounded" minOccurs="0" name="items"
type="impl:SortOrder"/>
</sequence>
</complexType>

The SortOrderList structure consists of the following element:

items

A list of SortOder structure items.

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"/>
</xsd:sequence>
</xsd:complexType>

The SortOrder structure consists of the following elements:

attributeName

The name of the attribute to sort.

sortOder

The sort order for the list of attributes.

ASCENDINGThe

attributes will be sorted in ascending order

of the list.
DESCENDINGThe attributes will be sorted in descending
order of the list.

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"/>
</sequence>
</complexType>

The InstanceInfoList structure consists of the following element:

items

A list of InstanceInfo structure items.

Chapter 6 Web services API operations and data structures

229

BMC Atrium CMDB 2.1.00

InstanceInfo
The InstanceInfo data structure is used to hold instance values.
<xsd:complexType name="InstanceInfo">
<xsd:sequence>
<xsd:element name="instanceId" type="xsd:string"/>
<xsd:element name="instanceAttributes"
type="tns:AttributeValueList"/>
</xsd:sequence>
</xsd:complexType>

The InstanceInfo structure consists of the following elements:

instanceId

The ID of the instance.

instanceAttributes

The attributes of the instance.

StatusList
The StatusList data structure is used to hold a list of status information for an
operation.
<complexType name="StatusList">
<sequence>
<element maxOccurs="unbounded" minOccurs="0" name="items"
type="impl:Status"/>
</sequence>
</complexType>

The StatusList structure consists of the following element:

items

230

Developers Reference Guide

The status value of the operation.

Data structures

Status
The Status data structure is used to hold the status information for an operation.
<xsd:complexType name="Status">
<xsd:sequence>
<xsd:element name="statusType" type="tns:StatusType"/>
<xsd:element name="messageNum" type="xsd:long"/>
<xsd:element name="messageText" type="xsd:string"/>
<xsd:element name="appendedText" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

The Status structure consists of the following elements:

statusType

The type of status message for the operation.

OKOperation successful. Status might contain one or more

informational messages.
WARNINGOperation successful, but some problems
encountered. Status contains one or more warning messages
and might also contain information messages.
ERROROperation failed. Status contains one or more error

messages and might also contain warning or informational

messages.
FATALOperation failed.
BAD_STATUSInvalid status parameter. Operaion cancelled.
PROMPTStatus for the active link action.
ACCESSIBLEStatus message for client accessibility.

messageNum

An integer value indicating the message number.

messageText

The description for the status message.

appendedText

Additional information for the status message.

Chapter 6 Web services API operations and data structures

231

BMC Atrium CMDB 2.1.00

Graph query structures

Graph query structures are data structures used in graph queries. The graph query
data structures include:

GraphList (page 232)

Graph (page 232)

GraphAdjacencyList (page 233)

GraphAdjacency (page 233)

ObjectQueryInfoList (page 234)

ObjectQueryInfo (page 234)

RelationQueryInfoList (page 235)

RelationQueryInfo (page 235)

GraphList
The GraphList data structure is used to hold a list of graph information.
<complexType name="GraphList">
<sequence>
<element maxOccurs="unbounded" minOccurs="0" name="items"
type="impl:Graph"/>
</sequence>
</complexType>

The GraphList structure consists of the following element:

items

A list of Graph structure items.

Graph
The Graph data structure is used to hold the query graph information.
<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>

The Graph structure consists of the following elements:

232

classNameId

The name of the class for the object (node).

extensionId

The extension ID of the node.

adjacencyList

The list of adjacent objects (nodes).

Developers Reference Guide

Data structures

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"/>
</xsd:sequence>
</xsd:complexType>

The GraphAdjacencyList structure consists of the following element:\

items

A list of GraphAdjancency structure items.

GraphAdjacency
The GraphAdjacency data structure is used to hold an adjacent node.
<xsd:complexType name="GraphAdjancency">
<xsd:sequence>
<xsd:element name="extensionId" type="xsd:string"/>
<xsd:element name="objectClassName" type="tns:ClassNameId"/>
<xsd:element name="objectAttributeNames"
type="tns:ArrayOf_String"/>
<xsd:element name="objectAttributeType"
type="tns:GraphAdjancencyAttributeType"/>
<xsd:element name="objectQuery" type="xsd:string"/>
<xsd:element name="relationClassName"
type="tns:ClassNameId"/>
<xsd:element name="relationAttributeNames"
type="tns:ArrayOf_String"/>
<xsd:element name="relationAttributeType"
type="tns:GraphAdjancencyAttributeType"/>
<xsd:element name="relationQuery" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

Chapter 6 Web services API operations and data structures

233

BMC Atrium CMDB 2.1.00

The GraphAdjacency structure consists of the following elements:

extensionId

The extension ID of the object. This item can contain an

empty string.

objectClassName

The object class name.

objectAttributeNames

The object attribute to retrieve.

objectAttributeType

The type of object attributes to retrieve.

NONERetreive no attributes in the query.
NOHIDDENRetreive all non-hidden attributes.
ALLRetreive all the attributes.

objectQuery

The qualification for the object. This item can be NULL.

relationClassNames

The name of the class that makes up the relationship.

relationAttributeNames

The related attribute to retrieve from the relationship.

relationAttributeType

The related attribute type.

relationQuery

The qualification string that qualifies the relationship.

This item can be NULL.

ObjectQueryInfoList
The ObjectQueryInfoList data structure is used to hold a list of CI instances.
<complexType name="ObjectQueryInfoList">
<sequence>
<element maxOccurs="unbounded" minOccurs="0" name="items"
type="impl:ObjectQueryInfo"/>
</sequence>
</complexType>

The ObjectQueryInfoList structure consists of the following element:

items

A list of ObjectQueryInfo items.

ObjectQueryInfo
The ObjectQueryInfo data structure is used to hold a CI instance.
<xsd:complexType name="ObjectQueryInfo">
<xsd:complexContent>
<xsd:extension base="tns:InstanceInfo">
<xsd:sequence> <
xsd:element name="classNameId" type="tns:ClassNameId"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>

The ObjectQueryInfoList structure consists of the following element:

classNameId

234

Developers Reference Guide

The class name ID for the class.

Data structures

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"/>
</sequence>
</complexType>

The RelationQueryInfoList structure consists of the following element:

items

A list of RelationQueryInfo items.

RelationQueryInfo
The RelationQueryInfo data structure is used to hold relationship information.
<xsd:complexType name="RelationQueryInfo">
<xsd:complexContent>
<xsd:extension base="tns:ObjectQueryInfo">
<xsd:sequence>
<xsd:element name="instanceRole1type="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.

Chapter 6 Web services API operations and data structures

235

BMC Atrium CMDB 2.1.00

Class Structures
Class structures are data structures for class and relationship definitions. The class
data structures include:

ClassInfoIn (page 236)

ClassInfoOut (page 237)

ClassRelationship (page 237)

ClassProperties (page 239)

IndexList (page 240)

IndexInfo (page 240)

PropInfoList (page 241)

PropInfo (page 241)

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"/>
</sequence>
</complexType>

The ClassInfoIn structure consists of the following elements:

236

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.

Developers Reference Guide

Data structures

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:

superClassNameId

The name of the superclass.

classId

The ID of the class.

classType

The type of class.

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:

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.

Chapter 6 Web services API operations and data structures

237

BMC Atrium CMDB 2.1.00

cardinality

An integer identifying the cardinality of the relationship

between the related classes:
NONEUndefined cardinality for a relationship.
ONE_ONEOne-to-one. One instance of a class is

associated with a single instance of another class.

MANY_ONEMany-to-one. One or more instances of a

class are associated with one instance of another class.

ONE_MANYOne-to-many. One instance of a class is

associated with one or more instances of another class.

MANY_MANYMany-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:
TRUEA cascade delete is allowed. Deleting an instance

in one class also deletes the instance in the related class.

FALSEA 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:
TRUEThe role 2 class is a weak reference. Role 2 is a

weak entity and it uses role 1s primary key as part of its

own key. If the value is TRUE, cardinality must be one-toone or many-to-many.
FALSEThe role 2 class is not a weak reference.

weakPropagatedAttrsList

238

Developers Reference Guide

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.

Data structures

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"/>
</xsd:sequence>
</xsd:complexType>

The AttributeInfoList structure consists of the following element:

isAbstract

A value indicating whether the class is an abstract class.

NOA regular class
REGULARA regular abstract class
WITH_DATA_REPLICATIONA data replication abstract class

hiddenPerms

A value indicating the groups or roles that cannot view the

class form in the ObjectList form of the application. The
class will be only available through the workflow once this
parameter is set for a group or role.

visiblePerms

A value indicating the groups or roles that can view the

class form bothin the ObjectList form of the application
and the workflow.

categorizationSubclass

A Boolean value indicating whether the class is a categorization class.

TRUEThis is a categorization class. In categorization

classes the data is stored in the parent class.

FALSEThis is not a categorization class.

description

The description text for the class.

isFinal

A Boolean value indicating whether the class is a Final

class.
TRUEThis is a Final class. You cannot create a subclass for
a Final type class.
FALSEThe class is not a final class.

isSingleton

A Boolean value indicating whether the class is a singleton

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.

Chapter 6 Web services API operations and data structures

239

BMC Atrium CMDB 2.1.00

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"/>
</xsd:sequence>
</xsd:complexType>

The IndexList structure consists of the following elements:

Items

An integer value indicating the number of IndexStruct

items in the list.

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"
type="tns:ArrayOf_String"/>
</xsd:sequence>
</xsd:complexType>

The IndexInfo structure consists of the following elements:

indexName

The name of the index.

unique

A Boolean value indicating whether the index key must be

unique:
TRUEThe index key is unique.
FALSEThe index key is not unique.

isPrimaryKey

A Boolean value indicating whether the index is a primary

key index:
TRUEThe index key is a primary key index.
FALSEThe index key is not a primary key index.

attributeNames

240

Developers Reference Guide

The names of attributes to index.

Data structures

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"/>
</xsd:sequence>
</xsd:complexType>

The PropInfoList structure consists of the following elements:

Items

A list of PropInfo structure items.

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"/>
</xsd:sequence>
</xsd:complexType>

The PropInfo structure consists of the following elements:

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

Chapter 6 Web services API operations and data structures

241

BMC Atrium CMDB 2.1.00

Attribute structures
Attribute structures are data structures for attribute definitions. The attribute data
structures include:

AttributeInfoList (page 242)

AttributeValueList (page 243)

AttributeValue (page 243)

AttributeInfoIn (page 243)

AttributeLimit (page 245)

AttachmentLimit (page 246)

CurrencyLimit (page 247)

CharLimit (page 246)

DateLimit (page 248)

EnumLimit (page 248)

IntLimit (page 248)

RealLimit (page 249)

AttributeLimitList (page 249)

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"/>
</sequence>
</complexType>

The AttributeInfoList structure consists of the following element:

items

242

Developers Reference Guide

A list of AttributeInfoOut items.

Data structures

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"/>
</sequence>
</complexType>

The AttributeValueList structure consists of the following element:

items

A list of AttributeValue structure items.

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"/>
</xsd:sequence>
</xsd:complexType>

The AttributeValueList structure consists of the following elements:

name

The name of the attribute.

value

The value for the attribute.

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"/>
</sequence>
</complexType>

The AttributeInfoIn structure consists of the following elements:

value

The value of the attribute.

Chapter 6 Web services API operations and data structures

243

BMC Atrium CMDB 2.1.00

entryMode

The entry mode for the attribute.

createMode

DISPLAY_ONLYData for the attribute is display only. This

attribute cannot be modified.
NONENo specific entry mode defined for the attribute.
OPTIONALENTRYData entry for the attribute is optional. This
attribute can be left blank.
REQUIREDENTRYData entry for the attribute is required. This
attribute cannot be left blank.
SYSTEMA system-generated value will be used for this attribute.
The create mode for the attribute.
OPENAllow any user to create an attribute.
PROTECTEDAllow 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 attribute.

isHidden

A Boolean value indicating whether the attribute is hidden.

TRUEThe attribute is hidden in the class form.
FALSEThe attribute is not hidden in the class form.

244

viewPerms

A value indicating the view permissions for the attribute.

customCharacList

A structure indicating the custom properties for the attribute.

Developers Reference Guide

Data structures

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.

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.

Chapter 6 Web services API operations and data structures

245

BMC Atrium CMDB 2.1.00

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"/>
</xsd:sequence>
</xsd:complexType>

The AttachmentLimit structure consists of the following elements:

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.

The AttachPoolLimit structure consists of the following elements:

attachPoolName

A unique name for the attachment pool.

maxSize

An integer value indicating the maximum size limit for the

attachment.

CharLimit
The CharLimit structure is used to hold data limit definitions for the character data
type.
<xsd:complexType name="CharLimit">
<xsd:sequence>
<xsd:element name="charMenu" type="xsd:string"/>
<xsd:element name="format" type="xsd:string"/>
<xsd:element name="FTSOption" type="xsd:int"/>
<xsd:element name="maxCharLength" type="xsd:int"/>
<xsd:element name="menuStyle" type="xsd:int"/>
<xsd:element name="pattern" type="xsd:string"/>
<xsd:element name="QBEOption" type="xsd:int"/>
</xsd:sequence>
</xsd:complexType>

The AttachPoolLimit structure consists of the following elements:

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).
0Not full text search indexed.
1Full text search indexed.
An integer value indicating the maximum size limit for the char
attribute.

maxCharLength

246

Developers Reference Guide

Data structures

menuStyle

Specifies a style for the menu.

1Overwrite the existing value.
2Append 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.

1Anywhere in the string.
2In the leading characters of the string.
3The same as the string

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"/>
</xsd:sequence>
</xsd:complexType>

The CurrencyLimit structure consists of the following elements:

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.

Chapter 6 Web services API operations and data structures

247

BMC Atrium CMDB 2.1.00

DateLimit
The DateLimit structure is used to hold data limit definitions for the date data type.
<xsd:complexType name="DateLimit">
<xsd:sequence>
<xsd:element name="minDate" type="xsd:int"/>
<xsd:element name="maxDate" type="xsd:int"/>
</xsd:sequence>
</xsd:complexType>

The DateLimit structure consists of the following elements:

minDate

The minimum value for the date data type.

maxDate

The maximum value for the date data type.

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>

The EnumLimit 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.

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"/>
</xsd:sequence>
</xsd:complexType>

The IntLimit structure consists of the following elements:

248

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.

Developers Reference Guide

Data structures

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"/>
</xsd:sequence>
</xsd:complexType>

The RealLimit structure consists of the following elements:

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:

Items

A list of AttributeLimit items.

Chapter 6 Web services API operations and data structures

249

BMC Atrium CMDB 2.1.00

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

VersionInfo (page 250)

VersionInfoList
The VersionInfoList structure is used to hold a list of version information
elements for the BMC Atrium CMDB components.
<xsd:complexType name="VersionInfoList">
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
name="items" type="tns:VersionInfo"/>
</xsd:sequence>
</xsd:complexType>

The VersionInfoList structure consists of the following element:

Items

A list of VersionInfo structure items.

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"/>
</xsd:sequence>
</xsd:complexType>

The VersionInfo structure consists of the following elements:

250

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.

Developers Reference Guide

Data structures

patchNum

The patch number.

isExist

A Boolean value indicating whether the specified version of

a component exists.
TRUEThe specified version exists.
FALSEThe 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 251)

UIComponentResult (page 252)

UIComponentResultList (page 252)

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"/>
</xsd:sequence>
</xsd:complexType>

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_ICONThe icon type component to

retrieve.
COMPONENT_TYPE_LINEThe user interface graphical line

information to retrieve (This option is currently not being

used.)
COMPONENT_TYPE_LOCALIZED_LABELThe localized label

type component to retrieve.

COMPONENT_TYPE_NONENo component information to

retrieve.
COMPONENT_TYPE_TOOLTIPThe tooltip type component to

retrieve.
encodedQual

The encoded qualifier for the UI component query.

Chapter 6 Web services API operations and data structures

251

BMC Atrium CMDB 2.1.00

locale

The name of the locale specific to the component. If no locale

is specified in this subclasses, the default locale will be used.

tag1

Information tag used to filter a specific component type.

tag2

Information tag used to filter a specific component type.

tag3

Information tag used to filter a specific component type.

tag4

Information tag used to filter a specific component type.

tag5

Information tag used to filter a specific component type.

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"/>
</xsd:sequence>
</xsd:complexType>

The UIComponentResultList structure consists of the following element:

Items

A list of CMDBUIComponentResult structure items.

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"/>
</xsd:sequence>
</xsd:complexType>

The UIComponentResult structure consists of the following elements:

252

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.

Developers Reference Guide

Data structures

Reconciliation Engine structures

Reconciliation Engine structures are data structures for reconciliation jobs. The
Reconciliation Engine structures include:

JobRunInfo (page 253)

JobRunInfoList (page 253)

ClassQualifierList (page 254)

ClassQualifier (page 254)

DatasetPairList (page 254)

DatasetPair (page 255)

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"/>
</sequence>
</complexType>

The JobRunInfo structure consists of the following elements:

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:

items

A list of information about the jobs.

Chapter 6 Web services API operations and data structures

253

BMC Atrium CMDB 2.1.00

ClassQualifierList
The ClassQualifierList data structure is used to hold a list of ClassQualifier
structures.
<xsd:complexType name="ClassQualifierList">
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
name="items" type="tns:ClassQualifier"/>
</xsd:sequence>
</xsd:complexType>

The ClassQualifierList structure consists of the following element:

Items

A list of ClassQualifier structure items.

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"/>
</xsd:sequence>
</xsd:complexType>

The ClassQualifier structure consists of the following elements:

qualifierString

The qualification for the class. If the qualification contains a

Null value, all the instances in the class will be reconciled.

classId

The ID of the class.

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"/>
</xsd:sequence>
</xsd:complexType>

The DatasetPairList structure consists of the following element:

Items

254

Developers Reference Guide

A list of DatasetPair items.

Data structures

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"/>
</xsd:sequence>
</xsd:complexType>

The DatasetPair structure consists of the following elements:

dataset

The dataset for the reconciliation job. If the workingDataset

field in the structure contains a Null, 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.

Chapter 6 Web services API operations and data structures

255

BMC Atrium CMDB 2.1.00

Federation structures
Federation structures are data structures used in federation operations. The
federation structures include:

FederatedActivateInfo (page 256)

FederatedARInfo (page 257)

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"/>
</xsd:sequence>
</xsd:complexType>

The FederatedActivateInfo structure consists of the following elements:

accessType

The type of access required.

ACCESS_TYPE_ARAccess an AR System form for the
federated interface.
ACCESS_TYPE_URLAccess a URL for the federated interface.
ACCESS_TYPE_WEBSERVICEUse a web service for the federated
interface.
ACCESS_TYPE_PROCESSStart a process for the federated
interface.
ACCESS_TYPE_MANUALAccess a manual launch link
information for the federated interface.
ACCESS_TYPE_DATA_STOREAccess a data store for the
federated interface.

actionType

The action to perform.

ACTIVATION_LAUNCHExpand and launch the federated
interface.
ACTIVATION_DATA_RETURNReturn the expanded federated

interface data.

256

accessString

Based on the accessType subclasses, contains the URL link,

process command, or other information.

arInfo

Contains information related to the AR System form.

Developers Reference Guide

Data structures

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"/>
</xsd:sequence>
</xsd:complexType>

The FederatedARInfo structure consists of the following elements:

accessType

The access type for the AR System.

ACCESS_TYPE_AR_URLRetrieve AR System URL.
ACCESS_TYPE_AR_PROCESSRetrieve 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.

Chapter 6 Web services API operations and data structures

257

BMC Atrium CMDB 2.1.00

Audit structures
Audit structures are data structures used in audit operations. The audit structures
include:

AuditValueListList (page 258)

AuditValueList (page 258)

AuditInfo (page 259)

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"/>
</xsd:sequence>
</xsd:complexType>

The AuditValueListList structure consists of the following element:

Items

A list of AuditValueListList structures.

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"/>
</xsd:sequence>
</xsd:complexType>

The AuditValueList structure consists of the following elements:

attributeList

The list of attribute names that changed in the audit

operation.

auditDate

The date and time when the audit operation was

performed.

changedBy

The user who performed the audit operation.

operation

The type of audit operation performed.

AUDIT_OP_SETThe modify operation performed.
AUDIT_OP_CREATEThe create operation performed.
AUDIT_OP_DELETEThe delete operation performed.
AUDIT_OP_MERGEThe merge operation performed.

258

Developers Reference Guide

Data structures

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"/>
</xsd:sequence>
</xsd:complexType>

The AuditInfo structure consists of the following elements:

auditType

The type of audit option to set.

CopyCreate a copy of an instance when an attribute is
modified.
LogStore the information for the modified attributes in a

log.
NoneNo auditing option set.

qualifierString

The qualification to retrieve the audit information for the

class.

Chapter 6 Web services API operations and data structures

259

BMC Atrium CMDB 2.1.00

260

Developers Reference Guide

Appendix

CI Relationship Viewer events

This section 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.
The following topics are provided:

Events from AR System to CI Relationship Viewer (page 262)

Events from CI Relationship Viewer to AR (page 264)

Appendix A

CI Relationship Viewer events

261

BMC Atrium CMDB 2.1.00

Events from AR System to CI Relationship

Viewer
You send an event to the CI Relationship Viewer with the PERFORM-ACTION-SENDEVENT 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.1.00 Workflow Objects.

CIRV_SET_FILTER
Changes 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_FILTER
Sets the characteristics of the currently selected filter without saving it. This event
enables you to customize the display when an existing filter does not meet your
needs.
Event Type: CIRV_SET_CUSTOM_FILTER
Event Data: <Namespace>|<Classes>|<Relationships>|<Statuses>|
<Direction>|<NumLevels>

The following code shows an example Event Data for the CIRV_SET_CUSTOM_FILTER
event:
BMC.CORE|BMC_ComputerSystem BMC_DiskDrive|BMC_Dependency
BMC_Component|Active|0|5

262

Developers Reference Guide

Events from AR System to CI Relationship Viewer

CIRV_SHOW
Displays 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_SHOW
Event 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.AS0050560C63F28d6HQQYFQG
AAKQAA

CIRV_SET_AS_ROOT
Sets the currently selected CI node as the root.
Event Type: CIRV_SET_AS_ROOT
Event Data: none

CIRV_SELECT_CI
Selects the given CI in the relationship diagram.
Event Type: CIRV_SELECT_CI
Event Data: <instance id>

An example of Event Data for the CIRV_SELECT_CI event is

AS0050560C63F28d6HQQYFQGAAKQAA.

CIRV_REFRESH
Refreshes 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_REFRESH
Event Data: none

CIRV_LAYOUT
Changes 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_LAYOUT
Event Data: <layout style>

An example of Event Data for the CIRV_LAYOUT event is TreeLayout.

Appendix A

CI Relationship Viewer events

263

BMC Atrium CMDB 2.1.00

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_CI
When 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_CI
Event 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_AR
This is a special type of event used by context menu items. When you specify
CIRV_NOTIFY_AR as the value for the context menu items 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>

264

Developers Reference Guide

Appendix

Using graph queries to find

related CIs
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 section provides you a context for these graphs, then explains how the graph
query works, using two examples.
The following topics are provided:

Representing graphs (page 266)

The CMDBGraphQuery API function (page 267)

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

Appendix B

Using graph queries to find related CIs

265

BMC Atrium CMDB 2.1.00

Representing graphs
You can represent a graph, G = ( V, E ) , in two standard ways: 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 E is much less than V 2 . An adjacency-matrix representation
might be preferred, however, when the graph is dense: E is close to V 2 . The
representation used by the CMDBGraphQuery input query graph is an adjacency list.
The adjacency-list representation of a graph G = ( V, E ) consists of an array Adj of V
lists, one for each vertex in V . For each u V , the adjacency list Adj [ u ] contains
pointers to all the vertices v such that there is an edge ( u, v ) E . That is, Adj [ u ]
consists of all the vertices adjacent to u in G . 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 undirected1 graph in Figure B-1 (a).
Figure B-1: Undirected graph and its equivalent adjacency list

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

In an undirected graph G = ( V, E ) , the edge set E consists of unordered pairs of vertices, rather
than ordered pairs. That is, an edge is a set { u, v } , where u, v V and u v . In an undirected
graph, self-loops are forbidden, and so every edge consists of exactly two distinct vertices.
266

Developers Reference Guide

The CMDBGraphQuery API function

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 115.
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 267. In the graph, CI
instances are circular nodes and relationship instances are the lines connecting
them.
Figure B-3: Graph of data to use with example queries

Appendix B

Using graph queries to find related CIs

267

BMC Atrium CMDB 2.1.00

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. Theres 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 268 shows the data structures of the queryGraph argument for
Figure B-4 (a). Figure B-6 on page 269 shows the data structures of the queryGraph
argument for Figure B-4 (b).
Figure B-5: queryGraph data structures for Figure B-4 (a)

268

Developers Reference Guide

The CMDBGraphQuery API function

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 270. The bolded nodes are those returned in the objects list.

Appendix B

Using graph queries to find related CIs

269

BMC Atrium CMDB 2.1.00

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.

270

Developers Reference Guide

The CMDBGraphQuery API function

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. Theres
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 272 shows the data structures of the queryGraph argument for
Figure B-8 (a). Figure B-10 on page 273 shows the data structures of the queryGraph
argument for Figure B-8 (b).

Appendix B

Using graph queries to find related CIs

271

BMC Atrium CMDB 2.1.00

Figure B-9: queryGraph data structures for Figure B-8 (a)

272

Developers Reference Guide

The CMDBGraphQuery API function

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 274. The bolded nodes are those returned in the objects list.

Appendix B

Using graph queries to find related CIs

273

BMC Atrium CMDB 2.1.00

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.

274

Developers Reference Guide

Glossary
abstract class

A 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.
account

An entity or party whose data is represented

in BMC Atrium CMDB, and to whom specific
levels of permission can be granted.
Specifying instance permission by account
enables BMC Atrium CMDB to support
multitenancy.
activity

An 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.
attribute

A 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 permission

Permission to view or change the value in the

attribute for any instance, assuming valid
instance permissions.
attribute substitution

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

audit

A 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 class

A class that has no superclass.

BMC Atrium Integration Engine

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.
Business Service Management (BSM)

The concept of prioritizing IT efforts to

support the overall goals of the business.
cardinality

The number of members a relationship class can

have on each side. Cardinality can be one to
one, one to many, many to one, or many to
many.
cascading delete

To automatically delete, or mark as deleted,

the destination member of a relationship
when the source member is deleted or
marked.
Categories, Types, and Items (CTI)

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 BMC Atrium CMDB.

Glossary

275

BMC Atrium CMDB 2.1.00

categorization class

A class that does not have its own AR System

form, but stores its instance data in the form of
its superclass, preventing the need for a
database join.
CDM

See Common Data Model (CDM).

child

Permission to view instances of a class in the

BMC Atrium CMDB interface or access them
with AR System workflow.
CMDB

See Configuration Management Database

(CMDB).
CMDB Console

See destination.
CI

See configuration item (CI).

The main user interface of BMC Atrium

CMDB, accessible from both web and BMC
Remedy User clients.
CMDB Console User

CI class

A class that defines a type of configuration item

(CI), such as a computer system or software
application.
CI Relationship Viewer

A component of BMC Atrium CMDB that

graphically displays the relationships
between CIs. It can also be embedded in other
AR System-based applications.
CI Relationship Viewer event

A message sent to the CI Relationship Viewer

from AR System workflow to change its
settings. The CI Relationship Viewer can also
send AR System events.
CIM

See Common Information Model (CIM).

class

Metadata in BMC Atrium CMDB that defines

a type of object, usually a configuration item
(CI) or relationship. Either of these types of
class can store data as a regular class,
categorization class, abstract class, or abstract
class with data replication. You can apply the
final class and singleton class options to it as
well.
Class Manager

A component of 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.

276

class permissions

Developers Reference Guide

An application role. Members can perform

searches from the CMDB Console and view
federation definitions.
CMDB Console Admin

An application role. Members can perform

searches from the CMDB Console, view, create,
and modify federation definitions, and perform
CMDB Console administrative tasks.
CMDB Data Change

An application role. Members can view, create,

and modify instances if they have row-level
security.
CMDB Data Change All

An application role. Members can view, create,

and modify instances independent of row-level
security.
CMDB Data View

An application role. Members can view

instances if they have row-level security.
CMDB Definitions Admin

An application role. Members can view, create,

modify, and delete classes.
CMDB Definitions Viewer

An application role. Members can view class

definitions.
CMDB Extended Data

Related data or CI attributes linked to or from

BMC Atrium CMDB.
CMDB RE Definitions Admin

An application role. Members can view, create,

modify, and delete reconciliation definitions
and can start and cancel jobs.

Glossary

CMDB RE Manual Identification

An application role. Members can identify

instances manually.
CMDB RE User

An application role. Members can view

reconciliation definitions and can start and
cancel jobs.
cmdbdriver

A 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 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
Microsofts 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 activity

A Reconciliation Engine activity that compares

identified instances between two datasets,
either producing a report that shows the
differences or executing workflow.
configuration data

Data 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 BMC Atrium CMDB.
See also relationship.
Configuration Management Database (CMDB)

A database that stores information about your

IT configuration, including both CIs and
relationships.

consumer

An application that works with data in BMC

Atrium CMDB. It might view the data or
modify it. See also provider.
Copy Dataset activity

A Reconciliation Engine activity that copies

instances from one dataset to another.
CTI

See Categories, Types, and Items (CTI).

data replication

An option for abstract classes. With this option,

the instances of all subclasses are replicated to
a single form to allow you to search the
abstract class as though it had data. Only the
attributes inherited from the abstract class are
replicated.
dataset

A logical group of data in BMC Atrium

CMDB. A dataset can represent data from a
particular source, a snapshot from a particular
date, or other purpose. The dataset used by
BMC Software products for reconciled
production data is named BMC Asset. See also
overlay dataset.
Dataset Merge Precedence

A pairing of a dataset with a Precedence group.

Each Merge activity references a collection of
these, called a Dataset Merge Precedence set.
defined dataset

One of a pair of dataset IDs that is specified

when executing a job with dynamic dataset
substitution. The job is executed with the
working dataset in place of the defined dataset.
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 activity

A Reconciliation Engine activity that deletes

instances from one or more datasets without
removing the dataset itself. See also cascading
delete, hard delete, and soft delete.

Glossary

277

BMC Atrium CMDB 2.1.00

destination

The CI class defined as Class 2 in a relationship

class, or an instance of that CI class as a
member of such a relationship. Also known as
the child member or weak member.
discovery

The act of scanning your environment for

configuration data.
discovery application

An application that scans your environment

for configuration data and can act as a provider
to 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.
DMTF

See Distributed Management Task Force

(DMTF).
DSL

See Definitive Software Library (DSL).

Enterprise Integration Engine

See BMC Atrium Integration Engine.

The cmdbExtLoader program, which is used for

installing data model extensions and
importing other BMC Atrium CMDB data and
metadata.
federated data

Data linked from CIs in 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 interface

An instance of the BMC_FederatedInterface

class that specifies how to access a particular
type of federated data. See also federated link.
federated link

The connection between a class or CI and a

federated interface.
federated product

A product that holds federated data. It can be

linked to more than one federated interface.
federation

The act of linking CIs in BMC Atrium CMDB

to external data.
Federation Manager

event

A particular type of change to the instances of

specified classes. You can publish an event so
that any instance of it is written to the
CMDB:Events form. You can receive
notification each time an instance of the event
occurs by polling the form. See also CI
Relationship Viewer event.
Exclusion rule

A rule that specifies an attribute to be excluded

from participation in a Comparison activity.
Execute Job activity

A Reconciliation Engine activity that executes a

job.
extension

A logical set of classes and attributes, usually in

its own namespace, that is not part of the
Common Data Model (CDM).

278

extension loader

Developers Reference Guide

A component of BMC Atrium CMDB that you

can use to manage federated data. From the
Federation Manager, you can view, create,
and modify federated products, federated
interfaces, and federated links.
filter

A set of criteria for restricting the information

displayed by the CI Relationship Viewer. This is
different from an AR System filter.
final class

A class that cannot have subclasses.

foreign key substitution

A method of federation that assigns a key

from the federated product to each linked CI.
Foreign key substitution is useful when no
attributes that also exist in BMC Atrium
CMDB are stored in the federated product.

Glossary

group

A set of a particular type of reconciliation

definition that is referenced by an activity. See
also Identification group, Precedence group,
Qualification group, Workflow Execution group.
GUID

A globally unique identifier, automatically

generated by the AR System server. GUIDs
are used for instance IDs, reconciliation IDs,
and other cases where a unique value is
needed without human interaction.
hard delete

The act of removing an instance from BMC

Atrium CMDB.
Identification activity

A 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 group

A set of Identification rules that collectively

identify instances from a particular dataset
against other datasets. Each dataset that
participates in an Identification activity is
paired with one Identification group.
Identification rule

A rule used when identifying instances

between datasets. When two instances match
the qualification for the rule, they are assigned
the same reconciliation ID.
identity

See reconciliation ID.

incident

Defined by ITIL as any event that is not part of

the standard operation of a service and which
causes, or might cause, an interruption to, or a
reduction in, the quality of that service.
incremental merge

A Merge activity that only processes instances

that were created or modified since the
activity was last run, saving otherwise useless
processing time. Setting Force Attribute
Merge to No makes a Merge activity
incremental.

instance

An actual incarnation of a particular class,

represented as a record in BMC Atrium
CMDB. Both CIs and relationships are
instances of their respective classes.
instance ID

A GUID that BMC Atrium CMDB applies to

each instance to uniquely identify it.
instance permissions

The right to view or modify a specific

instance. These permissions are called rowlevel security and write security, respectively.
instantiate

To create an instance of a class.

ITIL

The Information Technology Infrastructure

Library (ITIL) is an internationally accepted
set of best practices for management of IT
services developed by the British government
job

A group of one or more reconciliation activities

executed in sequence. You cannot run an
activity by itself; only as part of a job. You can
start a job manually, with a schedule, with an
Execute Job activity, with workflow, or with an
API program.
Merge activity

A Reconciliation Engine activity that merges

two or more datasets into a single complete
and correct dataset based on precedence values
that favor the strengths of each dataset.
metadata

Definitions that describe the data stored in

BMC Atrium CMDB. Metadata includes
classes in the data model and special classes to
define things such as datasets and federation
objects.
multitenancy

The separation of data and access so that a

single BMC Atrium CMDB can contain the
data of multiple parties, but each party can
access only their own data. See also account
and role.

Glossary

279

BMC Atrium CMDB 2.1.00

namespace

A logical set of classes and attributes in the data

model, usually related to a specific consumer
or provider. The Common Data Model (CDM)
uses the BMC.CORE namespace.
normalize

To ensure that data of the same type follows

the same text formatting conventions. This
helps reconciliation by making it more likely
for instances to match in an Identification
activity.
orphan

An instance that has been physically deleted

from source datasets but still exists in the
target dataset into which they merge.
overlay dataset

A dataset that provides a layer in which to

make changes that are pending approval. API
queries to the dataset seamlessly return its
modified instances along with unmodified
instances from the underlying regular dataset.
parent

See source.
Precedence group

The definition of an overall precedence value for

a dataset. It can optionally contain precedence
values for specific classes and attributes
within the dataset.
precedence value

A 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 dataset

The dataset that serves as the single source of

reference for your organization and from
which you make business decisions. It acts as
the target dataset in most Merge activities.
provider

An application, often a discovery application,

that loads bulk data into BMC Atrium CMDB.
See also consumer.

280

Developers Reference Guide

provisioning

The process of providing access to resources,

such as printers, telephones, and such, and to
information, such as permissions, databases,
and so on.
publish

To make an event available so that instances of

it can be written to the CMDB:Events form.
Purge Dataset activity

A Reconciliation Engine activity that removes

instances that have been marked as deleted
from one or more datasets.
Qualification

A Boolean statement that is evaluated to

determine whether an instance should be
included in an activity.
Qualification group

A set of Qualifications that can be used in

various types of activity. An instance that
meets one or more Qualifications in the group
is included in the activity.
reconciliation

The process of managing data in multiple

datasets using the Reconciliation Engine. The
main activities of reconciliation are
identifying, comparing, and merging
datasets, though the Reconciliation Engine
performs other activities as well.
reconciliation definition

An entity defined in the Reconciliation Manager

such as a job, activity, or group.
Reconciliation Engine

The component of BMC Atrium CMDB that

reconciles data from different datasets.
reconciliation ID

A GUID that the Reconciliation Engine assigns

to instances in different datasets that represent
the same real-life object.
Reconciliation Manager

The component of BMC Atrium CMDB that

you can use to manage reconciliation
definitions.

Glossary

regular class

A class that stores its instance data in its own

AR System form. See also abstract class,
categorization class.
related information

Information about a CI that does not qualify as

attributes of the CI, and should therefore not
be stored in a Configuration Management
Database (CMDB).
relationship

A connection between two CIs such as a

dependency or membership. It is an instance
of a relationship class. See also configuration item
(CI).
relationship class

A class that defines a type of relationship

between CIs, such as a dependency or
membership.
relationship filter

See filter.
Rename Dataset activity

A reconciliation activity that renames a dataset

without changing its ID, preserving references
to the dataset from any reconciliation
definitions.
role

A designation that grants permissions to more

than one AR System group.
row-level security

The permission required to view a specific

instance. See also write security.
rule

One or more criteria that, when met, cause an

action. The types of rules used in BMC Atrium
CMDB are Exclusion rule, Identification rule,
and Workflow Execution rule.
ruleset

A group of rules.
service level agreement

A contract between a service provider and a

purchaser that defines the level of service.

snapshot

A set of data that represents a configuration at

a certain point in time, usually stored in its
own dataset. There can be multiple snapshots
of a given configuration.
soft delete

The act of marking an instance as deleted from

BMC Atrium CMDB by setting the
MarkAsDeleted attribute to Yes.
source

The CI class defined as Class 1 in a relationship

class, or an instance of that CI class as a
member of such a relationship. Also known as
the parent member or strong member.
subclass

A 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.
superclass

A class from which other classes, called

subclasses, are derived.
synchronization

The 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.
text normalization

See normalize.
weak reference

See weak relationship.

weak relationship

An optional characteristic for relationship

classes, signifying that the members of a
relationship form a composite object that can
be reconciled as one. The destination member
is considered the weak member of a weak
relationship, existing as part of the source
member.

singleton class

An optional class characteristic that restricts

the class to holding only one instance.

Glossary

281

BMC Atrium CMDB 2.1.00

Windows Management Instrumentation (WMI)

Microsoft's application of the Web-Based

Enterprise Management initiative for an
industry standard for accessing management
information.
WMI

See Windows Management Instrumentation

(WMI).
workflow

AR System objects such as active links,

escalations, and filters that perform actions
against data.
Workflow Execution group

A set of Workflow Execution rules. Each

Comparison activity can optionally reference
one Workflow Execution group.
Workflow Execution rule

A 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 dataset

One of a pair of dataset IDs that is specified

when executing a job with dynamic dataset
substitution. The job is executed with the
working dataset in place of the defined dataset.
write security

The permission required along with row-level

security to modify or delete a specific instance.

282

Developers Reference Guide

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Index
A
ActivateFederatedInContext operation 219
activating federated instances 153, 186, 256
adjacency items, storing for graphs 233
adjacency lists, representing graphs as 266
adjacency matrixes, representing graphs as 266
adjacent nodes, storing 179, 180
API compatibility 22
AR System
CI Relationship Viewer and 63
creating forms 121
storing related federation data 186, 257
transferring data
from CI Relationship Viewer 264
to CI Relationship Viewer 262
architecture, CMDB API 16
ArrayOf_String structure 228
attachLimits structure 165
attachment limits, defining 165
AttachmentLimit structure 246
AttributeInfoIn structure 243
AttributeInfoList structure 242
AttributeLimit structure 245
AttributeLimitList structure 249
attributes
C API data structures 161
creating 34, 83, 86, 211
data structures 161
deleting 88, 101, 209, 213
expanding CI parameters 127
exporting definitions with cmdbdriver 54
installing extensions with cmdbExtLoader 53
managing 82
retrieving 89, 92, 210
setting 95, 97, 212
storing
attachment limits 246
character limits 246
currency limits 247
data limits 245, 249
date limits 248

attributes (continued)
storing (continued)
definitions 161
enum limits 248
index information 160, 240
information 173
information to retrieve 242
information to set 243
integer limits 248
lists of values 243
real data limits 249
retrieval information 161
sort information 168, 229
sort information by type 229
sources for propagation 167
targets for propagation 167
values 166, 243
validating CI 126
web services API data structures 242
AttributeValue structure 243
AttributeValueList structure 243
audience for this guide 9
AuditInfo structure 259
audits
data structures 188, 258
functions 155
operations 222
retrieving CI instance logs 157
retrieving modified CI instances 155, 222
storing
class options 189, 259
value lists 188, 189, 258
AuditValueList structure 258
AuditValueListList structure 258

Index

283

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

B
BLOBs, retrieving instance 113
BMC Atrium CMDB
accessing classes 77
cmdbdriver program 42
documentation 10, 11
exporting data 128
importing data 128
importing data with EIE 76
installing extensions 54
migrating data between servers 45
programming 32
programs
header files 28
structure 32
storing version information 171, 250
tools 4178
utilities 4178, 134, 225
BMC Software, contacting 2
bulk entries
beginning transactions 118
committing transactions 119
ending transactions 119
invoking API calls 118
rolling back transactions 119
transaction functions 118

C
C API data structures
about 158
attribute
about 161
attachLimits 165
charLimits 164
CMDBAttributeGetStruct 161
CMDBAttributeLimit 162
CMDBAttributeNameId 166
CMDBSortList 168
CMDBSortStruct 168
CMDBWeakPropagatedAttrs 167
CMDBWeakPropagatedAttrsList 167
currencyLimits 165
dateLimits 165
decimalLimits 165
enumLimits 165
integerLimits 164
realLimits 164
audit
about 188
CMDBAuditInfoStruct 189
284

Developers Reference Guide

C API data structures (continued)

audit (continued)
CMDBAuditValueList 188
CMDBAuditValueListList 189
class
about 158
CMDBClassRelationship 159
CMDBClassTypeInfo 158
CMDBIndexList 160
CMDBIndexStruct 160
federation
about 186
CMDBFederatedActivateInfo 186
CMDBFederatedARInfo 186
general purpose
about 171
CMDBClassNameId 169
CMDBClassNameIdList 169
CMDBQualifierStruct 170
CMDBVersionInfo 171
CMDBVersionInfoList 171
graph query
about 178
CMDBGetObjectList 178
CMDBGetObjectStruct 178
CMDBGetRelationList 179
CMDBGetRelationStruct 179
CMDBGraphAdjacentList 179
CMDBGraphAdjacentStruct 180
CMDBGraphList 180
CMDBGraphStruct 181
import and export
about 172
CMDBExportItem 173
CMDBExportItemList 174
CMDBExportItemStruct 174
CMDBImportItem 175
CMDBImportItemList 176
CMDBImportItemStruct 176
CMDBItemTypeAttribute 173
CMDBItemTypeClass 172
CMDBXMLExportItemList 174
CMDBXMLImportItemList 176
instance
about 169
CMDBAttributeValueList 166
CMDBAttributeValueListList 166
CMDBAttributeValueStruct 167
Reconciliation Engine
about 183
CMDBREClassQualList 185
CMDBREClassQualStruct 184

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
C API data structures (continued)
Reconciliation Engine (continued)
CMDBREDatasetList 185
CMDBREDatasetPair 185
CMDBREJobRunInfo 184
CMDBREJobRunInfoList 183
user interface component
about 181
CMDBUIComponentInfo 181
CMDBUIComponentResult 182
CMDBUIComponentResultList 183
C API functions
about 82
audit
about 155
CMDBGetCopyAuditData 155
CMDBGetLogAuditData 157
bulk entry transaction
about 118
CMDBBeginBulkEntryTransaction 118
CMDBEndBulkEntryTransaction 119
data model management
about 82
CMDBCreateAttribute 83
CMDBCreateClass 99
CMDBCreateMultipleAttribute 86
CMDBDeleteAttribute 88
CMDBDeleteClass 101
CMDBGetAttribute 89
CMDBGetClass 102
CMDBGetListClass 104
CMDBGetMultipleAttribute 92
CMDBSetAttribute 95
CMDBSetClass 105
CMDBSetMultipleAttribute 97
environment
about 120
CMDBGetServerPort 122
CMDBInitialization 120
CMDBSetServerPort 123
CMDBSynchMetaData 121
CMDBSystemInit 121
CMDBTermination 124
federation
about 152
CMDBActivateFederatedInContext 153
CMDBGetRelatedFederatedInContext 152
free
about 136
FreeCMDBAttributeGetStruct 141
FreeCMDBAttributeLimit 138
FreeCMDBAttributeLimitList 139

C API functions (continued)

free (continued)
FreeCMDBAttributeLimitStruct 138
FreeCMDBAttributeValueList 146
FreeCMDBAttributeValueListList 146
FreeCMDBClassNameIdList 137
FreeCMDBClassTypeInfo 144
FreeCMDBExportItemList 140
FreeCMDBExportItemStruct 140
FreeCMDBGetObjectList 145
FreeCMDBGetRelationList 145
FreeCMDBGraphAdjacentList 142
FreeCMDBGraphAdjacentStruct 142
FreeCMDBGraphList 143
FreeCMDBGraphStruct 143
FreeCMDBImportItemList 141
FreeCMDBIndexList 139
FreeCMDBQualifierStruct 144
FreeCMDBREJobRunInfoList 147
FreeCMDBSortList 147
FreeCMDBVersionInfoList 137
import and export
about 128
CMDBExport 128
CMDBExportData 130
CMDBExportDef 129
CMDBImport 131
CMDBImportData 133
CMDBImportDef 132
instance management
about 107
CMDBCreateInstance 107
CMDBDeleteInstance 108
CMDBGetInstance 109
CMDBGetInstanceBLOB 113
CMDBGetListInstance 110
CMDBGetMultipleInstances 112
CMDBGraphQuery 115, 267
CMDBSetInstance 117
Reconciliation Engine
about 148
CMDBCancelJobRun 151
CMDBGetJobRun 149
CMDBGetListJobRun 150
CMDBStartJobRun 148
user interface component
about 125
CMDBExpandParametersForCI 127
CMDBGetCMDBUIComponents 125
CMDBRunQualificationForCI 126
utility
about 134

Index

285

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
C API functions (continued)
utility (continued)
CMDBCreateGuid 134
CMDBGetVersions 134
C API sessions
initializing 120
terminating 124
C API, compiling on HP machines 26
C APIs
about 17
compilers 26
components 17
data structures 158
driver source code 24
function calls 17
function definitions 82
functions 82
header files 24
installing package 24
library files 25
library links 27
calls
C API function 17
debugging with data structure contents 78
invoking bulk entry API 118
canceling reconciliation jobs 151, 218
CancelJobRun operation 218
character limits, defining 164
CharLimit structure 246
charLimits structure 164
CI instances. See instances
CI Relationship Viewer
about 63
AR System and 63
configuring 69
creating context menus 70
creating definitions 73
creating events 75
embedding in AR System forms 66
events
CIRV_LAYOUT 263
CIRV_NOTIFY_AR 264
CIRV_REFRESH 263
CIRV_SELECT_CI 263
CIRV_SET_AS_ROOT 263
CIRV_SET_CUSTOM_FILTER 262
CIRV_SET_FILTER 262
CIRV_SHOW 263
SELECTED_CI 264
filters 69
launching 64, 67
opening 64, 67

286

Developers Reference Guide

CI Relationship Viewer (continued)

transferring data with events
from AR System 262
to AR System 264
CIRV_LAYOUT event 263
CIRV_NOTIFY_AR event 264
CIRV_REFRESH event 263
CIRV_SELECT_CI event 263
CIRV_SET_AS_ROOT event 263
CIRV_SET_CUSTOM_FILTER event 262
CIRV_SET_FILTER event 262
CIRV_SHOW event 263
class forms
creating instances in 196
setting instances in 195
classes
accessing BMC Atrium CMDB directly 77
C API data structures 158
configuration item
about 32
creating 32
creating attributes 34
creating instances 36
creating
attributes 34
with cmdbdriver program 42
with core attributes 99, 206
data structures 158
deleting 101, 209
exporting
data with cmdbdriver 47
definitions 128, 129
definitions with cmdbdriver 47, 54
qualified 130
importing
data 133
data with cmdbdriver 49
definitions 131, 132
definitions with cmdbdriver 49
installing extensions with cmdbExtLoader 53
managing 82
relationship
about 37
creating 37
retrieving 207
retrieving 102, 104, 204
retrieving list of UI components 125, 224
setting properties 105, 205
storing
attribute index information 160
audit options 189
CI definitions 158

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
classes (continued)
storing (continued)
CI properties 239
CI relationship information 237
class names 166
display properties 241
display property structures 241
index information 160, 240
information to retrieve 237
information to set 236
names 169, 172, 228
namespace names 166, 169, 228
qualification information 254
relationship definitions 158
relationship information 159
type information 158
web services API data structures 236
ClassInfoIn structure 236
ClassInfoOut structure 237
ClassNameId structure 228
ClassNameIdList structure 228
ClassProperties structure 239
ClassQualifier structure 254
ClassQualifierList structure 254
ClassRelationship structure 237
CMDB APIs
about 16
architecture 16
C APIs 17
Java APIs 18
migrating to 29
programming 19
programs, when to write 19
sample source code 29
terminology changes 20
web services APIs 18
CMDB Console API programming and 19
CMDB. See BMC Atrium CMDB
CMDBActivateFederatedInContext function 153
CMDBAttributeGetStruct structure 161
CMDBAttributeLimit structure 162
CMDBAttributeNameId structure 166
CMDBAttributeValueList structure 166
CMDBAttributeValueListList structure 166
CMDBAttributeValueStruct structure 167
CMDBAuditInfoStruct structure 189
CMDBAuditValueList structure 188
CMDBAuditValueListList structure 189
CMDBBeginBulkEntryTransaction function 118
CMDBCancelJobRun function 151
CMDBClassNameId structure 169
CMDBClassNameIdList structure 169

CMDBClassRelationship structure 159

CMDBClassTypeInfo structure 158
CMDBCreateAttribute function 83
CMDBCreateClass function 99
CMDBCreateGuid function 134
CMDBCreateInstance function 107
CMDBCreateMultipleAttribute function 86
CMDBDeleteAttribute function 88
CMDBDeleteClass function 101
CMDBDeleteInstance function 108
cmdbdriver program
about 42
exporting
class data 47
class definitions 47
instance data 48
subclass definitions 47
importing
class data 49
class definitions 49
instance data 50
starting 46
using from command line 42
using on UNIX 45
CMDBEndBulkEntryTransaction function 119
CMDBExpandParametersForCI function 127
CMDBExport function 128
CMDBExportData function 130
CMDBExportDef function 129
CMDBExportItem structure 173
CMDBExportItemList structure 174
CMDBExportItemStruct structure 174
cmdbExtLoader program
about 53
file structure 53
starting 59
CMDBFederatedActivateInfo structure 186
CMDBFederatedARInfo structure 186
CMDBGetAttribute function 89
CMDBGetClass function 102
CMDBGetCMDBUIComponents function 125
CMDBGetCopyAuditData function 155
CMDBGetInstance function 109
CMDBGetInstanceBLOB function 113
CMDBGetJobRun function 149
CMDBGetListClass function 104
CMDBGetListInstance function 110
CMDBGetListJobRun function 150
CMDBGetLogAuditData function 157
CMDBGetMultipleAttribute function 92
CMDBGetMultipleInstances function 112
CMDBGetObjectList structure 178

Index

287

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
CMDBGetObjectStruct structure 178
CMDBGetRelatedFederatedInContext function 152
CMDBGetRelationList structure 179
CMDBGetRelationStruct structure 179
CMDBGetServerPort function 122
CMDBGetVersions function 134
CMDBGraphAdjacentList structure 179
CMDBGraphAdjacentStruct structure 180
CMDBGraphList structure 180
CMDBGraphQuery function 115, 267
CMDBGraphStruct structure 181
CMDBImport function 131
CMDBImportData function 133
CMDBImportDef function 132
CMDBImportItem structure 175
CMDBImportItemList structure 176
CMDBImportItemStruct structure 176
CMDBIndexList structure 160
CMDBIndexStruct structure 160
CMDBInitialization function 120
CMDBItemTypeAttribute structure 173
CMDBItemTypeClass structure 172
CMDBQualifierStruct structure 170
CMDBREClassQualList structure 185
CMDBREClassQualStruct structure 184
CMDBREDatasetList structure 185
CMDBREDatasetPair structure 185
CMDBREJobRunInfo structure 184
CMDBREJobRunInfoList structure 183
CMDBRunQualificationForCI function 126
CMDBSetAttribute function 95
CMDBSetClass function 105
CMDBSetInstance function 117
CMDBSetMultipleAttribute function 97
CMDBSetServerPort function 123
CMDBSortList structure 168
CMDBSortStruct structure 168
CMDBStartJobRun functions 148
CMDBSynchMetaData function 121
CMDBSystemInit function 121
CMDBTermination function 124
CMDBUIComponentInfo structure 181
CMDBUIComponentResult structure 182
CMDBUIComponentResultList structure 183
CMDBVersionInfo structure 171
CMDBVersionInfoList structure 171
CMDBWeakPropagatedAttrs structure 167
CMDBWeakPropagatedAttrsList structure 167
CMDBXMLExportItemList structure 174
CMDBXMLImportItemList structure 176
commands, cmdbdriver program 42
committing bulk entry transactions 119

288

Developers Reference Guide

compilers, C APIs 26
components
C API 17
web services API 18
configuration items
See also instances
classes 32
creating instances 36
querying instances 40
viewing relationships 63
context menus, creating 70
CreateAttribute operation 211
CreateClass operation 206
CreateInstance operation 196
CreateRelationInstance operation 199
creating
AR System forms 121
attributes 83, 86, 211
CI classes 32
CI Relationship Viewer
context menus 70
definitions 73
events 75
classes 99, 206
classes with cmdbdriver program 42
forms 121
globally unique IDs 134
installation activity file 57
instances
CI 36, 107
in class forms 196
relationship 107
with cmdbdriver program 42
instances relationship 199
package.xml file 55
relationship classes 37
currency limits, defining 165
CurrencyLimit structure 247
currencyLimits structure 165
customer support 3

D
data
importing with EIE 76
limits, defining 165
transferring
from CI Relationship Viewer 264
to CI Relationship Viewer 262
data models
management functions, C API 82
managing 82

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
data models (continued)
operations, web services API 204
data structures
C API
about 158
attribute 161
audit 188
class 158
export 172
federation 186
general purpose 171
graph query 178
import 172
instance 169
Reconciliation Engine 183
user interface component 181
printing contents 78
web services API
about 227
attribute 242
audit 258
class 236
federation 256
graph 232
instance 227
job 253
user interface component 251
utility 250
DatasetPair structure 255
DatasetPairList structure 254
DateLimit structure 248
dateLimits structure 165
debugging
calls with data structure contents 78
debugging APIs 78
decimal limits, defining 165
decimalLimits structure 165
defining
attachment limits 165
character limits 164
currency limits 165
date limits 165
decimal limits 165
enum limits 165
integer limits 164
query graph lists 180
real limits 164
definitions
creating CI Relationship Viewer 73
exporting
attribute with cmdbdriver 54
class 128, 129

definitions (continued)
exporting (continued)
class with cmdbdriver 47, 54
subclass with cmdbdriver 47
importing
class 131, 132
class with cmdbdriver 49
storing
attribute 161
CI 158
relationship 158
Delete Attribute operation 213
DeleteClass operation 209
DeleteInstance operation 197
deleting
attributes 213
attributes with specified ID 88
classes 209
instances 108, 197
specified class 101
display properties, storing for classes 241
documentation for BMC Atrium CMDB 10, 11

E
EIE, importing data with 76
Enterprise Integration Engine. See EIE
enum limits, defining 165
EnumLimit structure 248
enumLimits structure 165
environment functions 120
events
creating CI Relationship Viewer 75
transferring from
AR System to CI Relationship Viewer 262
CI Relationship Viewer to AR System 264
ExecuteJobRun operation 215
expanding federated instances 153, 219
exporting
attribute definitions with cmdbdriver 54
C API data structures 172
C API functions 128
class
data with cmdbdriver 47
data, qualified 130
definitions 128, 129
definitions with cmdbdriver 47, 54
CMDB data 128
instance data with cmdbdriver 48
storing data for 172
subclass definitions with cmdbdriver 47

Index

289

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

F
features
Java API 19
Web services API 18
federated instances, activating 153
FederatedActivateInfo structure 256
FederatedARInfo structure 257
federation
data structures 186, 256
expanding instances 153, 219
functions 152
launching instances 153, 219
operations 219
retrieving instances 152, 221
storing AR system data 186, 257
storing instance activation data 186, 256
filters, CI Relationship Viewer 69
forms, creating 121
free functions 136
FreeCMDBAttributeGetStruct function 141
FreeCMDBAttributeLimit function 138
FreeCMDBAttributeLimitList function 139
FreeCMDBAttributeLimitStruct function 138
FreeCMDBAttributeValueList function 146
FreeCMDBAttributeValueListList function 146
FreeCMDBClassNameIdList function 137
FreeCMDBClassTypeInfo function 144
FreeCMDBExportItemList function 140
FreeCMDBExportItemStruct function 140
FreeCMDBGetObjectList function 145
FreeCMDBGetRelationList function 145
FreeCMDBGraphAdjacentList function 142
FreeCMDBGraphAdjacentStruct function 142
FreeCMDBGraphList function 143
FreeCMDBGraphStruct function 143
FreeCMDBImportItemList function 141
FreeCMDBIndexList function 139
FreeCMDBQualifierStruct function 144
FreeCMDBREJobRunInfoList function 147
FreeCMDBSortList function 147
FreeCMDBVersionInfoList function 137
functions
C API
audit 155
bulk entry transaction 118
calls 17
data model management 82
environment 120
federation 152
free 136
import and export 128

290

Developers Reference Guide

functions (continued)
C API (continued)
instance management 107
Reconciliation Engine 148
user interface component 125
utility 134
web services API 192

G
general purpose data structures 171
GetAttributes operation 210
GetClass operation 204
GetCopyAuditData operation 222
GetInstances operation 193
GetJobRun operation 216
GetListJobRun operation 217
GetRelatedFederatedInContext operation 221
GetUIComponents operation 224
GetVersions operation 225
Graph structure 232
GraphAdjacency structure 233
GraphAdjacencyList structure 233
GraphList structure 232
GraphQuery operation 201
graphs
adjacency lists, collections of 266
adjacency matrixes 266
query data structures
C API 178
web services API 232
representing 266
storing adjacency items 233

H
header files
C API 24
CMDB program 28
HP machines C API, compiling 26

I
icon, New 9
IDs, creating globally unique 134
import and export functions 128
importing
C API data structures 172
C API functions 128
class
data 133

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
importing (continued)
class (continued)
data with cmdbdriver 49
definitions 131, 132
definitions with cmdbdriver 49
CMDB data 128
data with EIE 76
instance data with cmdbdriver 50
storing data for 172
IndexInfo structure 240
IndexList structure 240
initializing
networks 121
servers 121
installation activity file, creating 57
installing
attribute extensions with cmdbExtLoader 53
C API package 24
class extensions with cmdbExtLoader 53
CMDB extensions 54
InstanceInfo structure 230
InstanceInfoList structure 229
instances
See also configuration items and relationships
C API management functions 107
C API structures 169
creating
CI 107
configuration item 36
in class forms 196
relationship 107
with cmdbdriver program 42
data operations 192
data structures 227
deleting 108, 197
expanding CI parameters 127
expanding federated 153, 219
exporting data with cmdbdriver 48
importing data with cmdbdriver 50
launching federated 153
management functions 107
managing 107
querying 40, 201
retrieving
audit logs 157
BLOBs 113
CI audit data 155, 222
federated 152
list of 110, 193
multiple 112
single 109
retrieving federated 221

instances (continued)
searching for related 115
setting CI 117
setting in class forms 195
setting relationship 117
storing
CI 178
data 169
list of values 229
relationship 179
values 230
structures 169
viewing relationships 63
web services API data structures 227
web services API operations 192
integer limits, defining 164
integerLimits attribute structure 164
IntLimit structure 248

J
Java API changes 23
Java APIs
about 18
environment components 27
features 19
program requirements 27
JobRunInfo structure 253
JobRunInfoList structure 253
jobs. See reconciliation jobs

K
known issues, migrating CMDB data 52

L
launching
CI Relationship Viewer 64, 67
federated instances 153, 219
library
files, C API 25
links, C API 27
limits, defining
attachment 165
character 164
currency 165
date 165
decimal 165
enum 165
integer 164

Index

291

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
limits, defining (continued)
real 164
linking libraries, C API 27
ListClasses operation 207
login information, storing 227
LoginInfo structure 227

M
managing
attributes 82
classes 82
data models 82
instances 107
reconciliation jobs 148
matrixes, representing graphs as 266
memory, releasing 136
menus, creating context 70
migrating
CMDB data between servers 45
known issues 52
to BMC Atrium CMDB 2.0 API 29

N
names
storing class 166, 169, 228
storing namespace 166, 169, 228
networks, initializing 121
New icon 9
new in this release 22
API compatibility 22
Java API changes 23

O
ObjectQueryInfo structure 234
ObjectQueryInfoList structure 234
opening, CI Relationship Viewer 64, 67
operations, web services API
about 192
audit 222
data model 204
federation 219
reconciliation job 215
storing status 230, 231
user interface component 224
utility 225

292

Developers Reference Guide

P
package.xml file, creating 55
parameters, expanding CI 127
ports
retrieving 122
setting 123
print.c file 78
printing
data structure contents 78
print.c file 78
product support 3
programs
cmdbdriver program 42
cmdbExtLoader 53
propagating attribute values 167
PropInfo structure 241
PropInfoList structure 241

Q
qualifications, storing strings 170
querying
C API graph query data structures 178
instances 40
instances related to CIs 201
storing
CIs for 234
graph list definitions for 180
graph nodes for 181
graphs for 232
list of CIs for 234
list of relationships for 235
relationships for 235

R
real data limits, defining 164
RealLimit structure 249
realLimits attribute structure 164
Reconciliation Engine
C API data structures 183
C API functions 148
managing jobs 148
reconciliation jobs
canceling 151, 218
data structures 253
operations 215
retrieving
data for running 149
list of running 150, 217
logs for running 149

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
reconciliation jobs (continued)
retrieving (continued)
single running 216
starting 148, 215
storing
all running 253
datasets 185, 254, 255
qualifications 184, 185
running 183, 184
single 253
RelationQueryInfo structure 235
RelationQueryInfoList structure 235
relationship instances, creating 199
relationships
See also instances
classes 37
querying instances 40
viewing 63
releasing memory 136
retrieving
attributes 89, 92, 210
audit data 155, 222
audit logs 157
classes 102, 104, 204
federated instances 152, 221
instance BLOBs 113
instances 109, 110, 112, 193
ports 122
reconciliation jobs 149, 150, 216, 217
relationship classes 207
server ports 122
UI component lists 125, 224
version of CMDB components 134, 225

S
samples
C API driver programs 24
CMDB API source code 29
searching for instances 115
SELECTED_CI event 264
server ports
retrieving 122
setting 123
servers
initializing 121
retrieving ports 122
setting ports 123
sessions
initializing C API 120
terminating C API 124
SetAttribute operation 212

SetClass operation 205

SetInstance operation 195
setting
attributes 95, 97, 212
class properties 105, 205
instances 117
instances in class forms 195
ports 123
server ports 123
sorting attributes 229
sorting attributes by type 229
SortOrder structure 229
SortOrderList structure 229
source code
C API driver 24
sample CMDB API 29
SQL views 77
starting
bulk entry transactions 118
cmdbdriver program 46
cmdbExtLoader program 59
reconciliation jobs 148, 215
Status structure 231
status, storing 230, 231
StatusList structure 230
storing
adjacent nodes 179, 180
AR System federated data 186, 257
attributes
attachment limits 246
character limits 246
currency limits 247
data limits 245, 249
date limits 248
definitions 161
enum limits 248
index information 160, 240
information 173, 242, 243
integer limits 248
real data limits 249
retrieval information 161
sort information 168, 229
sort information by type 229
values 166, 167, 243
audit options 189, 259
audit value lists 188, 189, 258
CI definitions 158
CI instances 178
CIs to query 234
classes
CI properties 239
CI relationship information 237

Index

293

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
storing (continued)
classes (continued)
data 158
display properties 241
display property structures 241
index information 160, 240
information to retrieve 237
information to set 236
names 166, 169, 172, 228
namespace names 166, 169, 228
qualification information 254
type information 158
export data 172
federated instance activation data 186, 256
graph adjacency items 233
graph nodes 181
import data 172
instance data 169
instance values 229, 230
items to export 173, 174
items to import 175, 176
login information 227
operation statuses 230, 231
qualification strings 170
query graph list definitions 180
query graphs 232
reconciliation job datasets 185, 254, 255
reconciliation job qualifications 184, 185
reconciliation jobs 253
relationships
definitions 158
information 159
instances 179
to query 235
running reconciliation jobs 183, 184
source attributes 167
strings 228
target attributes 167
UI component information 252
UI component query results 182, 183, 252
UI components to retrieve 181, 251
versions of CMDB components 171, 250
XML items to export 174
XML items to import 176
strings, storing 228
subclasses, exporting definitions 47
support, customer 3

294

Developers Reference Guide

T
technical support 3
terminating C API sessions 124
terminology
changes 20
CMDB and API 20
tools, CMDB 4178

U
UI components. See user interface components
UIComponentInfo structure 251
UIComponentResult structure 252
UIComponentResultList structure 252
user interface components
data structures 181
functions 125
operations 224
retrieving list of 125, 224
storing
information 252
query results 182, 183, 252
to retrieve 181, 251
web services API data structures 251
user login information, storing 227
utilities
CMDB 4178, 134, 225
functions 134
operations 225
web services API data structures 250

V
validating attributes, CI 126
VersionInfo structure 250
VersionInfoList structure 250
versions, retrieving CMDB component 134, 225
viewing
configuration item relationships 63
instance relationships 63
views, SQL 77

W
web services API data structures
attribute
about 242
AttachmentLimit 246
AttributeInfoIn 243
AttributeInfoList 242

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
web services API data structures (continued)
attribute (continued)
AttributeLimit 245
AttributeLimitList 249
AttributeValue 243
AttributeValueList 243
CharLimit 246
CurrencyLimit 247
DateLimit 248
EnumLimit 248
IntLimit 248
RealLimit 249
audit
about 258
AuditInfo 259
AuditValueList 258
AuditValueListList 258
class
about 236
ClassInfoIn 236
ClassInfoOut 237
ClassProperties 239
ClassRelationship 237
IndexInfo 240
IndexList 240
PropInfo 241
PropInfoList 241
federation
about 256
FederatedActivateInfo 256
FederatedARInfo 257
graph
about 232
Graph 232
GraphAdjacency 233
GraphAdjacencyList 233
GraphList 232
ObjectQueryInfo 234
ObjectQueryInfoList 234
RelationQueryInfo 235
RelationQueryInfoList 235
instance
about 227
ArrayOf_String 228
ClassNameId 228
ClassNameIdList 228
InstanceInfo 230
InstanceInfoList 229
LoginInfo 227
SortOrder 229
SortOrderList 229
Status 231

web services API data structures (continued)

instance (continued)
StatusList 230
job
about 253
ClassQualifier 254
ClassQualifierList 254
DatasetPair 255
DatasetPairList 254
JobRunInfo 253
JobRunInfoList 253
user interface component
about 251
UIComponentInfo 251
UIComponentResult 252
UIComponentResultList 252
utility
about 250
VersionInfo 250
VersionInfoList 250
web services API operations
audit
about 222
GetCopyAuditData 222
data model
about 204
CreateAttribute 211
CreateClass 206
Delete Attribute 213
DeleteClass 209
GetAttributes 210
GetClass 204
ListClasses 207
SetAttribute 212
SetClass 205
federation
about 219
ActivateFederatedInContext 219
GetRelatedFederatedInContext 221
instance data
about 192
CreateInstance 196
CreateRelationInstance 199
DeleteInstance 197
GetInstances 193
GraphQuery 201
SetInstance 195
reconciliation job
about 215
CancelJobRun 218
ExecuteJobRun 215
GetJobRun 216

Index

295

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
web services API operations (continued)
reconciliation job (continued)
GetListJobRun 217
user interface component
about 224
GetUIComponents 224
utility
about 225
GetVersions 225
web services APIs
about 18
components 18
data structures 227
features 18
functions 192
operations 192

296

Developers Reference Guide

*70088*
*70088*
*70088*
*70088*
*70088*