Documente Academic
Documente Profesional
Documente Cultură
Copyright 19912006 BMC Software, Inc. All rights reserved. BMC, the BMC logo, all other BMC product or service names, BMC Software, the BMC Software logos, and all other BMC Software product or service names, are registered trademarks or trademarks of BMC Software, Inc. All other trademarks belong to their respective companies. BMC Software, Inc., considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable end user license agreement or nondisclosure agreement for the product and the proprietary and restricted rights notices included in this documentation. Restricted Rights Legend
U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.
Contacting Us If you need technical support for this product, contact Customer Support by email at support@remedy.com. If you have comments or suggestions about this documentation, contact Information Development by email at doc_feedback@bmc.com. This edition applies to version 2.0.1 of the licensed program.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 The New icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 BMC Atrium CMDB documentation . . . . . . . . . . . . . . . . . . 10
Section I
Chapter 1
Chapter 2
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . 23
C API package contents . . . . . . . . . . . . . . . . . . . . . . . . 24 Header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Compiler information . . . . . . . . . . . . . . . . . . . . . . . . 29 Link information . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Contents
Java API package contents . . . . . . . . . . . . . . . . . . . . . . . 30 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Sample source code . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Renamed C and Java API objects . . . . . . . . . . . . . . . . . . . . 33 Migrating to the BMC Atrium CMDB 2.0 API . . . . . . . . . . . . . . 33 API parameter changes . . . . . . . . . . . . . . . . . . . . . . . 34 Data structure changes. . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 3
Chapter 4
Contents
Using the extension loader . . . . . . . . . . . . . . . . . . . . . . . 61 The extension loader directory structure . . . . . . . . . . . . . . . . 62 Packaging and installing BMC Atrium CMDB extensions . . . . . . . . . 63 Integrating the CI Relationship Viewer with other applications . . . . . . . 70 Launching the CI Relationship Viewer from AR System applications . . . . 71 Embedding the CI Relationship Viewer in AR System applications . . . . . 73 Launching the CI Relationship Viewer from non-AR System applications . . 75 Configuring the CI Relationship Viewer . . . . . . . . . . . . . . . . . 77 Working with filters . . . . . . . . . . . . . . . . . . . . . . . . . 77 Customizing the configuration file. . . . . . . . . . . . . . . . . . . 77 Creating CI Relationship Viewer events . . . . . . . . . . . . . . . . 84 Creating CMDB status alerts . . . . . . . . . . . . . . . . . . . . . . 85 Importing data with EIE . . . . . . . . . . . . . . . . . . . . . . . . 86 Working with SQL views . . . . . . . . . . . . . . . . . . . . . . . . 87 Debugging BMC Atrium CMDB API programs . . . . . . . . . . . . . . 88 Using the API Logging option . . . . . . . . . . . . . . . . . . . . 88 Using print.c routines . . . . . . . . . . . . . . . . . . . . . . . . 89
Section II
Chapter 5
API reference . . . . . . . . . . . . . . . . . . . . . . . . 91
C API functions and data structures . . . . . . . . . . . . . . . . 93
Related files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Deprecated objects . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Deprecated functions . . . . . . . . . . . . . . . . . . . . . . . . 94 Deprecated data structures . . . . . . . . . . . . . . . . . . . . . . 95
Contents
Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Data model functions . . . . . . . . . . . . . . . . . . . . . . . . 95 Instance functions . . . . . . . . . . . . . . . . . . . . . . . . 126 Bulk entry transaction functions . . . . . . . . . . . . . . . . . . 139 Environment functions . . . . . . . . . . . . . . . . . . . . . . 141 User interface component functions . . . . . . . . . . . . . . . . . 146 Import and Export functions . . . . . . . . . . . . . . . . . . . . 149 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . 155 Free functions . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Reconciliation Engine functions. . . . . . . . . . . . . . . . . . . 172 Federation functions . . . . . . . . . . . . . . . . . . . . . . . 176 Audit functions. . . . . . . . . . . . . . . . . . . . . . . . . . 179 Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Class structures . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Attribute structures . . . . . . . . . . . . . . . . . . . . . . . . 186 Instance structures . . . . . . . . . . . . . . . . . . . . . . . . 196 General purpose structures . . . . . . . . . . . . . . . . . . . . . 198 Export and import structures . . . . . . . . . . . . . . . . . . . . 199 Graph query structures . . . . . . . . . . . . . . . . . . . . . . 206 User interface components structures . . . . . . . . . . . . . . . . 210 Reconciliation Engine structures . . . . . . . . . . . . . . . . . . 212 Federation structures . . . . . . . . . . . . . . . . . . . . . . . 215 Audit structures . . . . . . . . . . . . . . . . . . . . . . . . . 218
Chapter 6
Contents
Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Instance structures . . . . . . . . . . . . . . . . . . . . . . . . 262 Graph query structures . . . . . . . . . . . . . . . . . . . . . . 267 Class Structures. . . . . . . . . . . . . . . . . . . . . . . . . . 272 Attribute structures . . . . . . . . . . . . . . . . . . . . . . . . 278 Utility structures . . . . . . . . . . . . . . . . . . . . . . . . . 286 User interface component structures . . . . . . . . . . . . . . . . . 288 Reconciliation Engine structures . . . . . . . . . . . . . . . . . . 290 Federation structures . . . . . . . . . . . . . . . . . . . . . . . 293 Audit structures . . . . . . . . . . . . . . . . . . . . . . . . . 295
Chapter 7
Appendix A
Appendix B
Contents
Contents
Preface
The BMC Atrium CMDB 2.0.1 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 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. It also provides a list of error messages generated in the BMC Atrium CMDB along with their descriptions and solutions.
The BMC Atrium CMDB application runs on top of the BMC Remedy Action Request System application (AR System) and enables you to manage data about your IT environment.
Preface
Audience
This guide is intended for application programmers. For more information about configuring the application, see the Installation and Configuration Guide.
BMC Atrium CMDB 2.0 Information about CMDB concepts and IT leaders and Print and Concepts and Best Practices Guide best practices for planning your BMC administrators PDF Atrium CMDB implementation. BMC Atrium CMDB 2.0.1 Installation and Configuration Guide Information about installing and configuring the BMC Atrium CMDB, including permissions, class definitions, reconciliation, and federation. Administrators Print and PDF
BMC Atrium CMDB 2.0.1 Users Information about using the BMC Guide Atrium CMDB, including searching for and comparing CIs and relationships, relating CIs, viewing history, and launching federated data.
Users
10
Preface
Document provides
Audience
Format
Administrators Print and Information about creating API PDF programs, using C and web services API and functions and data structures, and a list programmers of error messages. Combined index of all guides. Information about new features, open issues, and resolved issues. Everyone Everyone Print and PDF Print and PDF
BMC Atrium CMDB 2.0.1 Master Index BMC Atrium CMDB 2.0.1 Release Notes BMC Atrium CMDB 2.0 Common Data Model Diagram
Hierarchical diagram of all classes in the Administrators PDF Common Data Model (CDM) including unique attributes and applicable relationships, and a relationship normalization table. Description and details of superclasses, subclasses, attributes, and relationships for each class. Administrators HTML
BMC Atrium CMDB 2.0.1 Common Data Model Help BMC Atrium CMDB 2.0.1 Javadoc API Help
Information about Java classes, methods, Programmers and variables that integrate with the BMC Atrium CMDB.
HTML
BMC Atrium CMDB 2.0.1 Help Help for using and configuring the BMC Users and Product Atrium CMDB. administrators Help BMC Remedy Action Request System 7.0: C API Reference BMC Remedy Action Request System 7.0: Configuring BMC Remedy Action Request System 7.0: Form and Application Objects BMC Remedy Action Request System 7.0: Installing Administrators Print and Information about AR System data PDF structures, C API function calls, and OLE and programmers support. Information about configuring AR System servers and clients, localizing, importing and exporting data, and archiving data. Administrators Print and PDF
Description of the components necessary Developers to build applications in AR System, including applications, fields, forms, and views. Procedures for installing AR System.
11
Title BMC Remedy Action Request System 7.0: Installing and Administering BMC Remedy Mid Tier BMC Remedy Action Request System 7.0: Integrating with Plug-ins and Third-Party Products BMC Remedy Action Request System 7.0: Workflow Objects
Document provides Information about the mid tier, including mid tier installation and configuration, and web server configuration.
Audience
Format
Administrators Print and Information about integrating AR System with external systems using plug- and developers PDF ins and other products, including LDAP, OLE, and ARDBC. Information about the workflow. Developers Print and PDF
12
Preface
Section
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.
13
14
Chapter
BMC Atrium CMDB API overview (page 16) Using API programming compared with the CMDB Console (page 20)
15
Reconciliation Engine
CMDB C API
AR System API
Note: The arrows indicate the directions in which each program or process can initiate an API function. Data can flow in any direction.
16
As shown in Figure 1-1 on page 16, a BMC Atrium CMDB components, such as the CI Relationship Viewer and CMDB Console use the Java API to manipulate the CDM, whereas the external data consumers and data providers can communicate either using the web services API or Java API. This guide describes the C and web services APIs. For more information about the Java API, see the Javadoc API Help, which is located in the sdk/ doc/javadoc/cmdbapi/ subdirectory of your BMC Atrium CMDB installation directory. To access the Javadoc API Help, open the index.html file.
C API
A BMC Atrium CMDB client can use the C API to create, modify, delete, and query the class definitions, instance data, federation, reconciliation, and other functions. The C API:
!
Contains data structures that store both simple and complex information. A simple data structure serves as the primary building block for a complex data structure. Includes a set of Free functions that you can use to deallocate memory. Provides server-access information with every call in the control parameter of the function.
! !
Features
You can use the C API functions to perform operations, such as:
! ! !
Create, modify, and delete classes and instances. Retrieve CI and relationship information. Create log files in a format that is different from the standard reports.
Components
The C API consists of a set of functions and data structures, most of which perform a specific database or data source operation. For example, you can use a function to retrieve information about a particular BMC Atrium CMDB class.
17
Most of these C API functions accept one or more BMC Atrium CMDB C data structures as parameters that qualify the action to perform, such as type of class to create, qualification for an instance to retrieve or delete, or class name to modify. For more information about the C API functions and data structures, see Chapter 5, C API functions and data structures. The sdk/samples/driver subdirectory in your BMC Atrium CMDB installation directory contains the source code for the cmdbdriver program. This program provides a command-line interface for calling C API functions. The cmdbdriver program also includes print routines for every data structure in the API, making it a useful debugging tool. For more information about the print routines, see Debugging BMC Atrium CMDB API programs on page 88.
Features
External web-based programs can communicate with the BMC Atrium CMDB using the web services operations. The BMC Atrium CMDB web services operations are developed to assist the following communities:
!
BMC software partnersFor developing integrated solutions with the BMC Atrium CMDB. UsersFor developing programs that set up communication between the BMC Atrium CMDB and other products running in their environment.
Although the web services operations are based on the BMC Atrium CMDB C API functions, they do not correspond one-to-one with the C API.
18
Components
The web services API is a wrapper on top of the Java API. Therefore, each of the web services operations and data structures corresponds to a method in the Java API. For more information about the web services operations that are currently available, see Chapter 6, Web services API operations and data structures.
Java API
The BMC Atrium CMDB Java API is a collection of Java classes and methods that provide the C API functionality in a Java development environment. Use the Java API if you write server-side web applications that you access through the Java Server page (JSP) or Java servlets web tier layer. The Java API provides an object model of the BMC Atrium CMDB. You will find it easier to use the Java API if you are already familiar with the C API. For more information about the Java API, see the Javadoc API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory. To access the Javadoc API Help, open the index.html file.
Features
The following list describes the Java API features:
!
The Java virtual machine (JVM) automatically deallocates objects that are created with the Java API. In the Java API, server access information is encapsulated in an ARServerUser object. For more information about ARServerUser object, see BMC Remedy Action Request System 7.0: Integrating with Plug-ins and Third-Party Products. The Java API has its own naming conventions.
19
Requirement 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. You need to create, delete, or search for BMC Atrium CMDB classes.
Yes
Yes
20
Requirement You need to perform complex operations that involve multiple objects. You need to create, delete, or search BMC Atrium CMDB relationships. You need a two-way interface (or gateway) between the BMC Atrium CMDB and another application. The values you want to specify for $PROCESS$ or the Run Process action exceed the size limitation of the command line.
Yes Yes
Yes
21
22
Chapter
Getting started
This chapter describes the preliminary steps you must follow before you use the BMC Atrium CMDB API suite. The following topics are provided:
! ! ! ! !
C API package contents (page 24) Java API package contents (page 30) Sample source code (page 32) Renamed C and Java API objects (page 33) Migrating to the BMC Atrium CMDB 2.0 API (page 33)
Getting started
23
Header files
Table 2-1 displays the list of C API header files installed in the include directory:
Table 2-1: C API Header files
File Name
ar.h cmdb.h arerrno.h arextern.h
Contents AR System API data type and structure definitions, size limits, and constant definitions. BMC Atrium CMDB C API data type and structure definitions, size limits, and constant definitions. Error code definitions. External declarations for the API functions, specified with and without prototypes for use with standard C, ANSI C, or C++ compilers. External declarations for the FreeAR functions. These functions recursively free all allocated memory associated with a particular data structure. External declarations for the FreeCMDB functions. These functions recursively free all allocated memory associated with a particular data structure. Core and reserved subclasses ID definitions, database separator characters, and labels for exporting structure definitions.
arfree.h
cmdbfree.h
arstruct.h
24
Library files
You must have arcatalog_eng.dll in your path at runtime and make sure the lib directory contains the API library files listed in Table 2-2.
Table 2-2: C API library files
Platform
Windows
Files
mfc71.dll msvcp71.dll msvcr71.dll Xalan-C_1_9.dll XalanMessages_1_9.dll arapi70.dll arcatalog_eng.dll ariapi70.dll arjni70.dll arrpc70.dll arutiljni70.dll arutl70.dll arxmlutil70.dll cmdb2asset.dll cmdbapi20.dll cmdbeng20.dll cmdbjni20.dll cmdbsvr20.dll icudt32.dll icuin32.dll icuuc32.dll libcmdbconsolefilterapi20.dll rcmn70.dll xerces-c_2_6.dll xerces-depdom_2_6.dll
25
Platform Solaris
Files
libcmdbjni20.so libcmdbeng20.so libcmdbsvr20.so libutil.a libcmdbapi20.so libcmdb2asset.so libcmdbconsolefilterapi20.so libar.a libxerces-depdombmc.so.26 libari70.so libicui18nbmc.so.32 libarutiljni70.so libarjni70.so libicudatabmc.so.32 libxalanMsgbmc.so.19 libjlicapi70.so libxalan-cbmc.so.19 libarxmlutil.so libicuucbmc.so.32 libxerces-cbmc.so.26
26
Platform AIX
Files
libcmdbsvr20.a libcmdbapi20.a libcmdbeng20.a libcmdbconsolefilterapi20.a libutil.a libcmdb2asset.a libar.a libcmdbjni20.a libxerces-cbmc26.0.a libarutiljni70.a libarxmlutil.a libxerces-depdombmc.a libxerces-cbmc.a libarjni70.a libxerces-cbmc26.a libxalan-cbmc19.a libxerces-depdombmc26.a libicui18nbmc32.a libicuucbmc32.a libxerces-depdombmc26.0.a libxalanMsgbmc.a libicudatabmc32.a libjlicapi70.a libari70.a
27
Platform HP-UX
Files
libutil.a libcmdbjni20.sl libar.a libcmdb2asset.sl libcmdbeng20.sl libcmdbapi20.sl libcmdbsvr20.sl libcmdbconsolefilterapi20.sl libicui18nbmc.sl.32 libxalan-cbmc.sl.19 libari70.sl libarjni70.sl libjlicapi70.sl libicudatabmc.sl.32 libxalanMsgbmc.sl.19 libarxmlutil.sl libxerces-depdombmc.sl.26 libarutiljni70.sl libxerces-cbmc.sl.26 libicuucbmc.sl.32
28
Platform Linux
Files
libcmdbeng20.so libar.a libcmdbjni20.so libcmdbconsolefilterapi20.so libcmdbapi20.so libcmdbsvr20.so libcmdb2asset.so libutil.a libicudatabmc.so.32 libxalanMsgbmc.so.19 libxalan-cbmc.so.19 libxerces-cbmc.so.26 libari70.so libarutiljni70.so libicui18nbmc.so.32 libjlicapi70.so libxerces-depdombmc.so.26 libarxmlutil.so libarjni70.so libicuucbmc.so.32
For Solaris and Linux: To load dynamic libraries, you need to include the -ldl link flag in the link command. For more information about linking and compiling your code, see the driver sample makefile in the sdk\samples\driver subdirectory of the BMC Atrium CMDB installation directory.
Compiler information
Before you write C API programs, make sure that the following software programs are installed or configured on your system:
! !
Microsoft Visual C++ version 7.0 or later Structure member alignment: 8 bytes (default)
29
Set code generation to Multithreaded DLL, not DebugMultithreaded DLL. Where other included libraries cause conflicts, add /nodefaultlib:"MSVCRTD" to the project options to avoid using the Debug C runtime library. If your program references this library at runtime, memory management errors will occur when memory pointers are referenced by both the Debug and Release C runtime libraries. ANSI standard C or C++ compiler (for UNIX)
Link information
Table 2-3 lists the libraries that your programs must use for linking to the BMC Atrium CMDB.
Table 2-3: Link files
Links
cmdbapi20.dll arapi70.dll libcmdbapi20.so libarapi70.so libcmdbapi20.sl libarapi70.sl libcmdbapi20.a libarapi70.a
30
Requirements
To build and run a Java API program on either Windows or UNIX, you need the following environment components:
!
All C API libraries and DLLs, as listed in the C API package contents on page 24. J2SE Software Development Kit (SDK), version 1.4.2 or higher. Windows dynamic link library (DLL) files or UNIX library files as listed in Table 2-4.
! !
Library files
Table 2-4 lists the Java API library files that are installed with the BMC Atrium CMDB application.
Table 2-4: Java API library files
Platform Windows
Files
arapi70.jar arutil70.jar arjni70.dll cmdbapi20.jar cmdbjni20.dll
Solaris
HP-UX
31
Platform AIX
Files
libarapi70.jar libarutil70.jar libarjni70.jar libcmdbapi20.a libcmdbjni20.a
Linux
Header files
Table 2-5 lists the header files that are installed with the Java API.
Table 2-5: Header files for the CMDB programs
Description AR System API functions CMDB API functions Java utilities library
32
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.
! !
C API functions, data structures, and constants C API library and header files
! osdriver.exe !
Java API namespaces, packages, classes, methods, functions, variables, and constants Java and JNI library and header files Javadoc directory and files
! !
This guide and the Java API Help use only the new names for these objects. The old names are deprecated, and will not work for the 2.0 release of the BMC Atrium CMDB.
33
Functions affected CMDBGetInstance CMDBGetListInstance CMDBGetMultipleInstance CMDBGetInstanceBLOB CMDBGraphQuery CMDBCreateClass CMDBSetClass CMDBGetClass CMDBCreateInstance CMDBSetInstance CMDBGetInstance CMDBGetListInstance CMDBGetMultipleInstance CMDBDeleteInstance CMDBGetInstanceBLOB CMDBGetRelatedFederatedInContext CMDBActivateFederatedInContext CMDBGraphQuery CMDBGetCopyAuditData CMDBGetLogAuditData CMDBGetUIComponents
Description The getMask parameter specifies that the function should manipulate the data in the overlay datasets.
auditInfo
The auditInfo parameter specifies the audit information for the CI class. The datasetId parameter specifies the dataset that the function should use.
datasetId
34
Data structure added CMDBUIComponentResult (New) CMDBUIComponentInfo (New) CMDBUIComponentResultList (New) CMDBVersionInfo (New) CMDBVersionInfoList (New) CMDBREJobRunInfoStruct (New) CMDBREJobRunInfoList (New) CMDBFederatedARInfo (New) CMDBFederatedActiveInfo (New) CMDBAuditValueList (New) CMDBAuditValueListList (New) CMDBAuditInfoStruct (New) CMDBREClassQualList (New)
Functions affected CMDBGetCMDBUIComponents CMDBGetCMDBUIComponents CMDBGetCMDBUIComponents CMDBGetVersions CMDBGetVersions CMDBGetJobRun CMDBGetListJobRun CMDBActivateFederatedInContext CMDBActivateFederatedInContext CMDBGetCopyAuditData CMDBGetCopyAuditData
Description Holds component result information. Holds component information. Holds a list of component results. Holds the BMC Atrium CMDB version information. Holds a list of BMC Atrium CMDB version information. Holds job run information. Holds job run information. Holds the federated AR System information. Holds federation information. Holds audit values. Holds a list of audit values in audit functions.
CMDBCreateClass, CMDBSetClass, Holds audit information. CMDBGetClass CMDBStartJobRun Holds a list of qualifications for the class when running a job with qualification substitution.
35
BMC Atrium CMDB 2.0.1 Table 2-7: API data structure changes
Description Holds the substitute and original datasets when running a job with dataset substitution. Holds a list of
CMDBREDatasetPair
CMDBREDatasetList
CMDBStartJobRun
36
Chapter
Java program requirements (page 38) Working with configuration item classes and instances (page 38) Working with relationship classes and instances (page 44)
37
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";
38
In the example, the phoneSystemClassNameKey and socketClassNameKey class variables hold the class name and namespace definitions for the phoneSystem and Socket classes respectively. The classNameKey class variables are passed as parameters to the constructor of the CMDBClass class. A class ID is an identification string that uniquely identifies a particular class within the BMC Atrium CMDB. In the try loop, the phoneSystemClass and socketClass classes are created in the BMC Atrium CMDB. The currentUser parameter is a pre-instantiated ARServerUser class that has valid user login credentials. For more information about the parameters for the CMDBCreateClass function, open index.html of the Java API Help, which is located in the sdk/ doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
39
40
In the example, the serialNumAttrName, serialNumFieldId, and serialNumEntryMode variables are created to hold the attribute name, attribute field ID, and the entry mode for the attribute, respectively. When you specify the Required entry mode for an attribute, you must provide a value for this attribute for every instance of the class. The field ID is a unique numeric identifier for an attribute. The data type and limit for the attribute is defined using the serialNumLimit class variable, which is of type CMDBAttributeLimit class. In the example, the serialNumAttr attribute is defined as a character data type with a limit of 30 characters. A default value of Null is specified for the attribute in the serialNumDefaultValue variable. This value is used if no value is provided for the ACMESerialNumber attribute when creating an instance. After these values are defined for the variables, they are passed as parameters to the CMDBAttribute class constructor, which creates a Java instance of the attribute. In the example, the Cost attribute is created to hold the cost information for the phoneSystemClass class. Similar to the ACMESerialNumber definition, the attribute name, field ID, entry mode, and attribute limit details are specified for the Cost attribute. The entry mode for the Cost attribute is defined as Optional. The attribute data type is defined as Currency. After the attributes for a specific class are defined as CMDBAttribute variables, these attributes are added to a hash map. These hash maps can hold multiple attributes at a time. The setAttributes method of the phoneSystemClass is used to set the attributes for the class. The hash map array, which holds the attribute definitions, is passed to this setAttributes method as a parameter. After the attributes are set in the class, the class information is updated in the BMC Atrium CMDB using the update method of the phoneSystemClass. For more information about the setAttributes method of the CMDBClass Java class, data types, and data limits, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
41
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.
42
After the attribute name and other attribute information is created as explained in the previous section, the serialNumAttrName and serialNum variables are assigned to the serialNumAttrValue variable, which is of type CMDBAttributeValue. The costAttrValue class variable holds the costAttrName and cost details for the instance. Using a hash map, the serial number and cost details are added to the
phoneInstance instance, which is of type CMDBInstance. To create the new instance in Java, the phoneSystemClassNameKey, which was shown in Creating a CI class on page 38, and attributeHashMap variables are passed
as parameters to the instance. Before creating the phoneInstance instance in the BMC Atrium CMDB, a dataset variable is created to specify the dataset to which the instance belongs. In the example, the acmeDatasetId variable is created that holds the dataset details. Because an instance must reside in a dataset, you must specify a dataset ID for the instance. In the try loop, the phoneInstance instance is created in the BMC Atrium CMDB. The currentUser and datasetId parameters are passed to the create method of the instance. After the instance is created in the BMC Atrium CMDB, the instance ID of the new instance is retrieved using the getId method. For more information about the parameters for the create method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
43
44
In the example, the relationshipClassName variable is created to hold the name of the relationship class. The relationshipClassKey variable, which is of type CMDBClassNameKey, is created to define the class name and namespace details for the relationship class. The class name and namespace information for the two classes that will be related in the relationship class is specified in the relationshipClasses variable. The role names for the two classes are specified in the roleNames variable. Each of the two classes in a relationship must have its role defined. You can define role names for Class 1 and Class 2, known respectively as the source and destination members of the relationship. The BMC Atrium CMDB prepends these role names to the attributes of a relationship class that pertain to its members. For example, on any CDM relationship class the attributes that hold the class IDs of its member CIs are named Source.ClassId and Destination.ClassId. After the role name and class name key details are defined, the phoneSystemToSocketRelClass Java instance of the relationship class is created, which of type CMDBRelationship. The setCardinality method of the CMDBRelationship class sets the cardinality. In this example, the cardinality for the relationship class is set to one-to-many. A one-to-many cardinality means that for each instance of the phoneSystem class, there can be many relationships to instances of the socket class. In the try loop, the phoneSystemToSocketRelationship relationship class is then created in the BMC Atrium CMDB. For more information about the parameters for the create method of the CMDBRelationship Java class, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
45
46
In the example, the phoneInstId and socketInstId variables are created to hold the instance IDs of the newPhoneSystem and newSocket instances. The srcInstId and destInstId variables are created to hold the IDs of the source and destination classes, which are phoneInstId and socketInstId respectively. The datasetId variable holds the dataset ID of the ACME dataset. These source, destination, and dataset ID variables are written to the attrHashMap array. The Java instance of the relationship class is then created using the constructor of the CMDBInstance class. In the try loop, the relationship instance is created in the BMC Atrium CMDB. The getARServerUser method of the relInstance instance retrieves the user ID that is currently used to log in to the AR System server. The user ID parameter is required to create the instance in the BMC Atrium CMDB. For more information about the parameters for the create method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
47
In the example, the attributes to retrieve in the query are specified in the attributesToGet array of type String. The query in this example retrieves the InstanceID, ReconciliationIdentity, and DatasetID attributes from all instances. If no attributes are specified to return in the query, all attributes of the instances will be returned by default. The query variable specifies a qualification that will retrieve all instances where the dataset ID is ACME.DATASET. In the try loop, the findObjects method of the CMDBInstance Java class is used to retrieve instances. The retrieved instances are placed in the instanceList array, which is of type CMDBInstance. For more information about the parameters for the findObjects method of the CMDBInstance Java class, open index.html of the Java API Help, which is located in the sdk/doc/javadoc/cmdbapi/ subdirectory of your CMDB installation directory.
48
Chapter
This chapter describes how to use the various BMC Atrium CMDB tools. The following topics are provided:
! ! ! ! ! ! ! ! !
Working with the cmdbdriver program (page 50) Migrating data between BMC Atrium CMDB servers (page 53) Using the extension loader (page 61) Integrating the CI Relationship Viewer with other applications (page 70) Configuring the CI Relationship Viewer (page 77) Creating CMDB status alerts (page 85) Importing data with EIE (page 86) Working with SQL views (page 87) Debugging BMC Atrium CMDB API programs (page 88)
49
platform:
!
Windows
!
! !
UNIX
! !
50
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.
51
Using a script
You can also use a script file that contains the cmdbdriver commands and execute it at the cmdbdriver prompt. You can create this script file using any text editor, such as Notepad or Wordpad. Example: cmdbdriver script file
imp 1 BMC.CORE BMC_BASEELEMENT
This example uses a script to import the BMC_BASEELEMENTclass from the BMC.CORE namespace. To accept a default value for a parameter in the cmdbdriver script, insert a blank line. The last line of the example accepts the default value for the Metadata, Instance data <1-2> parameter. The default for this parameter is set to 1 (metadata). You can use the rec and srec commands of the cmdbdriver program to record cmdbdriver commands. The rec command starts recording the commands you use at the prompt and srec stops recording these commands. When you type the rec command, you are prompted for the name of the file in which to store these commands. After you record the commands in a file, you can execute it at the cmdbdriver program using the execute command.
52
Migrating the BMC Atrium CMDB in such cases requires additional steps beyond migrating a base installation of the BMC Atrium CMDB. Those steps are not covered in this section. See the documentation and white papers for your applications to find the appropriate migration instructions. Migrating your BMC Atrium CMDB from a development server to a production server requires the following high-level steps:
Step 1 Export class data with cmdbdriver (see page 55). Step 2 Export instance data with cmdbdriver (see page 56). Step 3 Import class data with cmdbdriver (see page 57). Step 4 Import instance data with cmdbdriver (see page 58). Step 5 Export reconciliation information with BMC Remedy User (see page 59). Step 6 Import reconciliation information with BMC Remedy Import (see
page 60). For information about known issues regarding the procedure explained in this section, see Known issues on page 61. You can use cmdbdriver scripts to perform some of these steps.
53
platform:
!
Windows
!
! !
UNIX
! !
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.
54
For more information about logging in to the cmdbdriver program, see Logging in to the cmdbdriver program on page 54.
3 Type the xexpdf command to export all class definitions from the BMC
Atrium CMDB.
4 Specify the file name in which to store the exported definitions.
Make sure you specify the exact path for the file name, for example, c:\ExportedClassDefinitions. If you specify a file name that already exists, the contents of the file will be overwritten.
5 At the Export Classes prompt, type 1 to export all classes and their
subclasses. The definitions for the classes and their subclasses are saved to the specified directory as XML files. To export definitions for a specific class, type 2 at the Export Classes prompt. When you type option 2, you will be prompted for additional parameters.
55
For more information about starting the cmdbdriver program, see Logging in to the cmdbdriver program on page 54.
3 Type the xexpdt command to export instance data from the BMC Atrium
CMDB.
4 Type the file name in which to store the exported instance data.
Make sure you specify the exact path for the file name, for example, c:\ExportedInstanceData. If you specify a file name that already exists, the contents of the file will be overwritten.
5 At the Export Instances from prompt, type 1 to export instance data for
all classes and their subclasses. To export instance data for a specific class, type 2 at the Export Instances from prompt. When you type option 2, you will be prompted for additional parameters.
6 At the Dataset ID prompt, type the dataset ID from which to export the
instance data.
Tip: If you export all your instance data to the same directory, it can later be imported in one step.
The instance data for the classes is saved to the specified directory as an XML file.
56
For more information about logging in to the cmdbdriver program, see Logging in to the cmdbdriver program on page 54.
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.
(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,
57
For more information about logging in to the cmdbdriver program, see Logging in to the cmdbdriver program on page 54.
3 Type the impdt command to import instance data into the BMC Atrium
CMDB.
4 Type any of the following import options to specify the action to take when
an instance to be imported has the same InstanceId as an existing instance in the BMC Atrium CMDB:
! 1 (Error)Write
an error message and do not import the instance. the existing data for a given
instance.
! 3 (Merge)
Merge the new instance and the existing instance. a new ID for every duplicate instance.
5 Type the directory path where the import data is located, for example,
c:\ExportedInstanceData.
58
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.
! !
59
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 59. If you include no path or a relative path, the file is placed in or under the BMC Remedy User application folder.
6 Click Export.
other AR System clients are installed. The default directory is c:\Program Files\AR System.
60
For <import_file>, specify the full path to the file containing the exported definitions from the procedure To export reconciliation definitions on page 59. Specifying a log file is optional, but recommended in case there are any errors with the import, such as existing data with duplicate entry IDs.
Known issues
These issues can occur when performing the migration procedures in this section.
!
When exporting or importing instances for a categorization class, data from its superclass is also exported or imported. This is because a categorization class stores its instance data on the same AR System form as its superclass. When you attempt to export instance data from an abstract class, cmdbdriver crashes. There is no reason to do this, since abstract classes cannot have any instances. When importing the weak member in a weak relationship, you will receive an error if that instance already exists. You must delete the existing weak member before you can import it.
61
At the top level is the directory where you copy the extension loader files, for example, CMDBExtensionLoader. Under the CMDBExtensionLoader directory is the common folder, and two cmdbExtLoader executables, one each for UNIX (no extension) and Windows (.exe).
Note: You must name the directory that contains the extension subdirectories as extensions. If you specify any other name for this directory, the extension loader will not recognize it.
After you copy the extension loader files into the extension loader directory you created, you create an extensions directory, as displayed in Figure 4-2. The extensions directory can contain one or more extension subdirectories. Each extension subdirectory contains a package.xml file, an installation activity file, and one or more class XML files. These class files are obtained when you use the expdf command of the cmdbdriver program to export the class or attribute definitions.
62
extensions directory in ascending order. Therefore, you must specify a lower <install-order> for the object that you want to install first. For example, if you have two extension subdirectories, 650-EXClass and 655-EXClass, the 650-EXClass subdirectory will be installed first.
! <name> is an alphanumeric name for the extension. Make sure you do not
use spaces, quotation marks, or wildcard characters in the <name> element. Examples of extension subdirectory names are 500-EXClass and 501-EXAtt.
63
See The extension loader directory structure on page 62. This directory will contain all the extension loader files.
2 Export the class definitions using the cmdbdriver expdf command.
For more information about exporting class definitions with the cmdbdriver program, see Step 1Exporting class data with cmdbdriver on page 55. The expdf command creates several XML files that contain the class definition information for the specified class.
64
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.0</minversion> </cmdb> </applications> </dependencies> </package>
This package.xml example instructs the extension loader program to install the ComSys Hardware Component class extension version 1.0 on the BMC Atrium CMDB application version 2.0. The first line of code is an xml version tag that is required for all XML files.
Note: When you specify a GUID for the BMC Atrium CMDB dependency in your package.xml file, make sure you use the same GUID as shown in the example. This is the GUID stored in the SHARE:Application_Properties AR System form for the BMC Atrium CMDB.
If you are creating a new extension, generate a GUID using the cg command of the cmdbdriver program. For more information about using the cmdbdriver program, see Logging in to the cmdbdriver program on page 54. If you are modifying an existing extension, skip to step 2.
65
GUID for the extension. For new extensions, specify the GUID that you created in step 1. For existing extensions, specify the currently existing GUID.
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
66
<install-order> is a three-digit number 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 655-EXClass, the 650-EXClass subdirectory will be installed first. <name> is an alphanumeric name for the extension. Do not use spaces, quotation marks, or wildcard characters in the <name> element. <type> instructs the extension loader to perform an action based on a specific value. The options for the <type> parameter include:
! ! ! !
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.
Using the extension loader 67
//activity type // Number of class or instance defintions to import // Class name // Namespace // metadata or instance data choice. 1 indicates metdata.
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.
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.
68
4 Specify the number of class definitions or instance data objects you want to
export or import.
5 Specify the class name and namespace for the OSD activity. 6 Specify if you want to export or import the metadata or instance data.
You can use the cmdbdriver program for the import and export function parameters. For more information about the cmdbdriver program, see Working with the cmdbdriver program.
7 Save the activity file under the extension subdirectory you created in step 1
with an xml, txt, or any other type of extension, depending on the activity type. For more information about the activity file extensions, see Step 3Create an installation activity file on page 67. The Extensions subdirectories will now contain a package.xml file, an installation activity file, and the XML files, which were created when you exported your classes using the cmdbdriver program.
From the directory in which you installed the extension loader program, start the cmdbExtLoader program using the following steps, based on your platform:
! !
The extension loader installation wizard appears, which guides you through the installation process. After you complete the installation, your extensions are installed in the BMC Atrium CMDB.
69
AR System applications
!
Launch the CI Relationship Viewer form from AR System applications. This is a quick and easy way to integrate the CI Relationship Viewer with your AR System application. In this method, you can launch the CI Relationship Viewer form, which is installed within the CMDB, using AR System workflow (see page 71). Embed CI Relationship Viewer in AR System applications. In this method, the CI Relationship Viewer field is embedded in the AR System application itself (see page 73).
Launching the CI Relationship Viewer from non-AR System applications. In this method, you can launch the CI Relationship Viewer directly using a browser. (see page 75).
70
Description The namespace to which the instance belongs. The class name to which the instance belongs. The Instance ID of the CI for which the relationship data will be displayed. The ID of the dataset where the instance resides. 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.
server and create a new active link for launching the CI Relationship Viewer. The properties for the active link are displayed in a tab form. For more information about creating active links, see the BMC Remedy Action Request System 7.0: Workflow Objects guide.
2 On the Basic tab, specify details, such as the Form Name and Execute On
criteria.
71
BMC Atrium CMDB 2.0.1 Figure 4-3: Setting CI Relationship Viewer parameters
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.
72
From the Form Name list, select CMDB:CIViewer. In the Field Mapping section, specify the parameters listed in Table 4-1 on page 71.
4 Click Add Action. 5 On the Permissions tab, specify permissions for the active link. 6 On the BMC Remedy Administrator toolbar, click the Save icon.
Note: The CI Viewer value in the Module type list does not appear if you have not installed the BMC Atrium CMDB application on your system.
!
From the Definition Name list, select the data visualization definition you created for the CI Viewer.
Select Default if you did not create any customized definitions. For more information about creating definitions, see Creating a definition for the CI Relationship Viewer on page 82.
4 On the Database tab, specify a name for the Data Visualization field in the
73
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:
!
Specify a name for the active link. From the Form Name list, select the form name.
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.
74
Field ID
F49000110f0 F400109900 F431400000
Description The namespace to which the instance belongs. The class name to which the instance belongs. The Instance ID of the CI for which the relationship data will be displayed. The dataset from where the instance data will be selected. 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.
F431400001 F431400003
75
Make sure that you specify appropriate values for placeholders, such as <mid tier>, <arserver>, <namespace>, <classname>, <ciid>, <datasetid>, and <filtername>.
2 Press Enter.
76
Creating a configuration file on page 78 Creating a definition for the CI Relationship Viewer on page 82
77
Where:
! idUniquely ! 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, Finding related CIs using graph queries.
! enabledUsed
to enable or disable the menu item. If you do not define this attribute, the default value of true is accepted.
You can create submenus up to any number of levels. The following example shows a submenu definition: Example: Submenu definition
<submenu id="SUBMENU_ID1" text="sub menu1"> <menuitem id="MNU_ID1" text="item1" action="action1"/> <menuitem id="MNU_ID2" text="item2" action="action2"/> </submenu>
You can create separators between the menu items to apply a context for them. A separator does not have the text and action attributes. The following example shows a menu separator: Example: Menu separator
<menuitem id="MNU_SEPARATOR"/>
78
The CI Relationship Viewer predefines a set of standard menu items for the applications that use the viewer. Table 4-3 lists the menu or submenu items of the CI Relationship Viewer along with their functions.
Note: The menu items listed in Table 4-3 are displayed in the context menu by default. To hide any of submenus in the context menu pop-up, modify the config.xml file or create a custom configuration file.
Table 4-3: Menu items and their functions
Action value
MNU_SET_AS_ROOT MNU_SEPARATOR MNU_LAYOUT_TREE MNU_LAYOUT_RADIAL MNU_SHOW_LEGEND MNU_REFRESH SUBMENU_LAYOUT SUBMENU_LAUNCH
Function Sets the currently selected CI as root Separator Tree Layout Radial Layout Show/Hide Legend Refreshes the Relationship Graph Submenu for showing the layouts Submenu for showing the items for Launch in Context
Text displayed in the CI Relationship Viewer Set as Root A line Tree Radial Show/Hide legend Refresh Layout Launch in Context
SUBMENU_LAUNCH is a special menu type that is used for adding menu items for launching federated data in context. If a SUBMENU_LAUNCH menu item is
included in the configuration file, menu items for all applicable federated interfaces are automatically displayed. The default option for the Launch in Context submenu in the CI Relationship Viewer is CI Viewer, which launches the CI Relationship Viewer in a browser. The SUBMENU_LAUNCH submenu will appear disabled in the CI Relationship Viewer if there are no CIs that are selected on the CI Relationship Viewer map.
Note: Do not add any menu items for the SUBMENU_LAUNCH menu option in the configuration file. Based on the federation definitions, the menu items will be dynamically added to SUBMENU_LAUNCH at run time.
79
The configuration, style, and context menu information must be placed within the <config>, <style>, <contextmenu> element tags respectively. Table 4-4 explains the various style attributes for the CI Relationship Viewer context menu.
Table 4-4: Context menu style attributes.
Description The font size for the CI labels. The default icon size for CI representation. The color for the links. When used in the link element, it represents the default color. The width of the link. When used in the link element, it represents the default width. The text to display in the legend.
width
text
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.
80
When you create a configuration file with the code explained in the config.xml example, the context menu shown in Figure 4-5 is displayed in the CI Relationship Viewer.
Figure 4-5: CI Relationship Viewer context Menu
81
Search mode.
2 Click Search on the form toolbar.
All existing Data Visualization Definition entries are listed in the results pane, as displayed in Figure 4-6 on page 83.
82
3 In the results pane, select the entry with a Definition Name of Default.
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.
83
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.
84
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.
85
When you transfer data into the BMC Atrium CMDB, a database table and its columns from the third-party data source are mapped to a BMC Atrium CMDB class and its attributes respectively. In general, this relationship is many-to-many because you can map different columns from different data sources to different attributes in the same BMC Atrium CMDB class. For more information about EIE data transfer between a third-party data source and the BMC Atrium CMDB, see the BMC Remedy Enterprise Integration Engine 7.0 Administrators Guide.
86
Alphabetic and numeric characters remain as defined. Colons and other special characters are replaced by underscores. For example, the SQL view for the BMC.CORE:BMC_BaseElement form is named BMC.CORE_BMC_BaseElement. A leading A is appended to all view names that do not begin with an alphanumeric character. If the name contains a database reserved word, the string _x is appended to the name. View names are limited to 30 characters. When a form name exceeds the 30 character limit, the corresponding view name is truncated to 27 or 28 characters. A schema ID is appended to the view name to differentiate between any other view that was truncated to the same string. Because schema IDs vary from one system to another, these view names cannot be formulated in advance. For example, the view of the BMC.CORE.CONFIG:BMC_ConfigBaseRelationship form might be named BMC_CORE_CONFIG_BMC_ConfigB131 or
BMC_CORE_CONFIG_BMC_Config2131e
Abstract classes do not store any data. Therefore, abstract classes do not have corresponding views.
For more information about SQL views and table naming conventions, see the BMC Remedy Action Request System 7.0: Database Reference guide.
87
To disable logging, set this parameter to F. Each entry in the log provides the following details:
! ! !
TimestampThe date and time of the log entry. Log TypeThe type of log entry such as warning, error, or information. MessageThe message for the log entry.
You can specify additional parameters for the logging option in the ar.cfg or ar.conf configuration file depending on your platform. However, you can only add these parameters after you set the CMDB-Debug-Flag parameter to true (T).
! CMDB-Debug-LevelSpecifies
the level of logging you require for your API calls. These levels determine the type of messages that are logged for the calls. The various debug levels include:
! !
88
All these logging levels are inclusive of their preceding levels. For example, if you set the debug level at 3, you will receive log messages for levels 1, 2, and 3. The default value for CMDB-Debug-level parameter is set to 3. An example for this parameter is, CMDB-Debug-Level: 2.
! CMDB-Log-File-LocationEnables
you to specify the directory location on your system where the log file will be written. You can specify any location on your system for the log files. By default, the log file is written to the Db directory of the AR System server. you to specify a maximum size for your log file. The size of the log file is specified in kilobytes (KB). When the log file reaches the specified limit, the system automatically creates a backup of the log file and stores the log entries in a new log file. The default value for the CMDB-Max-Log-File-Size parameter is set to 0, which specifies an unlimited size for the log file. An example of this parameter is, CMDB-Max-Log-File-Size: 50000.
! CMDB-Max-Log-File-SizeEnables
89
90
Section
II
API reference
This section provides reference information for the C and web services APIs. The Java API documentation is available in the Javadoc HTML files. This section is organized into the following chapters:
!
Chapter 5, C API functions and data structures, provides information about the functions and the data structures used in the C APIs. Chapter 6, Web services API operations and data structures, provides information about the operations and data structures used in the web services APIs. Chapter 7, Error messages, provides all CMDB error messages with their descriptions.
API reference
91
92
Chapter
Related files (page 94) Deprecated objects (page 94) Functions (page 95) Data structures (page 182)
93
Related files
The cmdb.h and cmdbfree.h files contain the C API function definitions. For a complete list of header files required for the BMC Atrium CMDB, see Chapter 2, Header files.
Deprecated objects
In version 2.0 of the BMC Atrium CMDB, the following functions and data structures are deprecated:
Deprecated functions
The deprecated C API functions for the BMC Atrium CMDB include:
! !
In these export and import functions, you pass a parameter to specify whether you want to export or import class definitions or instance data. In version 2.0, the following functions are available to export or import class definitions or instance data:
!
CMDBExportDefExports class definitions to a specified directory in a given format. CMDBExportDataExports instance data to a specified directory in a given format. CMDBImportDefImports a list of specified class definitions. CMDBImportDataImports the specific instance data.
! !
94
CMDBExportItem (page 200) FreeCMDBExportItemList (page 162) FreeCMDBExportItemStruct (page 161) CMDBImportItem (page 202) CMDBImportItemList (page 203)
Functions
The CMDB C API functions are categorized by the type of actions these functions perform. The function categories include data model, instance, and general purpose functions, such as session, authentication, and import or export definition functions.
Note: In the C API function descriptions, the usage of the term specified for a given parameter denotes that the parameter is listed under the Synopsis heading of the API function.
CMDBCreateAttribute (page 96) CMDBCreateMultipleAttribute (page 100) CMDBDeleteAttribute (page 103) CMDBGetAttribute (page 104) CMDBGetMultipleAttribute (page 107) CMDBSetAttribute (page 111) CMDBSetMultipleAttribute (page 113) CMDBCreateClass (page 116) CMDBDeleteClass (page 119)
Functions 95
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( ARControlStruct CMDBClassNameId ARNameType ARNameType unsigned int ARInternalId unsigned int CMDBAttributeLimit ARValueStruct ARPropList ARPropList ARStatusList *control, classNameID, attributeName, attributeId, dataType, *arsubclassesId, entryMode, *attributeLimit, *defaultValue, *characList, *customCharacList, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID
The name of the class for which you want to create an attribute. It is a twopart structure that contains the namespace and the classname. The name of the class must be unique.
96
attributeName
The name of the attribute to create. The name of the attribute must be unique within the specified class and within its superclasses and subclasses.
attributeID
The ID of the attribute to create.
dataType
The datatype of the attribute to create. 1: Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD)
2: Integer (CMDB_ATTR_DATA_TYPE_INTEGER) 3: Real (CMDB_ATTR_DATA_TYPE_REAL) 4: Character (CMDB_ATTR_DATA_TYPE_CHAR) 5: Diary (CMDB_ATTR_DATA_TYPE_DIARY) 6: Selection (CMDB_ATTR_DATA_TYPE_ENUM) 7: Time (CMDB_ATTR_DATA_TYPE_TIME) 10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL) 11: Attachment (CMDB_ATTR_DATA_TYPE_ATTACH) 12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY) 13: Date (CMDB_ATTR_DATA_TYPE_DATE) 14: Time of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY) 37:
arsubclassesId
The AR System subclasses ID of the attribute to create. The IDs of all attributes must be unique within the class. Specify 0 for this parameter if you want the system to generate the ID.
Functions
97
entryMode
The entry mode for the attribute. Entry mode can be set to any one of the following: required, optional, or display only.
1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED). 2:
Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL).
4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
attributeLimit
The value limits for the attribute and other properties specific to the 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.
1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). When querying for attributes, you will see all attributes including the hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5. 2: Users can specify a list of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
98
Developers Reference Guide 3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). This setting marks the atribute as hidden for
a group or a role. When querying for classes, you can retrieve hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3.
5:
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is <leadclassID>|<lead attribute>.
6: CMDB_ATTR_CHARAC_CREATE_MODE 7:Users can set the audit option on to store the audit history for the attribute. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can set the description for the attribute. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacList
A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX). After the properties list structure you specify is serialized, it is converted into the <list_size><prop_id><data_type><prop_value> format, where:
<list_size>: The number of items in the properties list. <prop_id>: The ID for the property, which is within the 300000 - 399999
range.
<data_type>: The data type for the property, which can be of any native data
type.
<prop_value>: The value for the property.
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
Functions
99
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( ARControlStruct CMDBClassNameId ARNameList ARNameList ARUnsignedIntList ARInternalIdList ARUnsignedIntList CMDBAttributeLimitList ARValueList ARPropListList ARPropListList ARStatusList *control, *classNameID, *attributeNameList, *attributeIdList, *dataTypeList, *arsubclassesIdList, *entryModeList, *attributeLimitList, *defaultValueList, *characListList, *customCharacListList, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID
The name of the class 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.
100
dataTypeList
The list of data types for the attributes being created.
arsubclassesIdList
The AR System subclasses IDs of the attributes being created.
entryModeList
The list of entry modes for the attributes being created. Options include display only, required, and optional.
1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED). 2:
Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL).
4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
attributeLimitList
The list of value limits for the attributes being created and other properties specific to the attributes types. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute list you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the limits and properties for the attribute list.
defaultValueList
The list of values to apply if a user submits an entry with no value for the attributes being created. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. Specify NULL if you do not want to specify a default value.
characListList
A list of characteristics for each attribute. Characteristics include View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description.
1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).When querying for attributes, you will see all attributes, including the hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5.
Functions
101
Users can specify a list of groups or roles that have permissions to view and modify the characteristics of the attribute
(CMDB_ATTR_CHARAC_CHANGE_PERMS). 3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). 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.
5:
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is <leadclassID>|<lead attribute>.
6: CMDB_ATTR_CHARAC_CREATE_MODE 7:Users can set the audit option on to store the audit history for the attribute. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can set descriptions for the attributes. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacListList
A list of user-defined custom characteristics list for each attribute. The value can be set to any user-defined characteristic but must be in the range between 300000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 399999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this attribute. After the properties list structure you specify is serialized, it is converted into the <list_size><prop_id><data_type><prop_value> format, where:
<list_size>: The number of items in the properties list. <prop_id>: The ID for the property, which is within the 300000 - 399999
range.
<data_type>: The data type for the property, which can be of any native data
type.
<prop_value>: The value for the property.
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
102
CMDBDeleteAttribute
Description Deletes the attribute with the specified ID. Depending on the value you specify for the deleteOption parameter, the attribute is deleted immediately and is not returned to users who request information about attributes. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBDeleteAttribute( ARControlStruct CMDBClassNameId ARNameType unsigned int ARStatusList *control, classNameID, attributeName, deleteOption, *status)
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID
The name of the class from which to delete the attribute.
attributeName
The name of the attribute to delete.
deleteOption
A value indicating the action to take if the specified attribute contains data.
0: Do not delete the attribute (AR_ATTRIBUTE_CLEAN_DELETE). 1: Delete if the attribute contains data but not if it is inherited by subclasses (AR_ATTRIBUTE_DATA_DELETE). 2: Delete the attribute even if it has subclasses that are associated with it (AR_ATTRIBUTE_FORCE_DELETE).
Functions
103
Return values
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 CMDBClassNameId ARNameType ARNameType unsigned int unsigned int CMDBClassNameId ARInternalId unsigned int CMDBAttributeLimit ARValueStruct ARPropList ARPropList ARStatusList *control, *classNameId, attributeName, attributeId, *dataType, *attributeType, *baseClassNameId, *arsubclassesId, *entryMode, *attributeLimit, *defaultValue, *characList, *customCharacList, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The name of the class. 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.
104 Chapter 5C API functions and data structures
Return values
attributeId
The ID of the attribute.
dataType
The datatype of the attribute.
1:
Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD)
2: Integer (CMDB_ATTR_DATA_TYPE_INTEGER) 3: Real (CMDB_ATTR_DATA_TYPE_REAL) 4: Character (CMDB_ATTR_DATA_TYPE_CHAR) 5: Diary (CMDB_ATTR_DATA_TYPE_DIARY) 6: Selection (CMDB_ATTR_DATA_TYPE_ENUM) 7: Time (CMDB_ATTR_DATA_TYPE_TIME) 10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL) 12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY) 13: Date (CMDB_ATTR_DATA_TYPE_DATE) 14: Time of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY) 37:
attributeType
The type of attribute to retrieve.
1: CMDB_ATTR_TYPE_CORE_INTERNAL 2: CMDB_ATTR_TYPE_CORE 3: CMDB_ATTR_TYPE_REGULAR
baseClassNameId
The name of the class that owns this attribute.
arsubclassesId
The internal ID of the attribute to retrieve.
entryMode
The entry mode for the attribute list. Entry mode can be set to any one of the following: display only, required, optional.
1: CMDB_ATTR_ENTRYMODE_REQUIRED
Functions
105
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 permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). 2: List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
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 a part of the primary key of the class (CMDB_ATTR_CHARAC_PRIMARY_KEY). 5:
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is <leadclassID>|<lead attribute>.
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:
106
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( ARControlStruct CMDBClassNameId ARBoolean ARBoolean ARNameList ARPropList ARBooleanList ARNameList ARNameList ARUnsignedIntList ARUnsignedIntList CMDBClassNameIdList ARInternalIdList ARUnsignedIntList CMDBAttributeLimitList ARValueList ARPropListList ARPropListList ARStatusList *control, *classNameId, getHiddenAttrs, getDerivedAttrs, *nameList, *attrCharacQueryList, *existList, *attributeNameList, *attributeIdList, *dataTypeList, *attributeTypeList, *baseClassNameIdList, *arsubclassesIdList, *entryModeList, *attributeLimitList, *defaultValueList, *characList, *customCharacList, *status)
Functions
107
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 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.
108
baseClassNameIdList
The name of the base class attribute to retrieve.
arsubclassesIdList
The AR System subclasses ID of the attribute.
entryModeList
The entry mode for the attribute list. Options include display only, required, and optional.
1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED ). 2: Users do not have to enter data when the entry mode is set to optional (CMDB_ATTR_ENTRYMODE_OPTIONAL). 4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
attributeLimitList
The value limits for the list of attributes and other properties specific to the attributes type. See CMDBAttributeLimit on page 187 to find the contained structure that applies to the type of attribute you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the attribute limits and properties.
defaultValueList
The value to apply if a user submits an entry with no attribute list value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute.
characList
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 permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS).
List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
2:
Functions
109
The flag value of the Hidden characteristic. If the flag is set to false, users cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN).
4: Specifies whether the attributes are a part of the primary key of the class (CMDB_ATTR_CHARAC_PRIMARY_KEY). 5:
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is <leadclassID>|<lead attribute>.
6: CMDB_ATTR_CHARAC_CREATE_MODE 7:
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:
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.
110
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( ARControlStruct CMDBClassNameId ARNameType ARNameType unsigned int CMDBAttributeLimit ARValueStruct ARPropList ARPropList ARStatusList *control, *classNameId, attributeName, newAttributeName, *entryMode, *attributeLimit, *defaultValue, *characList, *customCharacList, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The name of the class 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.
Functions
111
BMC Atrium CMDB 2.0.1 1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED). 2:
Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL).
4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
attributeLimit
The value limits for the attribute and other properties specific to the 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 the characteristics of the attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). 2: Users can view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS). 3: Users can set the flag to false so they cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN). 5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is <leadclassID>|<lead attribute>. 6: CMDB_ATTR_CHARAC_CREATE_MODE
112
Developers Reference Guide 7:Users can set the audit option on to store the audit history for the attribute. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can set the description 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.
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( ARControlStruct CMDBClassNameId ARNameList ARNameList ARUnsignedIntList CMDBAttributeLimitList ARValueList ARPropListList ARPropListList ARStatusList *control, *classNameId, *attributeNameList, *newAttributeNameList, *entryModeList, *attributeLimitList, *defaultValueList, *characListList, *customCharacListList, *status)
Functions
113
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 for which the attributes need to be set. It is a two-part structure that contains the namespace and the classname.
attributeNameList
The list of attribute names to set.
newAttributeNameList
The list of new names of the attributes. The names of all attributes must be unique within the specified class and within its superclasses and subclasses.
entryModeList
The list of entry modes for the attributes being created. Entry mode can be set to any one of the following modes: display only, required, optional.
1: Users must enter data when the entry mode is set to required (CMDB_ATTR_ENTRYMODE_REQUIRED ). 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).
attributeLimitList
The list of value limits for the attributes being created and other properties specific to the attributes' types. See CMDBAttributeLimit on page 187 to find the contained structure that applies to the type of attribute list you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL for this parameter if you do not want to change the limits and properties for the attribute list.
114
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.
1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). 2: Users can specify a list of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS). 3: Users can set the flag to false so that this attribute is hidden (CMDB_ATTR_CHARAC_HIDDEN). 5:
The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is <leadclassID>|<lead attribute>.
6: CMDB_ATTR_CHARAC_CREATE_MODE 7:User can set the audit option on to store the audit history for the attribute. CMDB_ATTR_CHARAC_AUDIT_OPTION 9:Users can set descriptions of the attributes. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacListList
A list of user-defined custom characteristics list for the attribute. The value can be set to any user-defined characteristic but must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this attribute. 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.
Functions
115
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBCreateClass
Description Creates a class with the core attributes in the OBJSTR:Class. The data model is stored in the OBJSTR:Class form and the attribute information is stored in the OBJSTR:AttributeDefinition form. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateClass( ARControlStruct CMDBClassNameId ARNameType CMDBClassTypeInfo CMDBClassNameId CMDBIndexList CMDBAuditInfoStruct ARPropList ARPropList ARStatusList *control, *classNameID, classID, *classTypeInfo, *superclassNameId, *indexList, *auditInfo, *characList, *customCharacList, *status)
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
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.
116
classTypeInfo
The type of class to create. The information contained in this definition depends on the type of class you specify.
1: Indicates a regular class (CMDB_CLASS_TYPE_REGULAR). 2: Indicates a class of type relationship (CMDB_CLASS_TYPE_RELATIONSHIP).
superclassNameID
The superclass of this class. Specify NULL for this parameter if there is no superclass.
indexList
A list of indexes defined for the class.
auditInfo
The audit information for the class.
characList
A list of characteristics for the class. Specify NULL for this parameter if you do not want to associate characteristics with this class. Used to specify if this is a singleton class. This characteristic is an integer value where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON).
1: 2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the
attribute, you cannot create instances for it. All the attributes are propagated to the subclasses.
3: You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL). 4: 5:
6: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks the class as hidden for
a group or a role. When querying for classes, you can choose to retrieve hidden classes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3.
Functions
117
BMC Atrium CMDB 2.0.1 7: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class as visible for a
group or a role. When querying for classes, you will see all classes, including the hidden classes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5.
8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS 9: CMDB_CLASS_CHARAC_FORM_NAME
customCharacList
A list of user-defined custom characteristics for the class. The ID for each list item can be set to any user-defined characteristic but must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this class. After the properties list structure you specify is serialized, it is converted into the <list_size><prop_id><data_type><prop_value> format, where:
<list_size>: Is the number of items in the properties list. <prop_id>: Is the ID for the property, which is within the 100000 - 199999
range.
<data_type>: Is the data type for the property, which can be of any native
data type.
<prop_value>: Is the value for the property.
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
118
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( ARControlStruct CMDBClassNameId unsigned int ARStatusList *control, *classNameId, deleteOption, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID
The name of the class to delete.
deleteOption
A value indicating the action to take if the specified class contains attributes or subclasses.
0: Delete the class only if the class contains no instances and has no subclasses or dependent relationships (CMDB_DELETE_CLASS_OPTION_NONE). 1: Delete the class only if the class has no subclasses or dependent relationships. This applies only to regular classes (CMDB_DELETE_CLASS_OPTION_WITH_DATA). 2: Delete the class, including all the subclasses and dependent relationship classes that are associated with it. All the dependencies for the specified class are deleted (CMDB_DELETE_CLASS_OPTION_ALL_DEPENDENCIES). This option overrides the CMDB_CLASS_DATA_DELETE option.
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
Functions 119
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( ARControlStruct CMDBClassNameID ARNameType CMDBClassTypeInfo CMDBClassNameId CMDBIndexList CMDBAuditInfoStruct ARPropList ARPropList ARStatusList *control, *classNameId, *classId, *classTypeInfo, *superclassNameId, *indexList, auditInfo, *characList, *customCharacList, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameID
The name of the class. 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.
120
indexList
The list of indexes defined for the class.
auditInfo
The audit information for the class.
characList
A list of characteristics for this class. Specify NULL for this parameter if you do not want to associate characteristics with this class. Used to specify if this is a singleton class. This characteristic is an integer value where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON).
1: 2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the
attribute, you cannot create instances for it. All the attributes are propagated to the subclasses.
3: You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL). 4: 5:
6: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks the class as hidden for
the users in the group. When querying for classes, you can choose to retrieve hidden classes.
7: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class as visible for
the users in the group. When querying for classes, you will see all classes including the hidden classes.
8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS 9: CMDB_CLASS_CHARAC_FORM_NAME
Functions
121
customCharacList
A list of user-defined custom characteristics for the class. The value retrieved must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to retrieve custom characteristics with this class.
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetListClass
Description Retrieves information about relationship classes for a specified class. The classes that are retrieved will have the class that is specified in the classNameIdRelation parameter as part of the relationship. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetListClass( ARControlStruct ARNameType CMDBClassNameId CMDBClassNameId ARPropList ARBoolean CMDBClassNameIdList ARStatusList *control, namespaceName, *classNameIdRelation, *superclassName, *characQueryList, getHiddenClasses, *classNameIdList, *status)
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
namespaceName
The name of the namespace. Namespaces are a way of partitioning your data model to create logical groups of classes. The C API namespaces are implemented using a prefix-based naming convention on classes.
122 Chapter 5C API functions and data structures
classNameIdRelation
Retrieves the relationship classes that have a class specified in this parameter as part of the relationship.
superclassName
Retrieves the classes that are derived from the superclass.
characQueryList
Retrieves all the classes that match the criteria.
getHiddenClasses
Retrieves the hidden classes. Return values
classNameIdList
A list of class names that match the specified criteria.
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBSetClass
Description Sets the class properties in the OBJSTR:Class form. After you create a class, you cannot modify the following properties: classId, classType (regular, relationship), and persistence provider. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetClass( ARControlStruct CMDBClassNameId CMDBClassNameId CMDBClassTypeInfo CMDBIndexList CMDBAuditInfoStruct ARPropList ARPropList ARStatusList *control, *classNameId, *newclassNameId, *classTypeInfo, *indexList, *auditInfo, *characList, *customCharacList, *status)
Privileges Synopsis
Functions
123
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The name of the class. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.
newclassNameId
The new name of the class.
classTypeInfo
Information about the type of class.
indexList
The list of indexes defined for the class. When this parameter is specified, all previously existing indexes are replaced by its contents. If you want to add indexes without losing existing indexes, include the existing indexes in this list.
auditInfo
The audit information for the class.
characList
A list of characteristics for this class. Specify NULL for this parameter if you do not want to associate characteristics with this class. Used to specify if this is a singleton class. This characteristic is an integer value, where type CMDB_CLASS_CHARAC_SINGLETON_FALSE indicates that this is not a singleton class. Type CMDB_CLASS_CHARAC_SINGLETON_TRUE indicates that this is a singleton class (CMDB_CLASS_CHARAC_SINGLETON).
1: 2: This property does not allow you to create instances for this abstract class (CMDB_CLASS_CHARAC_ABSTRACT ). After the property has been set for the
class, you cannot create instances for it. All the attributes are propagated to the subclasses.
3: You cannot create subclasses from this class (CMDB_CLASS_CHARAC_FINAL). 4:
124
6: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_HIDDEN_PERMS). Marks the class as hidden for
the users in the group. When querying for classes, you can choose to retrieve hidden classes.
7: Gives you the permissions to modify the class (CMDB_CLASS_CHARAC_CLASS_VISIBLE_PERMS). Marks the class as visible for
the users in the group. When querying for classes, you will see all classes, including the hidden classes.
8: CMDB_CLASS_CHARAC_CATEGORIZATION_SUBCLASS 9: CMDB_CLASS_CHARAC_FORM_NAME
customCharacList
A list of user-defined custom characteristics for the class. The value can be set to any user-defined characteristic but must be in the range between 100000 (CMDB_CLASS_CUSTOM_CHARAC_MIN) and 199999 (CMDB_CLASS_CUSTOM_CHARAC_MAX). Specify NULL for this parameter if you do not want to associate custom characteristics with this class. In version 2.0 of the BMC Atrium CMDB, the custom characteristic list was overwritten when you specified new values. With version 2.0.1, the new values are appended to the existing list. To delete a custom characteristic, set its datatype to NULL. Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
Functions
125
Instance functions
The C APIfunctions for instance include:
! ! ! ! ! ! !
CMDBCreateInstance (page 126) CMDBDeleteInstance (page 127) CMDBGetInstance (page 129) CMDBGetListInstance (page 130) CMDBGetMultipleInstances (page 132) CMDBGraphQuery (page 135) CMDBSetInstance (page 138)
CMDBCreateInstance
Description Privileges Synopsis Creates a CI or relationship instance in the OBJSTR:Class. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateInstance( ARControlStruct CMDBClassNameId ARNameType CMDBAttributeValueList ARNameType ARStatusList *control, *classNameId, datasetId, *attributeValueList, instanceId, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The name of the class from which the instance is derived. It is a two-part structure that contains the namespace and the classname.
126
datasetId
The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
attributeValueList
A list of one or more subclasses/value pairs (specified in any order) that identifies the data for the new attribute. You must specify values for all required subclasses that do not have defined defaults. Values must be of the data type defined for the subclasses or have a data type of 0. NULL values can be specified for optional subclasses only. An error is generated if a subclasses does not exist or the user specified by the control parameter does not have write permission for a subclasses. Return values
instanceId
The unique identifier for the new attribute (system-generated).
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBDeleteInstance
Description Privileges Synopsis Deletes the instance of the class. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBDeleteInstance( ARControlStruct CMDBClassNameId ARNameType ARNameType unsigned int ARStatusList *control, *classNameId, datasetId, instanceId, deleteOption, *status)
Functions
127
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 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.
instanceId
The unique identifier for the instance (system-generated).
deleteOption
0: Allows you to delete only the specified instance when the instance can be retrieved (CMDB_DERIVED_DELOPTION_NONE). 1: Allows you to delete the instance even when the instance cannot be retrieved (CMDB_DERIVED_DELOPTION_FORCE). Errors will be ignored for instances that do not exist.
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
128
CMDBGetInstance
Description Privileges Synopsis Retrieves information about the instance. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetInstance( ARControlStruct CMDBClassNameId ARNameType usigned int ARNameType ARNameList CMDBAttributeValueList ARStatusList *control, *classNameId, datasetId, getMask, instanceId, *attributeGetList, *attributeValueList, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The name of the class. 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
Functions
129
instanceId
The unique identifier for the instance to retrieve.
attributeGetList
The list of attributes to retrieve. Return values
attributeValueList
The list of attribute ID and value pairs for the instance.
status
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( ARControlStruct CMDBClassNameId ARNameType usigned int CMDBQualifierStruct ARNameList CMDBSortList unsigned int unsigned int ARNameList CMDBAttributeValueListList unsigned int ARStatusList *control, *classNameId, datasetId, getMask, *qualifier, *attributeGetList, *sortList, firstRetrieve, maxRetrieve, *instanceIdList, *attributeValueListList, *numMatches, *status)
130
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.
0: Based on the datasetId being passed, instances are retrieved from either
qualifier
A query that determines the set of entries to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations.
attributeGetList
A list of attribute names to retrieve.
sortList
The sort order for the retrieved data.
firstRetrieve
The first entry to retrieve. CMDB_START_WITH_FIRST_ENTRY represents the first entry to retrieve and is the default value if the value is not set.
maxRetrieve
The maximum number of entries to retrieve. Use this parameter to limit the amount of data returned if the qualification does not narrow the list. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum.
Functions
131
Return values
instanceIdList
The list of instance IDs that match the criteria.
attributeValueListList
A list of the attribute value list.
numMatches
The total number of entries that match the qualification criteria. This value does not represent the number of entries returned unless the number of matching entries is less than or equal to the maxRetrieve value.
status
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( ARControlStruct CMDBClassNameId ARNameType unsigned int ARNameList ARNameList ARBooleanList CMDBAttributeValueListList ARStatusList *control, *classNameId, datasetId, getMask, *instanceIds, *attributeGetList, *existList, *attributeValueListList, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
132
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
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.
Functions
133
CMDBGetInstanceBLOB
Description Privileges Synopsis Retrieves the attachment, or binary large object (BLOB), stored for the attachment subclasses. The BLOB is placed in a file. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetInstanceBLOB( ARControlStruct CMDBClassNameId ARNameType unsigned int ARNameType ARNameType ARLocStruct ARStatusList *control, *classNameId, datasetId, getMask, instanceId, attributeName, *loc, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The name of the class. 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
134
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.
CMDBGraphQuery
Description Privileges Synopsis Searches related instances. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGraphQuery( ARControlStruct CMDBClassNameId ARNameType unsigned int ARNameType ARNameType int int ARBoolean ARBoolean CMDBGraphList CMDBGetObjectList CMDBGetRelationList ARStatusList *control, *startClassNameId, datasetId, getMask, startExtensionId, startInstanceId, numLevels, direction, noMatchProceed, onMatchProceed, *queryGraph, *objects, *relations, *status)
Functions
135
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.
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
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):
136
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. 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.
Functions
137
CMDBSetInstance
Description Privileges Synopsis Sets a CI or relationship instance in the OBJSTR:Class. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetInstance( ARControlStruct CMDBClassNameId ARNameType ARNameType CMDBAttributeValueList ARStatusList *control, *classNameId, datasetId, instanceId, *attributeValueList, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The name of the class. 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).
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.
138
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.
CMDBBeginBulkEntryTransaction
Description Indicates that subsequent API functions are part of the bulk transaction. Any API calls that arrive after this function call are placed in a queue. Data model functions are not part of the bulk transaction. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBBeginBulkEntryTransaction( ARControlStruct ARStatusList *control, *status)
Privileges Synopsis
Input argument
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.
Return value
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
Functions 139
CMDBEndBulkEntryTransaction
Description This function commits or rolls back the bulk transaction, depending on the action type. For an action type of SEND, the API call will be executed as part of the transaction. For an action type of CANCEL, the transaction will be canceled. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBEndBulkEntryTransaction( ARControlStruct unsigned int ARBulkEntryReturnList ARStatusList *control, actionType, *bulkEntryReturnList, *status)
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
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.
140
Environment functions
The C API includes the following environment functions:
! ! ! ! ! !
CMDBInitialization (page 141) CMDBSystemInit (page 142) CMDBSynchMetaData (page 142) CMDBGetServerPort (page 143) CMDBSetServerPort (page 144) CMDBTermination (page 145)
CMDBInitialization
Description Privileges Synopsis Initializes the C API session. 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( ARControlStruct ARStatusList *control, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
Functions
141
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( ARPropList ARStatusList *propList, *status)
Return values
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( ARControlStruct ARNameType CMDBClassNameIdList ARStatusList *control, pendingId, *classNameIdList, *status)
142
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.
pendingId
The ID of the object to be synchronized with the system. Return values
classNameIDList
The list of classes that are successfully synchronized with the system.
status
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( ARControlStruct int int ARStatusList *control, *tcpPort, *rpcPort, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
Return values
tcpPort
Retrieves the CMDB server TCP port information.
Functions
143
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.
CMDBSetServerPort
Description Privileges Synopsis Sets the specified server port. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetServerPort( ARControlStruct int int ARStatusList *control, *tcpPort, *rpcPort, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
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.
144
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBTermination
Description Performs environment-specific cleanup routines and disconnects from the specified session. All API programs that interact with the C API session should call this function upon completing work in a given session. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBTermination( ARControlStruct ARStatusList *control, *status)
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
Functions
145
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 CMDBUIComponentInfo ARNameType CMDBUIComponentResultList ARStatusList
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, 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.
146
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.
CMDBRunQualificationForCI
Description Performs validation on a list of attributes for a specified CI. The CMDBRunQualificationForCI function takes qualification parameters in both structured and encoded modes. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBRunQualificationForCI( ARControlStruct CMDBQualifierStruct CMDBAttributeValueList ARBoolean* ARStatusList
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, 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.
Functions
147
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBExpandParametersForCI
Description 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 char CMDBAttributeValueList char ARStatusList
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, 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.
148
CMDBExport (page 149) CMDBExportDef (page 150) CMDBExportData (page 151) CMDBImport (page 152) CMDBImportDef (page 153) CMDBImportData (page 154)
CMDBExport
Description Privileges Synopsis Exports the specified class definitions from the specified server. This function is deprecated in the 2.0 release of the BMC Atrium CMDB. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBExport( ARControlStruct CMDBExportItemList unsigned int char ARStatusList *control, *exportItemList, exportFormat, *directoryPath, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
exportItemList
The list of items to export.
Functions
149
exportFormat
The format of the export. The default export format is set to
CMDB_EXPORT_FORMAT_XML.
directoryPath
The directory in which the exported file is to be stored. 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( ARControlStruct CMDBExportItemList char ARStatusList *control, *exportItemList, *exportBuf, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
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.
150
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
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 ARQualifierStruct ARNameList CMDBSortList unsigned int unsigned int char ARStatusList
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.
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.
Functions
151
firstRetrieve
The first instance to retrieve. A value of 0 (CMDB_START_WITH_FIRST_INSTANCE)represents the first entry and is the default value if no value is set.
maxRetrieve
The maximum number of instances to retrieve. Use this parameter to limit the instances returned in the query if the qualification does not sufficiently narrow the list. Specify 0 (CMDB_NO_MAX_LIST_RETRIEVE) to assign no maximum instances. Return values
exportBuf
The exported buffer, which contains the class data in an XML format.
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBImport
Description Imports the specified class definitions to the specified server. Use this function to copy structure definitions from one server to another. This function is deprecated in the 2.0 release of the BMC Atrium CMDB. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBImport( ARControlStruct CMDBImportItemList char ARStatusList *control, *importItemList, *directoryPath, *status)
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
152
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.
CMDBImportDef
Description Privileges Synopsis Imports a list of specified class definitions. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBImportDef( ARControlStruct CMDBXMLImportItemList unsigned int char ARStatusList *control, *importItemList, importOption, *importBuf, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
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.
Functions
153
BMC Atrium CMDB 2.0.1 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.
CMDBImportData
Description Privileges Synopsis Imports the specified instance data. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBImportData( ARControlStruct unsigned int char ARStatusList
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.
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).
154
Developers Reference Guide 2: Create an instance with a new instance ID if the instance ID already exists (CMDB_DATA_IMPORT_OPT_NEWID_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.
Utility functions
The utility functions enable you to use CMDB utilities such as export, import, and generate globally unique identifiers (GUIDs). The C API includes the following utility functions:
! !
CMDBCreateGuid
Description Privileges Synopsis Creates a globally unique identifier. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateGuid( ARGuid ARStatusList guid, *status)
Functions
155
Return values
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( ARControlStruct ARNameList ARBooleanList CMDBVersionInfoList ARStatusList *control, *appIdList *existList *versionInfoList *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
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.
156
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
Free functions
The free functions release the memory allocated to a specified function. The C API includes the following free functions:
! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !
FreeCMDBVersionInfoList (page 158) FreeCMDBClassNameIdList (page 158) FreeCMDBAttributeLimit (page 159) FreeCMDBAttributeLimitList (page 160) FreeCMDBAttributeLimitStruct (page 159) FreeCMDBIndexList (page 161) FreeCMDBExportItemStruct (page 161) FreeCMDBExportItemList (page 162) FreeCMDBImportItemList (page 162) FreeCMDBAttributeGetStruct (page 163) FreeCMDBGraphAdjacentStruct (page 164) FreeCMDBGraphAdjacentList (page 164) FreeCMDBGraphStruct (page 165) FreeCMDBGraphList (page 166) FreeCMDBClassTypeInfo (page 166) FreeCMDBQualifierStruct (page 167) FreeCMDBGetRelationList (page 167) FreeCMDBGetObjectList (page 168) FreeCMDBAttributeValueList (page 169) FreeCMDBAttributeValueListList (page 169) FreeCMDBSortList (page 170) FreeCMDBREJobRunInfoList (page 171)
Functions
157
FreeCMDBVersionInfoList
Description Privileges Synopsis Releases the memory space allocated to the CMDBVersionInfoList structure. CMDB Administrator
#include "ar.h" #include "arfree.h" #include "cmdbfree.h" FreeCMDBVersionInfoList( CMDBVersionInfoList ARBoolean *value, freestruct)
Input arguments
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( CMDBClassNameIdList ARBoolean *value, freestruct)
Input arguments
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.
158
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.
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( CMDBAttributeLimit ARBoolean *value, freestruct)
Input arguments
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( CMDBAttributeLimit ARBoolean *value, freestruct)
Functions
159
Input arguments
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.
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( CMDBAttributeLimitList ARBoolean *value, freestruct)
Input arguments
value
A pointer to the CMDBAttributeLimitList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
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.
160
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( CMDBIndexList ARBoolean *value, freestruct)
Input arguments
value
A pointer to the CMDBIndexList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
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.
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( CMDBExportItemStruct ARBoolean *value, freestruct)
Input arguments
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.
Functions
161
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( CMDBExportItemList ARBoolean *value, freestruct)
Input arguments
value
A pointer to the CMDBExportItemList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
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.
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( CMDBImportItemList ARBoolean *value, freestruct)
162
Input arguments
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( CMDBAttributeGetStruct ARBoolean *value, freestruct)
Input arguments
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.
Functions
163
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( CMDBGraphAdjacentStruct ARBoolean *value, freestruct)
Input arguments
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( CMDBGraphAdjacentList ARBoolean *value, freestruct)
164
Input arguments
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.
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( CMDBGraphStruct ARBoolean *value, freestruct)
Input arguments
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.
Functions
165
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( CMDBGraphList ARBoolean *value, freestruct)
Input arguments
value
A pointer to the CMDBGraphList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
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.
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( CMDBClassTypeInfo ARBoolean *value, freestruct)
Input arguments
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.
166
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( CMDBQualifierStruct ARBoolean *value, freestruct)
Input arguments
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.
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( CMDBGetRelationList ARBoolean *value, freestruct)
Functions
167
Input arguments
value
A pointer to the CMDBGetRelationList structure to be released. The system does not perform an operation if the structure contains zero items or if you specify NULL for this parameter.
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( CMDBGetObjectList ARBoolean *value, freestruct)
Input arguments
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.
168
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( CMDBAttributeValueList ARBoolean *value, freestruct)
Input arguments
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( CMDBAttributeValueListList ARBoolean *value, freestruct)
Functions
169
Input arguments
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.
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( CMDBSortList ARBoolean *value, freestruct)
Input arguments
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.
170
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( CMDBREJobRunInfoList ARBoolean *value, freestruct)
Input arguments
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.
Functions
171
CMDBStartJobRun (page 172) CMDBGetJobRun (page 173) CMDBGetListJobRun (page 174) CMDBCancelJobRun (page 175)
CMDBStartJobRun
Description Starts an existing Reconciliation Engine job. Before starting a job, make sure the job is defined and exists in an Active state. If no job for the specified job name exists, or the job is not Active, the CMDBStartJobRun function returns an error. Only one instance of the same job can be executed at a given time. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBStartJobRun( ARControlStruct ARNameType CMDBClassQualList CMDBREDatasetList ARNameType ARStatusList *control, jobName, *classQualList, *datasetList jobRunId, *status)
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
jobName
The name of the reconciliation job.
172
classQualList
The list of class qualifications.
datasetList
The list of Reconciliation Engine dataset pair. 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. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetJobRun( ARControlStruct ARNameType ARREJobRunInfoStruct char ARStatusList *control, jobRunId, *jobRunInfo, **jobRunLog *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
jobRunId
A unique job identifier.
Functions
173
Return values
jobRunInfo
The job run information to retrieve.
jobRunLog
The job run log to retrieve.
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( ARControlStruct CMDBQualifierStruct ARREJobRunInfoList unsigned int ARStatusList *control, *jobQualifier, *jobRunInfoList, *numMatches, *status)
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
jobQualifier
A query that determines the set of entries to retrieve. The qualification can include one or more subclasses and any combination of conditional, relational, and arithmetic operations. The following qualifiers are currently supported:
Run Status*, Run Start Time, Run End Time, Job Instance ID*, Job Run ID, and Submitter.
174
Return values
jobRunInfoList
The list of running jobs that match the qualification criteria.
numMatches
The total number of jobs that match the qualification criteria.
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBCancelJobRun
Description 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( ARControlStruct ARNameType ARStatusList *control, jobRunId, *status)
Privileges Synopsis
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
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.
Functions
175
Federation functions
The federation functions manipulate federated data for an instance. The C API functions for federation include:
! !
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( ARControlStruct CMDBClassNameId ARNameType ARNameType ARNameList ARNameList CMDBAttributeValueListList ARStatusList *control, *classNameId, datasetId, instanceId, *attributeGetList, *instanceIdList, *attrValueListList, *status
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The class name of the specified instance for which federated instances are to be retrieved.
datasetId
The dataset ID of the instance to retrieve.
176
instanceId
The instance ID of the specific instance for which federated instances are to be retrieved.
attributeGetList
The list of attribute names to retrieve. 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 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 CMDBClassNameId ARNameType ARNameType ARNameType unsigned int CMDBFederatedActivateInfo ARStatusList *control, *classNameId, datasetId, instanceId, federatedInstanceId, activateOption, *federatedInfo, *status
Privileges Synopsis
Functions
177
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.
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:
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.
178
Audit functions
The audit functions retrieve audit data for a class. The C API functions for audit include:
! !
CMDBGetCopyAuditData
Description Retrieves a copy of the specified CI instance if the attribute data for the instance is modified. The audit option must be set for the attributes characteristic to get the audit data. CMDB Administrator
#include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetCopyAuditData( ARControlStruct CMDBClassNameId ARNameType ARTimestamp CMDBQualifierStruct ARNameList CMDBSortList unsigned int unsigned int CMDBAuditValueListList unsigned int ARStatusList *control, *classNameId, instanceId, auditTimestamp, *qualifier, *attributeGetList, *sortList, firstRetrieve, maxRetrieve, *auditValueListList, *numMatches, *status)
Privileges Synopsis
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.
Functions
179
classNameId
The class name (class name and namespace combination) of the specified CI instance for which a copy of the audit data is to be retrieved.
instanceId
The instance ID of the specified CI instance for which a copy of the audit data is to be retrieved.
auditTimestamp
The data and time information for the instance. The CI instances with the data and time greater than or equal to the auditTimestamp will be retrieved. If auditTimestamp is 0, then all the audit data is retrieved.
qualifier
A query that determines the set of CI instances to retrieve. The qualification can include one or more attributes and any combination of conditional, relational, and arithmetic (numeric data types only) operations.
attributeGetList
A list of attribute names for which the audit data is to be retrieved.
sortList
The sort order for the attributes.
firstRetrieve
The first instance to retrieve for the qualification. CMDB_START_WITH_FIRST_ENTRY represents the first entry and is the default value if the value is not set.
maxRetrieve
The maximum number of entries to retrieve for the qualification. Use this parameter to limit the amount of data returned if the query does not narrow the list. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum. Return values
auditValueListList
The list of values for the specified attributes. If the audit option at the CI class-level is disabled, an error is returned.
numMatches
The number of CI instance entries that matched the specified qualification.
180
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
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 CMDBClassNameId ARNameType ARTextString ARStatusList *control, *classNameId, instanceId, *auditLog, *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.
Functions 181
Data structures
The C API data structures are categorized by function types, such as class functions and attribute functions. The data structures categories include Class, Attributes, General purpose, Graph Query, Export and Import, and Reconciliation Engine structures.
Class structures
Class structures are data structures for CI and relationship definitions (data model). The class data structures include:
! ! ! !
CMDBClassTypeInfo (page 182) CMDBClassRelationship (page 183) CMDBIndexList (page 184) CMDBIndexStruct (page 185)
CMDBClassTypeInfo
The CMDBClassTypeInfo structure is used to hold the class type information.
typedef struct CMDBClassTypeInfo { unsigned int classType; union { CMDBClassRelationship relationshipInfo; } u; } CMDBClassTypeInfo;
relationshipInfo
If the class type specified in the classType parameter is relationship, then the relationship information is retrieved.
182
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;
isRole2WeakReference
weak entity and it uses role 1s primary key as part of its own key. If the value is TRUE, cardinality must be one-to-one or many-to-many.
FALSEThe role 2 class is not a weak reference.
Data structures
183
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;
184
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;
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
Data structures
185
Attribute structures
Attribute structures are data structures for defining attributes. The attribute data structures include:
! ! ! ! ! ! ! ! !
CMDBAttributeGetStruct (page 186) CMDBAttributeLimitList (page 187) CMDBAttributeLimit (page 187) CMDBAttributNameId (page 192) CMDBAttributeValueList (page 192) CMDBAttributeValueListList (page 193) CMDBAttributeValueStruct (page 193) CMDBWeakPropagatedAttrs (page 194) CMDBWeakPropagatedAttrsList (page 194)
CMDBAttributeGetStruct
The CMDBAttributeGetStruct structure is used to hold the attributes to retrieve.
typedef struct CMDBAttributeGetStruct { unsigned int type; union { ARNameList attributeNameList; } u; } CMDBAttributeGetStruct;
attributeNameList
186
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;
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;
Data structures
187
0 1
CMDB_ATTR_DATA_TYPE_NULL CMDB_ATTR_DATA_TYPE_KEYWORD
2 3
CMDB_ATTR_DATA_TYPE_INTEGER CMDB_ATTR_DATA_TYPE_REAL
188
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_NU LL.
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_NU LL.
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. A UNIX-style date and time stamp (number of seconds since midnight January 1, 1970). A fixed-point decimal attribute. Values must be specified in C locale, for example, 1234.56. An attachment attribute. A currency attribute. A Julian date number (number of days since January 1, 4713 BC). The number of seconds since 12:00 a.m. of the current day.
CMDB_ATTR_DATA_TYPE_TIME
10
CMDB_ATTR_DATA_TYPE_DECIMAL
11 12 13
14 37
CMDB_ATTR_DATA_TYPE_TIME_OF_DAY
Data structures
189
190
Data structures
191
CMDBAttributNameId
The CMDBAttributeNameId structure is used to hold the namespace name and the class name information for a class.
typedef struct CMDBAttributeNameId { ARNameType namespaceName; ARNameType className; ARNameType attributeName; } CMDBAttributeNameId;
CMDBAttributeValueList
The CMDBAttributeValueList structure holds a list of values for an attribute.
typedef struct CMDBAttributeValueList { unsigned int numItems; CMDBAttributeValueStruct *attributeValueList; } CMDBAttributeValueList;
192
CMDBAttributeValueListList
The CMDBAttributeValueListList structure holds a list of values for an attributes list.
typedef struct CMDBAttributeValueListList { unsigned int numItems; CMDBAttributeValueList *attributeValueListList; } CMDBAttributeValueListList;
CMDBAttributeValueStruct
The CMDBAttributeValueStruct structure is used to hold values for attributes.
typedef struct CMDBAttributeValueStruct { ARNameType attributeName; ARValueStruct attributeValue; } CMDBAttributeValueStruct;
Data structures
193
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;
CMDBWeakPropagatedAttrsList
The CMDBWeakPropagatedAttrsList structure is used to hold a list of CMDBWeakPropagatedAttrs structures.
typedef struct CMDBWeakPropagatedAttrsList { unsigned int numItems; CMDBWeakPropagatedAttrs *attrsList; } CMDBWeakPropagatedAttrsList;
194
CMDBSortList
The CMDBSortList structure is used to hold a list of attributes to sort.
typedef struct CMDBSortList { unsigned int numItems; CMDBSortStruct *sortList; } CMDBSortList;
CMDBSortStruct
The CMDBSortStruct structure is used to hold the attribute to sort.
typedef struct CMDBSortStruct { ARNameType attributeName; unsigned int sortOrder; } CMDBSortStruct;
Data structures
195
Instance structures
Instance structures are data structures for instance data. The instance data structures include:
! ! !
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;
CMDBClassNameIdList
The CMDBClassNameIdList structure is used to hold a list of CMDBClassNameId structures.
typedef struct CMDBClassNameIdList { unsigned int numItems; CMDBClassNameId *classNameIdList; } CMDBClassNameIdList;
196
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;
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. The qualification in structure format.
qualifierStruct
Data structures
197
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;
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;
198
CMDBItemTypeClass (page 199) CMDBItemTypeAttribute (page 200) CMDBExportItem (page 200) CMDBExportItemList (page 201) CMDBExportItemStruct (page 201) CMDBXMLExportItemList (page 201) CMDBImportItem (page 202) CMDBImportItemList (page 203) CMDBImportItemStruct (page 204) CMDBXMLImportItemList (page 203)
CMDBItemTypeClass
The CMDBItemTypeClass data structure is used to hold the class name information.
typedef struct CMDBItemTypeClass { CMDBClassNameId classNameId; }CMDBItemTypeClass;
Data structures
199
CMDBItemTypeAttribute
The CMDBItemTypeAttribute data structure is used to hold a list of attribute information.
typedef struct CMDBItemTypeAttribute { CMDBClassNameId classNameId; ARNameList attribNameList; }CMDBItemTypeAttribute;
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;
(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.
200
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;
CMDBXMLExportItemList
The CMDBXMLExportItemList data structure is used to hold a list of items to export.
typedef struct CMDBXMLExportItemList unsigned int CMDBXMLExportItemStruct }CMDBXMLExportItemList; numItems; *exportItemList;
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;
Data structures
201
classNameId qualifier
The namespace name and the class name of the class that contains the items to export. 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).
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;
202
(CMDB_ITEM_TYPE_ATTRIBUTE). classItem attributeItem The class item to import. The attribute item to import.
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;
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;
Data structures
203
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;
classNameId
The namespace name and the class name of the class that contains the items to import.
204
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.
Data structures
205
CMDBGetObjectList (page 206) CMDBGetObjectStruct (page 206) CMDBGetRelationList (page 207) CMDBGetRelationStruct (page 207) CMDBGraphAdjacentList (page 208) CMDBGraphAdjacentStruct (page 208) CMDBGraphList (page 209) CMDBGraphStruct (page 209)
CMDBGetObjectList
The CMDBGetObjectList data structure is used to hold a list of CI instances.
typedef struct CMDBGetObjectList { unsigned int numItems; CMDBGetObjectStruct *objectList; } CMDBGetObjectList;
CMDBGetObjectStruct
The CMDBGetObjectStruct data structure is used to hold a CI instance.
typedef struct CMDBGetObjectStruct { CMDBClassNameId classNameId; ARNameType instanceId; CMDBAttributeValueList attributeValueList; } CMDBGetObjectStruct;
206
CMDBGetRelationList
The CMDBGetRelationList data structure is used to hold a list of relationships.
typedef struct CMDBGetRelationList { unsigned int numItems; CMDBGetRelationStruct *relationList; } CMDBGetRelationList;
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;
relatedClassNames[2] The names of the two classes that make up the relationship.
Data structures
207
The class IDs of the two classes that make up the relationship. The instance IDs of the two classes that make up the relationship. 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;
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;
208
The extension ID of the object. This item can contain an empty string. The qualification of the object. This item can be NULL. 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;
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;
Data structures
209
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;
210
componentType
(CMDB_COMPONENT_TYPE_LINE). tag1 tag2 tag3 tag4 tag5 encodedQual Information tag used to filter a specific component type. Information tag used to filter a specific component type. Information tag used to filter a specific component type. Information tag used to filter a specific component type. Information tag used to filter a specific component type. 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;
Data structures
211
CMDBUIComponentResultList
The CMDBUIComponentResultList data structure is used to hold the component query result.
typedef struct CMDBUIComponentResultList { unsigned int numItems; CMDBUIComponentResult *componentResList; } CMDBUIComponentResultList;
CMDBREJobRunInfoList (page 212) CMDBREJobRunInfo (page 213) CMDBREClassQualStruct (page 213) CMDBREClassQualList (page 214) CMDBREDatasetPair (page 214) CMDBREDatasetList (page 215)
CMDBREJobRunInfoList
The CMDBREJobRunInfoList data structure is used to hold a list of Reconciliation Engine jobs that are currently running.
typedef struct CMDBREJobRunInfoList { unsigned int numItems; CMDBREJobRunInfo *jobRunList; } CMDBREJobRunInfoList;
212
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;
CMDBREClassQualStruct
The CMDBREClassQualStruct data structure is used to hold information about the class qualification.
typedef struct CMDREBClassQualStruct { ARNameType classId; CMDBQualifierStruct *qual; }CMDBREClassQualStruct;
Data structures
213
CMDBREClassQualList
The CMDBREClassQualList data structure is used to hold a list of CMDBREClassQualStruct structures.
typedef struct CMDBREClassQuaList { unsigned int numItems; CMDBREClassQualStruct *classQualList; }CMDBREClassQuaList;
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;
dataset
214
CMDBREDatasetList
The CMDBREDatasetList data structure is used to hold a list of CMDBREDatasetPair structures.
typedef Struct CMDBREDatasetList { Unsigned int numItems; CMDBREDatasetPair* datasetList; }CMDBREDatasetList;
Federation structures
Federation structures are data structures used in federation functions. The federation structures include:
! !
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;
Data structures
215
The AR System server name. The AR System form name. The AR System view name. The qualifier string for accessing the AR System. 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;
216
accessType
federated interface
(CMDB_FEDERATED_ACCESS_TYPE_MANUAL). 5Access a data store for the federated interface (CMDB_FEDERATED_ACCESS_TYPE_DATA_STORE).
arInfo accessString
Contains information related to the AR System form. Based on the accessType subclasses, contains the URL link, process command, or other information.
Data structures
217
Audit structures
Audit structures are data structures used in audit functions. The audit structures include:
! ! !
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 user who performed the audit operation. The date and time when the audit operation was performed. The list of attribute names that changed in the audit operation. The list of attribute values that changed for the specified attributes.
218
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;
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;
Store the information for the modified attributes in a log. qual logForm The qualification to retrieve the audit information for the class. The name of the AR System form for the Log audit option.
Data structures
219
220
Chapter
221
Operations
The web services operations are categorized by the type of functions these operations perform. The operation categories include instance, data model, reconciliation object, and session.
Note: In the web services API function descriptions, the usage of the term specified for a given parameter denotes that the parameter is listed under the Synopsis heading of the API function.
GetInstances (page 223) SetInstance (page 225) CreateInstance (page 226) DeleteInstance (page 228) CreateRelationInstance (page 229) GraphQuery (page 231)
222
GetInstances
Description Privileges Synopsis 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>
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 instances are to be retrieved. It is a two-part structure that contains the namespace and the class name.
Operations 223
query
A qualification that determines the set of instances to retrieve. The qualification can include one or more attributes and any combination of conditional, relational, and arithmetic operations.
attributes
A list of attribute names to retrieve.
firstRetrieve
The first instance to retrieve. CMDB_START_WITH_FIRST_ENTRY represents the first entry and is the default value if the value is not set.
maxRetrieve
The maximum number of entries to retrieve. Use this parameter to limit the amount of data returned if the query does not narrow the list. Specify CMDB_NO_MAX_LIST_RETRIEVE to assign no maximum.
sortOrder
The sort order for the retrieved data.
aDatasetId
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
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.
224
SetInstance
Description Privileges Sets a CI or relationship instance in the class form. CMDB Administrator
<wsdl:operation name="SetInstance" parameterOrder="inargs"> <wsdl:input message="tns:SetInstanceRequest" name="SetInstanceRequest"/> <wsdl:output message="tns:SetInstanceResponse" name="SetInstanceResponse"/> </wsdl:operation> <wsdl:message name="SetInstanceRequest"> <wsdl:part element="tns:SetInstance" name="inargs"/> </wsdl:message> <wsdl:message name="SetInstanceResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="SetInstance"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="instanceId" type="xsd:string"/> <element name="aDatasetId" type="xsd:string"/> <element name="attributes" type="impl:AttributeValueList"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element>
Input arguments
loginInfo
The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
classNameId
The class for which the instance is to be set. It is a two-part structure that contains the namespace and the class name.
instanceId
The unique identifier for the instance.
Operations
225
aDatasetId
The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
attributes
A list of one or more name and value pairs (specified in any order) that identifies the data for the new attribute. You must specify values for all required subclasses that do not have defined defaults. Values must be of the data type defined for the subclasses or have a data type of 0. NULL values can be specified for optional attribute names only. An error is generated if an attribute does not exist or the user specified in the loginInfo parameter does not have the write permission for an attribute name. Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this operation.
CreateInstance
Description Privileges Synopsis Creates a CI or relationship instance in the class form. CMDB Administrator
<wsdl:operation name="CreateInstance" parameterOrder="inargs"> <wsdl:input message="tns:CreateInstanceRequest" name="CreateInstanceRequest"/> <wsdl:output message="tns:CreateInstanceResponse" name="CreateInstanceResponse"/> </wsdl:operation> <wsdl:message name="CreateInstanceRequest"> <wsdl:part element="tns:CreateInstance" name="inargs"/> </wsdl:message> <wsdl:message name="CreateInstanceResponse"> <wsdl:part element="tns:CreateInstanceOutput" name="outargs"/> </wsdl:message> <element name="CreateInstance"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="aDatasetId" type="xsd:string"/> <element name="attributes" type="impl:AttributeValueList"/> </sequence> </complexType> </element>
226
Input arguments
loginInfo
The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
classNameId
The class for which the instance is to be created. It is a two-part structure that contains the namespace and the class name.
aDatasetId
The unique identifier for the dataset. The data in the return values are based on the dataset ID specified in this parameter.
attributes
A list of one or more name and value pairs (specified in any order) that identifies the data for the new attribute. You must specify values for all required subclasses that do not have defined defaults. Values must be of the data type defined for the subclasses or have a data type of 0. NULL values can be specified for optional attribute names only. An error is generated if an attribute does not exist or the user specified in the loginInfo parameter does not have the write permission for an attribute name. Return values
instanceId
The unique identifier for the new attribute.
status
A list of zero or more notes, warnings, or errors generated from a call of this operation.
Operations
227
DeleteInstance
Description Privileges Synopsis Deletes an instance of a class. CMDB Administrator
<wsdl:operation name="DeleteInstance" parameterOrder="inargs"> <wsdl:input message="tns:DeleteInstanceRequest" name="DeleteInstanceRequest"/> <wsdl:output message="tns:DeleteInstanceResponse" name="DeleteInstanceResponse"/> </wsdl:operation> <wsdl:message name="DeleteInstanceRequest"> <wsdl:part element="tns:DeleteInstance" name="inargs"/> </wsdl:message> <wsdl:message name="DeleteInstanceResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="DeleteInstance"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="instanceId" type="xsd:string"/> <element name="aDatasetId" type="xsd:string"/> <element name="deleteOption" type="impl:InstanceDeleteOption"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element>
Input arguments
loginInfo
The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
classNameId
The class from which the instance is to be deleted. It is a two-part structure that contains the namespace and the class name.
instanceId
The unique identifier for the instance.
228
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,
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this operation.
CreateRelationInstance
Description Privileges Synopsis Creates relationship instances for the specified CIs. CMDB Administrator
<wsdl:operation name="CreateRelationInstance"> <wsdlsoap:operation soapAction="CreateRelationInstance" style="document"/> <wsdl:input name="CreateRelationInstanceRequest"> <wsdlsoap:body parts="inargs" use="literal"/> </wsdl:input> <wsdl:output name="CreateRelationInstanceResponse"> <wsdlsoap:body parts="outargs" use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:message name="CreateRelationInstanceRequest"> <wsdl:part element="tns:CreateRelationInstance" name="inargs"/> </wsdl:message> <wsdl:message name="CreateRelationInstanceResponse"> <wsdl:part element="tns:CreateInstanceOutput" name="outargs"/> </wsdl:message> <xsd:element name="CreateRelationInstance"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="classNameId" type="tns:ClassNameId"/> <xsd:element name="role1Name" type="xsd:string"/> <xsd:element name="instance1Id" type="xsd:string"/> <xsd:element name="class1Id" type="xsd:string"/> <xsd:element name="role2Name" type="xsd:string"/> <xsd:element name="instance2Id" type="xsd:string"/> <xsd:element name="class2Id" type="xsd:string"/>
Operations
229
Input arguments
loginInfo
The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
classNameId
The class in which the relationship instance is to be created. It is a two-part structure that contains the namespace and the class name.
role1Name
The role name of the parent instance.
instance1Id
The instance ID of the parent instance.
classId
The class ID of the parent instance.
role2Name
The role name of the child instance.
instance2Id
The instance ID of the child instance.
class2Id
The class name of the child instance.
aDatasetId
The ID of the dataset within which the CI classes exist.
230
attributes
The list of attributes values for the relationship class. Return Values
instanceId
The instance ID of the relationship instance that is created.
status
A list of zero or more notes, warnings, or errors generated from a call of this operation.
GraphQuery
Description Privileges Synopsis Queries related instances for the specified CI. CMDB Administrator
<wsdl:operation name="GraphQuery" parameterOrder="inargs"> <wsdl:input message="tns:GraphQueryRequest" name="GraphQueryRequest"/> <wsdl:output message="tns:GraphQueryResponse" name="GraphQueryResponse"/> </wsdl:operation> <wsdl:message name="GraphQueryRequest"> <wsdl:part element="tns:GraphQuery" name="inargs"/> </wsdl:message> <wsdl:message name="GraphQueryResponse"> <wsdl:part element="tns:GraphQueryOutput" name="outargs"/> </wsdl:message> <element name="GraphQuery"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="startClassNameId" type="impl:ClassNameId"/> <element name="startExtensionId" type="xsd:string"/> <element name="startInstanceId" type="xsd:string"/> <element name="numLevels" type="xsd:int"/> <element name="direction" type="impl:GraphDirection"/> <element name="noMatchProceed" type="xsd:boolean"/> <element name="onMatchProceed" type="xsd:boolean"/> <element name="graph" type="impl:GraphList"/> <element name="aGetMask" type="tns:GetMask"/> <element name="aDatasetId" type="xsd:string"/> </sequence> </complexType> </element>
Operations
231
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.
startClassNameId
The name of the starting node class in the CI graph.
startExtensionId
The extension ID of the starting node CI. This is required if the query graph contains more than one instance of the same class and needs to distinguish one from another. For example, if the starting node class is BMC:A and BMC:A appears more than once in the query graph, you can designate one of them to have an extension ID of 2 to distinguish it from the other one.
startInstanceId
The ID of the starting node in the CI graph.
numLevels
The number of levels to traverse the specified queryGraph. The value A-1 specifies the graph query to traverse to the end of the graph.
direction
The direction in which the graph is to traverse.
IMPACT_NODE_RIGHT:
232
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.
GET_MASK_NONE: Based on the datasetId being passed, instances are
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.
Operations
233
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.
GetClass (page 235) SetClass (page 236) CreateClass (page 237) ListClasses (page 238) DeleteClass (page 240) GetAttributes (page 241) SetAttribute (page 244) CreateAttribute (page 242) Delete Attribute (page 245)
234
GetClass
Description Privileges Synopsis 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>
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.
Operations
235
SetClass
Sets the properties for a specified class. Privileges Synopsis CMDB Administrator
<wsdl:operation name="SetClass" parameterOrder="inargs"> <wsdl:input message="tns:SetClassRequest" name="SetClassRequest"/> <wsdl:output message="tns:SetClassResponse" name="SetClassResponse"/> </wsdl:operation> <wsdl:message name="SetClassRequest"> <wsdl:part element="tns:SetClass" name="inargs"/> </wsdl:message> <wsdl:message name="SetClassResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="SetClass"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="newClassNameId" type="impl:ClassNameId"/> <element name="classInfo" type="impl:ClassInfoIn"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element>
Input arguments
loginInfo
The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
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.
236
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 CMDB Administrator
<wsdl:operation name="CreateClass" parameterOrder="inargs"> <wsdl:input message="tns:CreateClassRequest" name="CreateClassRequest"/> <wsdl:output message="tns:CreateClassResponse" name="CreateClassResponse"/> </wsdl:operation> <wsdl:message name="CreateClassRequest"> <wsdl:part element="tns:CreateClass" name="inargs"/> </wsdl:message> <wsdl:message name="CreateClassResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="CreateClass"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="superclassNameId" type="impl:ClassNameId"/> <element name="classId" type="xsd:string"/> <element name="classInfo" type="impl:ClassInfoIn"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element>
Input arguments
loginInfo
The login information for the operation, such as the user ID, password, and the language to be used for the session. The userId is a required element.
Operations
237
classNameId
The name of the class to create. It is a two-part structure that contains the namespace and classname in the <namespace>:<classname> format. The name of the class must be unique.
superClassNameId
The superclass of class being created. Specify NULL for this parameter if there is no superclass.
classId
The unique identifier for the class. It can be provided by the user. If it is not provided by the user, it will be automatically generated by the system.
classInfo
The information about the class, such as the type of class to create. The information contained in this definition depends on the type of class you specify. Return values
status
A list of zero or more notes, warnings, or errors generated from a call to this operation.
ListClasses
Description Retrieves information about relationship classes for a specified class. The classes that are retrieved will have the class that is specified in the relatedClass parameter as part of the relationship. CMDB Administrator
<wsdl:operation name="ListClasses"> <wsdlsoap:operation soapAction="ListClasses" style="document"/> <wsdl:input name="ListClassesRequest"> <wsdlsoap:body parts="inargs" use="literal"/> </wsdl:input> <wsdl:output name="ListClassesResponse"> <wsdlsoap:body parts="outargs" use="literal"/> </wsdl:output> </wsdl:operation> <wsdl:message name="ListClassesRequest"> <wsdl:part element="tns:ListClassesInput" name="inargs"/> </wsdl:message>
Privileges Synopsis
238
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.
Operations
239
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.
DeleteClass
Description Privileges Synopsis 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>
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.
240
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
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. Return values
status
A list of zero or more notes, warnings, or errors generated from a call to this operation.
GetAttributes
Description Privileges Synopsis Retrieves information about a list of attributes CMDB Administrator
<wsdl:operation name="GetAttributes" parameterOrder="inargs"> <wsdl:input message="tns:GetAttributesRequest" name="GetAttributesRequest"/> <wsdl:output message="tns:GetAttributesResponse" name="GetAttributesResponse"/> </wsdl:operation> <wsdl:message name="GetAttributesRequest"> <wsdl:part element="tns:GetAttributes" name="inargs"/> </wsdl:message> <wsdl:message name="GetAttributesResponse"> <wsdl:part element="tns:GetAttributesOutput" name="outargs"/> </wsdl:message> <element name="GetAttributes"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="attributeNames" type="impl:ArrayOf_String"/> </sequence>
Operations
241
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 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.
status
A list of zero or more notes, warnings, or errors generated from a call to this operation.
CreateAttribute
Description Privileges Synopsis Creates an attribute for the specified instance. CMDB Administrator
<wsdl:operation name="CreateAttribute" parameterOrder="inargs"> <wsdl:input message="tns:CreateAttributeRequest" name="CreateAttributeRequest"/> <wsdl:output message="tns:CreateAttributeResponse" name="CreateAttributeResponse"/> </wsdl:operation> <wsdl:message name="CreateAttributeRequest"> <wsdl:part element="tns:CreateAttribute" name="inargs"/> </wsdl:message> <wsdl:message name="CreateAttributeResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/>
242
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 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.
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.
Operations
243
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 Sets an attribute for the specified instance. CMDB Administrator
<wsdl:operation name="SetAttribute" parameterOrder="inargs"> <wsdl:input message="tns:SetAttributeRequest" name="SetAttributeRequest"/> <wsdl:output message="tns:SetAttributeResponse" name="SetAttributeResponse"/> </wsdl:operation> <wsdl:message name="SetAttributeRequest"> <wsdl:part element="tns:SetAttribute" name="inargs"/> </wsdl:message> <wsdl:message name="SetAttributeResponse"> <wsdl:part element="tns:StatusOutput" name="outargs"/> </wsdl:message> <element name="SetAttribute"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="classNameId" type="impl:ClassNameId"/> <element name="attributeName" type="xsd:string"/> <element name="newAttributeName" type="xsd:string"/> <element name="attributeInfo" type="impl:AttributeInfoIn"/> </sequence> </complexType> </element> <element name="StatusOutput"> <complexType> <sequence> <element name="status" type="impl:StatusList"/> </sequence> </complexType> </element>
244
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>
Operations
245
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.
246
ExecuteJobRun (page 247) GetJobRun (page 248) GetListJobRun (page 250) CancelJobRun (page 251)
ExecuteJobRun
Description Privileges Synopsis 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>
Operations
247
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.
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 Retrieves information about a currently running job. CMDB Administrator
<wsdl:operation name="GetJobRun" parameterOrder="inargs"> <wsdl:input message="tns:GetJobRunRequest" name="GetJobRunRequest"/> <wsdl:output message="tns:GetJobRunResponse" name="GetJobRunResponse"/> </wsdl:operation> <wsdl:message name="GetJobRunRequest"> <wsdl:part element="tns:GetJobRun" name="inargs"/> </wsdl:message> <wsdl:message name="GetJobRunResponse"> <wsdl:part element="tns:GetJobRunOutput" name="outargs"/> </wsdl:message> <element name="GetJobRun"> <complexType> <sequence> <element name="loginInfo" type="impl:LoginInfo"/> <element name="jobId" type="xsd:string"/> </sequence> </complexType> </element>
248
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.
Operations
249
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>
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.
250
status
A list of zero or more notes, warnings, or errors generated from a call to this operation.
CancelJobRun
Description Privileges Synopsis 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>
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.
Operations
251
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
Description Expands the FederatedInterface instance for a specific CI and federated interface. Depending on a flag you specify when you call this function, your federated instance might either be only expanded or expanded and launched. CMDB Administrator
<wsdl:operation name="ActivateFederatedInContext" parameterOrder="inargs"> <wsdl:input message="tns:ActivateFederatedInContextRequest" name="ActivateFederatedInContextRequest"/> <wsdl:output message="tns:ActivateFederatedInContextResponse" name="ActivateFederatedInContextResponse"/> </wsdl:operation> <wsdl:message name="ActivateFederatedInContextRequest"> <wsdl:part element="tns:FederatedActivateInfoInput" name="inargs"/> </wsdl:message> <wsdl:message name="ActivateFederatedInContextResponse"> <wsdl:part element="tns:FederatedActivateInfoOutput" name="outargs"/> </wsdl:message> <xsd:element name="FederatedActivateInfoInput"> <xsd:complexType> <xsd:sequence> <xsd:element name="loginInfo" type="tns:LoginInfo"/> <xsd:element name="classNameId" type="tns:ClassNameId"/> <xsd:element name="aDatasetId" type="xsd:string"/> <xsd:element name="instanceId" type="xsd:string"/> <xsd:element name="federatedInstanceId type="xsd:string"/> <xsd:element name="activateOption" type="tns:FederatedActivationOption"/> </xsd:sequence> </xsd:complexType> </xsd:element>
Privileges Synopsis
252
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:
Operations
253
Return values
federatedActivateInfo
The expanded federated instance information. This parameter is returned only if you specify a value of 1in the activateOption parameter.
status
A list of zero or more notes, warnings, or errors generated from a call to this operation.
GetRelatedFederatedInContext
Description Privileges Synopsis 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>
254
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 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. 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.
Operations
255
Audit operations
The audit functions manipulate the audit option for the classes and attributes. The web services API for audit includes:
!
GetCopyAuditData
Description Retrieves a copy of the specified CI instance if the attribute data for the instance is modified. The audit option must be set for the 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>
Privileges Synopsis
256
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.
Operations
257
GetUIComponents
Description Privileges Synopsis 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>
258
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.
componentInfo
The qualification for the user interface component. You can specify information such as locale, classId, and tags to get the required UI component data. If there are no qualifications specified, all existing UI components will be returned.
datasetId
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.
Operations
259
Utility operations
The utility operations enable you to use CMDB utilities such as get version information of the BMC Atrium CMDB application. The web services API includes the following utility operations:
!
GetVersions
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> <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.
260
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.
Operations
261
Data structures
The web services data structures are used as parameters for web services operations. The data structure categories include Instance, Graph query, Class, and Reconciliation Engine structures.
Instance structures
Instance structures are data structures for the instance data. Instance structures include:
! ! ! ! ! ! ! ! ! !
LoginInfo (page 262) ClassNameIdList (page 263) ClassNameId (page 263) ArrayOf_String (page 263) SortOrderList (page 264) SortOrder (page 264) InstanceInfoList (page 264) InstanceInfo (page 265) StatusList (page 265) Status (page 265)
LoginInfo
The LoginInfo data structure is used to hold the login information for a user.
<complexType name="LoginInfo"> <sequence> <element name="userId" type="xsd:string"/> <element name="password" type="xsd:string"/> <element name="lang" type="xsd:string"/> </sequence> </complexType>
262
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>
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>
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>
Data structures
263
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>
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>
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>
264
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>
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>
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>
Data structures
265
cancelled.
PROMPTStatus for the active link action. ACCESSIBLEStatus message for client accessibility.
An integer value indicating the message number. The description for the status message. Additional information for the status message.
266
GraphList (page 267) Graph (page 267) GraphAdjacencyList (page 268) GraphAdjacency (page 268) ObjectQueryInfoList (page 269) ObjectQueryInfo (page 270) RelationQueryInfoList (page 270) RelationQueryInfo (page 271)
GraphList
The GraphList data structure is used to hold a list of graph information.
<complexType name="GraphList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:Graph"/> </sequence> </complexType>
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>
Data structures
267
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>
GraphAdjacency
The GraphAdjacency data structure is used to hold an adjacent node.
<xsd:complexType name="GraphAdjancency"> <xsd:sequence> <xsd:element name="extensionId" type="xsd:string"/> <xsd:element name="objectClassName" type="tns:ClassNameId"/> <xsd:element name="objectAttributeNames" type="tns:ArrayOf_String"/> <xsd:element name="objectAttributeType" type="tns:GraphAdjancencyAttributeType"/> <xsd:element name="objectQuery" type="xsd:string"/> <xsd:element name="relationClassName" type="tns:ClassNameId"/> <xsd:element name="relationAttributeNames" type="tns:ArrayOf_String"/> <xsd:element name="relationAttributeType" type="tns:GraphAdjancencyAttributeType"/> <xsd:element name="relationQuery" type="xsd:string"/> </xsd:sequence> </xsd:complexType>
268
The name of the class that makes up the relationship. The related attribute to retrieve from the relationship. The related attribute type. 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>
Data structures
269
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>
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>
270
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>
Data structures
271
Class Structures
Class structures are data structures for class and relationship definitions. The class data structures include:
! ! ! ! ! ! ! !
ClassInfoIn (page 272) ClassInfoOut (page 273) ClassRelationship (page 273) ClassProperties (page 275) IndexList (page 276) IndexInfo (page 276) PropInfoList (page 277) PropInfo (page 277)
ClassInfoIn
The ClassInfoIn data structure is used to set class information.
<complexType name="ClassInfoIn"> <sequence> <element name="relationshipInfo" nillable="true" type="impl:ClassRelationship"/> <element name="indexList" type="impl:IndexList"/> <element name="properties" type="impl:ClassProperties"/> <element name="customCharacList" type="impl:PropertyList"/> </sequence> </complexType>
272
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>
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>
Data structures
273
roleNames2 cardinality
The role name of the parent class that is a part of the relationship. 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
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.
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-to-one or many-to-many.
FALSEThe role 2 class is not a weak reference.
weakPropagatedAttrsList If the value of isRole2WeakReference is TRUE, indicates the list of attributes that are propagated from the role 1 class to the role 2 class.
274
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>
hiddenPerms
abstract class 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. A value indicating the groups or roles that can view the class form bothin the ObjectList form of the application and the workflow.
visiblePerms
description isFinal
The description text for the class. 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.
Data structures
275
A Boolean value indicating whether the class is a singleton class. The form name for the class. The name of the author for the class. The structure that holds the audit information for the class.
IndexList
The IndexList structure is used to hold index information for the class.
<xsd:complexType name="IndexList"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="items" type="tns:IndexInfo"/> </xsd:sequence> </xsd:complexType>
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>
276
isPrimaryKey
attributeNames
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>
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>
Data structures
277
Attribute structures
Attribute structures are data structures for attribute definitions. The attribute data structures include:
! ! ! ! ! ! ! ! ! ! ! ! !
AttributeInfoList (page 278) AttributeValueList (page 279) AttributeValue (page 279) AttributeInfoIn (page 279) AttributeLimit (page 281) AttachmentLimit (page 282) CurrencyLimit (page 283) CharLimit (page 282) DateLimit (page 284) EnumLimit (page 284) IntLimit (page 285) RealLimit (page 285) AttributeLimitList (page 286)
AttributeInfoList
The AttributeInfoList data structure is used to retrieve attribute information.
<complexType name="AttributeInfoList"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="items" type="impl:AttributeInfoOut"/> </sequence> </complexType>
278
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>
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>
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>
Data structures
279
createMode
attribute. attrLimit changePerms isHidden The AttributeLimit structure defining the limit for the attribute. A value indicating the change permissions for the attribute. 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.
viewPerms customCharacList
A value indicating the view permissions for the attribute. A structure indicating the custom properties for the attribute.
280
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>
Data structures
281
timeLimit timeOfDayLimit
A TimeLimit structure indicating the data limit for a time data type. A TimeOfDayLimit structure indicating the data limit for a time of day data type.
AttachmentLimit
The AttachmentLimit structure is used to hold data limit definitions for the attachment data type.
<xsd:complexType name="AttachmentLimit"> <xsd:sequence> <xsd:element name="attachmentPoolName" type="xsd:string"/> <xsd:element name="maxSize" type="xsd:long"/> </xsd:sequence> </xsd:complexType>
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>
282
FTSOption
maxCharLength menuStyle
The menyStyle field is applicable only if a menu is attached. pattern QBEOption The AR System pattern specification for the field that is attached to this attribute. 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>
Data structures
283
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>
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>
284
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>
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>
Data structures
285
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
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
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>
286
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>
Data structures
287
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>
retrieve.
COMPONENT_TYPE_LINEThe user interface graphical line information to retrieve (This option is currently not being used.) COMPONENT_TYPE_LOCALIZED_LABELThe localized
to retrieve.
COMPONENT_TYPE_TOOLTIPThe tooltip type
component to retrieve. encodedQual The encoded qualifier for the UI component query.
288
locale
The name of the locale specific to the component. If no locale is specified in this subclasses, the default locale will be used. Information tag used to filter a specific component type. Information tag used to filter a specific component type. Information tag used to filter a specific component type. Information tag used to filter a specific component type. 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>
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>
Data structures
289
JobRunInfo (page 290) JobRunInfoList (page 291) ClassQualifierList (page 291) ClassQualifier (page 291) DatasetPairList (page 292) DatasetPair (page 292)
JobRunInfo
The JobRunInfo data structure is used to retrieve job information.
<complexType name="JobRunInfo"> <sequence> <element name="jobStartTime" type="xsd:dateTime"/> <element name="jobEndTime" type="xsd:dateTime"/> <element name="jobInstanceId" type="xsd:string"/> <element name="jobName" type="xsd:string"/> <element name="jobRunId" type="xsd:string"/> </sequence> </complexType>
290
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>
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>
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>
classId
Data structures
291
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>
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>
workingDataset
292
Federation structures
Federation structures are data structures used in federation operations. The federation structures include:
! !
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>
actionType
Data structures
293
accessString arInfo
Based on the accessType subclasses, contains the URL link, process command, or other information. Contains information related to the AR System form.
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>
Process. The AR System form name. The qualifier string for accessing the AR System. The AR System server name. Contains a URL to access the AR System form depending on whether the default web path is specified on the AR System server.
294
Audit structures
Audit structures are data structures used in audit operations. The audit structures include:
! ! !
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>
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>
Data structures
295
changedBy operation
The user who performed the audit 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.
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>
is modified.
LogStore the information for the modified attributes in a log. NoneNo auditing option set.
qualifierString
296
Chapter
Error messages
This chapter contains all BMC Atrium CMDB error messages in their numerical order. Use the error number to look up any error message. The following topics are provided:
! ! !
BMC Atrium CMDB C API error messages (page 298) CMDB Console active link error messages (page 327) CMDB Console filter error messages (page 334)
Error messages
297
Error message The CMDB API session is not initialized. (CMDB_ERROR_SYSTEM_NOT_INITIALIZED) Description You did not initialize the CMDB API session in your API calls. Solution You must call the CMDBInitialization function before calling another BMC Atrium CMDB C API function.
120001
Error
A fatal error occurred during CMDB initialization. The CMDB system cannot be initialized. (CMDB_ERROR_SYSTEM_CANNOT_BE_INITIALIZED) Description A system error prevented the CMDB from being initialized. Solution Contact your CMDB system administrator.
120002
Error
Class does not exist. (CMDB_ERROR_NO_SUCH_CLASS) Description The class you are attempting to view does not exist in the CMDB. Solution Specify a valid class name or class ID.
120003
Error
A required parameter is empty. (CMDB_ERROR_REQUIRED_PARAM_EMPTY) Description You did not specify a value for a required function parameter. Solution Provide a non-empty parameter to the BMC Atrium CMDB C API function call.
298
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Attribute does not exist. (CMDB_ERROR_NO_SUCH_ATTRIBUTE) Description The attribute you are attempting to view does not exist. Solution Provide a valid attribute name or ID.
120005
Error
The supplied attribute data type is not supported. (CMDB_ERROR_UNSUPPORTED_ATTRIBUTE_DATA_TYPE) Description The data type specified for the attribute does not exist in the CMDB. Solution Make sure that the supplied attribute data type is supported. For more information about data types, see AR_DATA_TYPE section of the ar.h file.
120006
Error
Instance not found. (CMDB_ERROR_INSTANCE_NOT_FOUND) Description The specified instance is not found. Solution Specify a valid instance ID.
120007
Error
CMDB system error occurred during processing. (CMDB_ERROR_SYSTEM_ERROR) Description An unexpected system error occurred during CMDB processing. Solution Contact your CMDB system administrator.
120009
Error
The class name is not unique. The class name is already in use. (CMDB_ERROR_CLASS_NAME_ID_NOT_UNIQUE) Description The specified class name already exists within the given namespace. Solution Specify an unused class name.
299
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Class already exists. (CMDB_ERROR_CLASS_ALREADY_EXISTS) Description A class with the specified class ID already exists. Solution Create a class with a different class ID.
120014
Error
The attribute name is not unique. The attribute name is already in use. (CMDB_ERROR_ATTRIBUTE_NAME_NOT_UNIQUE) Description An attribute with the specified name already exists. Solution Specify an unused attribute name.
120015
Error
Attribute already exists. (CMDB_ERROR_ATTRIBUTE_ALREADY_EXISTS) Description An attribute with the same attribute ID already exists. Solution Specify a different attribute ID.
120016
Error
The default enumeration value is invalid. (CMDB_ERROR_INVALID_ENUM_DEFAULT) Description The default value specified for the enumeration attribute is not one of the defined values. Solution Specify an enumeration value you defined.
120017
Error
The specified list format is not valid. (CMDB_ERROR_INVALID_LIST_FORMAT) Description The format is L<n>, where n is the maximum number of items. Solution Modify the list format to L<n>.
300
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message (CMDB_ERROR_EXCEED_MAX_LIST_ITEMS) Description The number of semicolon-separated items in a character subclass exceeds the number specified in the list subclasses. Solution Decrease the number of items in the subclasses or change the list format.
120019
Error
The relationship role names must be different. (CMDB_ERROR_ROLE_NAMES_MUST_BE_DIFFERENT) Description You cannot create a relationship class with the same role name. Solution Provide a different role name for each role.
120020
Error
An invalid cardinality value was supplied. (CMDB_ERROR_INVALID_CARDINALITY_VALUE) Description The cardinality you specified is not one of the defined values. Solution Specify a valid cardinality value.
120021
Error
Cannot create a relationship class that is derived for a nonrelationship class. (CMDB_ERROR_SUPERCLASS_MUST_BE_REL_CLASS) Description You are attempting to derive a relationship class from a class of another type. Solution Derive from a relationship class.
120022
Error
The role name does not match the superclass role name. (CMDB_ERROR_ROLE_NAME_DOES_NOT_MATCH_SUPERCLASS) Description When creating a derived relationship class, the role name properties must match the superclasss role name properties. Solution Supply the same role name as the superclass.
301
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The Configuration Item Class for the role is not a derived class of the superclasss role. (CMDB_ERROR_CLASS_ROLE_NOT_SUPERCLASS_DERIVED) Description When creating a derived relationship class, the configuration item role classes must be the same as or derived from the superclass' configuration item role classes. Solution Derive a role class from the superclasss role class.
120024
Error
The cardinality of the derived relationship class cannot be less restrictive than the superclass. (CMDB_ERROR_SUBCLASS_CARDINALITY_LESS_RESTRICTIVE) Description If the superclass cardinality is one-to-many, the derived class cardinality can be one-to-one, but cannot be many-to-many. Solution Specify a cardinality that is the same as the superclass or is more restrictive than the superclass.
120025
Error
The supplied relationship parameter cannot be modified. (CMDB_ERROR_RELATIONSHIP_PARAM_CANNOT_BE_CHANGED) Description You cannot modify the relationship parameter. Solution Do not attempt to modify the relationship parameter.
120026
Error
The supplied class type is invalid. (CMDB_ERROR_INVALID_CLASS_TYPE) Description The class type you specified is not one of the system defined class types. Solution Select a valid class typeCI or Relationship.
302
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The class type cannot be modified. (CMDB_ERROR_CLASS_TYPE_CANNOT_BE_CHANGED) Description You cannot modify the class type. Solution Do not attempt to modify an existing class type.
120028
Error
The attribute cannot be set. (CMDB_ERROR_ATTRIBUTE_CANNOT_BE_SET) Description You cannot set the attribute. Solution Contact your CMDB Systems Administrator.
120029
Error
The attribute information is corrupt. (CMDB_ERROR_ATTRIBUTE_INFO_CORRUPT) Description Information for the attribute is corrupt. Solution Contact your CMDB systems administrator.
120030
Error
Invalid instance operation on the abstract class. (CMDB_ERROR_INVALID_ABSTRACT_CLASS_INST_OPERATION) Description You are attempting to perform an abstract class operation on an instance. Solution Perform the operation on a non-abstract class.
120031
Error
The parameters for the categorization class are invalid. (CMDB_ERROR_INVALID_CATEGORAIZATION_SUBCLASS) Description The parameter value you specified for the categorization class does not match with the class definition. Solution Make sure that the parameters for the categorization class are correct.
303
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The parameters for the final class are invalid. (CMDB_ERROR_INVALID_FINAL_CLASS) Description The parameter value you specified for the final class does not match with the class definition. Solution Make sure that the parameters for the final class are correct.
120033
Error
The parameters for the singleton class are invalid. (CMDB_ERROR_INVALID_SINGLETON_CLASS) Description The parameter value you specified for the singleton class does not match with the class definition. Solution Make sure that the parameters for the singleton class are correct.
120034
Warning
The specified export item type is invalid. (CMDB_WARN_INVALID_EXPORT_ITEM_TYPE) Description The item type you are attempting to export is invalid. Solution The export item should be either of type CMDB-ITEM-TYPE-METADATA (1) or CMDB-INSTANCE-DATA (2).
120035
Error
The permission list must be a list of group IDs separated by semicolons. (CMDB_ERROR_PERMISSION_LIST_INVALID) Description You are attempting to separate a list of group IDs using an invalid character. Solution Use semicolons to separate the groups IDs in the permission list.
304
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The specified query graph does not have a starting node. (CMDB_ERROR_QUERY_GRAPH_HAS_NO_STARTNODE) Description You omitted the starting node parameter in a graph query. Solution Make sure you specify the starting node information in the graph query.
120037
Error
A specified node is ambiguous. (CMDB_ERROR_QUERY_GRAPH_HAS_AMBIGUOUS_NODE) Description There is more than one node with the same name for the query graph. Solution Use an extension ID to distinguish between nodes within the same class and namespace.
120038
Error
Creating more than one instance in a singleton class is not allowed. (CMDB_ERROR_INVALID_SINGLETON_CLASS_INST_OPERATION) Description You can create only one instance from a singleton class. Solution Do not create more than one instance from a singleton class.
120039
Error
The operation violates the cardinality constraint of the relationship. (CMDB_ERROR_RELATION_CARDINALITY_CHECK) Description The operation you are performing violates the cardinality constraint of the relationship. Solution Using the CI Relationship Viewer, make sure that the operation does not violate the cardinality constraint.
305
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The relationship endpoint instance does not exist. (CMDB_ERROR_RELATION_END_PT_DOES_NOT_EXIST) Description You are attempting to create a relationship for a CI instance that does not exist. Solution Make sure that the instance exists.
120041
Error
Required attributes are not allowed in categorization classes. (CMDB_ERROR_CATSUBCLASS_REQD_ATTR_NOT_ALLOWED) Description You are specifying the entry mode option as Required for the categorization class. This option is not allowed. Solution Change the entry mode to Optional.
120042
Error
Because the relationship superclass is a weak relationship, this class must also be a weak relationship. (CMDB_ERROR_SUBCLASS_MUST_BE_RS_WEAK_REFERENCE) Description You cannot derive a regular relationship subclass from a weak relationship superclass. Solution Define this class to be of type weak relationship.
120043
Error
Invalid cardinality for the weak relationship. (CMDB_ERROR_INVALID_CARDINALITY_FOR_WEAK_REFERENCE) Description You are attempting to specify an incorrect cardinality for a weak relationship. Solution The cardinality for a weak relationship must be either one-to-many or one-to-one.
306
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The weak instance is already associated with another lead instance. (CMDB_ERROR_WEAK_INSTANCE_ALREADY_ASSOCIATED) Description You are attempting to specify more than one lead instance for a weak instance. Solution Unassociate the weak instance before trying to associate it with another lead instance.
120045
Error
The weak class of the weak relationship cannot be abstract. (CMDB_ERROR_NO_WEAK_RELATION_ABSTRACT_CLASS_ALLOWED) Description You cannot create a weak class of abstract type for a weak relationship. Solution Define the weak class of the weak relationship to be non-abstract.
120046
Error
Setting lead class reference values is not allowed. (CMDB_ERROR_SETTING_LEAD_CLASS_REF_DISALLOWED) Description You cannot modify the attributes propagated from the lead class. Solution Do not attempt to modify propagated read-only attributes values.
120048
Error
You cannot set a primary key characteristic on an attribute. (CMDB_ERROR_CANNOT_MODIFY_PRIMARY_KEY_ON_ATTRIBUTE) Description You can only set an attribute as the primary key by way of a unique index. Solution You must set the primary key characteristic by way of an index.
307
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The primary key must be a unique index. (CMDB_ERROR_PRIMARY_KEY_ISNT_UNIQUE) Description The attribute you are attempting to set as primary key contains duplicate values. Solution Specify a unique index as the primary key.
120050
Error
You can have only one primary key per class. (CMDB_ERROR_MORE_THAN_ONE_PRIMARY_KEY_DISALLOWED) Description You are attempting to set more than one primary key for a class. Solution Specify only one primary key per class.
120051
Error
The weak class for the weak relationship class cannot be a categorization class. (CMDB_ERROR_NO_RHS_CATSUBCLASS_FOR_WEAK_REFERENCE) Description You are attempting to create the right-hand class of type categorization class in a week relationship. Solution Define the weak class to be a non-categorization class.
120053
Error
The class cannot be deleted because this class has instance data. (CMDB_ERROR_DELETE_CLASS_FAILED_DATA_EXISTS) Description You are attempting to delete a class that contains data. Solution To delete a class that contains data, specify Delete With Data as the delete option.
308
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The class cannot be deleted because there are class dependencies on this class. (CMDB_ERROR_DELETE_CLASS_FAILED_DEPENDECIES_EXISTS) Description You are attempting to delete a class that has a subclass or is CI instance for a relationship. Solution To delete a class with dependencies, specify Delete With Dependencies as the delete option. WARNING: The Delete With Dependencies option will also delete all dependent classes. This option will delete the classes even if they contain data.
120055
Warning
This class is a derived class of the class being deleted. (CMDB_WARN_DELETE_CLASS_FAILED_DEP_REG_CLASS) Description This is a warning that the class being deleted had a derived class.
120056
Warning
An endpoint for this relationship class is the class being deleted. (CMDB_WARN_DELETE_CLASS_FAILED_DEP_REL_CLASS) Description This is a warning that a CI instance for the specified relationship class is being deleted.
120057
Warning
This class is a weak class of the relationship class being deleted. (CMDB_WARN_DELETE_CLASS_FAILED_DEP_WEAK_REF_CLASS) Description This is a warning that the specified weak class of the relationship class is being deleted.
120058
Error
The source attribute on the lead class for attribute propagation does not exist. (CMDB_ERROR_NO_SUCH_SOURCE_ATTRIBUTE_FOR_WEAK_REL) Description You are attempting to propagate an attribute that does not exist in the source class. Solution Make sure that the source attribute exists in the lead class.
309
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The target attribute on the weak class for attribute propagation does not exist. (CMDB_ERROR_NO_SUCH_TARGET_ATTRIBUTE_FOR_WEAK_REL) Description You are attempting to propagate an attribute of the weak class that does not exist. Solution Make sure that the target attribute exists in the weak class.
120060
Error
The data types for the source and target attributes do not match. (CMDB_ERROR_ATTRIBUTE_DATATYPE_MISMATCH_FOR_WEAK_REL) Description The attributes being propagated from the lead and weak classes must have the same data type. Solution Make sure that the data type of the propagated attributes match.
120061
Error
The specified target attribute on the weak class cannot be a derived attribute from a superclass. (CMDB_ERROR_TARGET_WEAK_ATTR_CANNOT_DERIVED_ATTR) Description You are attempting to specify a derived attribute as the target attribute in the weak class. Solution Specify a target attribute for the weak class that is not a derived from its superclass.
120062
Error
Permissions for a categorization class must be the same as the permissions for the superclass. (CMDB_ERROR_CATGORIZATION_SUB_PERM_LIST_INVALID) Description The categorization class permissions must match the permissions of its superclass. Solution Make sure that the categorization class permissions match its superclass.
310
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Instances cannot be deleted from this form. (CMDB_ERROR_INSTANCE_DELETE_ON_FORM_DISALLOWED) Description You cannot delete an instance from the regular subclass form. Solution Delete the instance using the join form of the class.
120064
Error
The system failed to create a unique identifier. (CMDB_ERROR_CREATE_GUID_FAILED) Description The system was unable to generate a unique identifier. Solution If required, restart your process to generate the GUID.
120065
Warning
Specified attachment pool does not exist. (CMDB_WARN_NO_SUCH_ATTACHMENT_POOL) Description You are attempting to specify an attachment pool that does not exist. Solution Create the attachment pool.
120067
Error
An entry in the import item list is invalid. (CMDB_ERROR_IMPORT_ITEM_ITEM) Description An item in the specified import directory is not available. Solution Make sure that the item exists in the specified directory.
120068
Error
Data type does not match the data type defined for this attribute. (CMDB_ERROR_MISMATCHING_ATTR_DATATYPE) Description The value you specified for the attribute does not match the attribute definition. Solution Specify appropriate values that match the attribute data type definition.
311
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Attribute value does not fall within the limits defined for this attribute. (CMDB_ERROR_ATTRIBUTE_VALUE_OUT_OF_LIMITS) Description The attribute value you specified is not within the defined range for the attribute. Solution Make sure that the attribute value is within the defined range.
120070
Error
Index list is invalid. (CMDB_ERROR_INVALID_INDEX_LIST) Description You specified an invalid index list. Solution Make sure that the index properties that are specified in the error message, are valid.
120071
Error
Setting the form name class characteristic is not allowed. (CMDB_ERROR_SETTING_FORM_NAME_CHARAC_DISALLOWED) Description The Form Name characteristic is an invalid option for the class. Solution You cannot set the form name class characteristic.
120072
Error
The data type for the class characteristic value is invalid. (CMDB_ERROR_INVALID_DATATYPE_FOR_CLASS_CHARAC) Description The value you specified for class characteristic subclasses does not match its datatype. Solution Specify a valid value for the class characteristic.
120073
Error
The namespace name is too long. Must be 70 characters or less. (CMDB_ERROR_NAMESPACE_NAME_TOO_LONG) Description The namespace name you specified cannot exceed its character limit. Solution Specify a namespace name that is 70 characters or less.
312
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The class name is too long. Must be 80 characters or less. (CMDB_ERROR_CLASS_NAME_TOO_LONG) Description The classname you specified cannot exceed its character limit. Solution Specify a class name that is 80 characters or less.
120075
Error
Description The namespace you specified for the subclass does not match its superclass. Solution Specify the same subclass namespace as the superclass. 120076 Error No value supplied for a required attribute. (CMDB_ERROR_REQUIRED_ATTRIBUTE_VALUE_MISSING) Description You did not specify a value for a required attribute. Solution Specify a value for the required attribute. 120077 Error Modifying the namespace name after class creation is not allowed. (CMDB_ERROR_MODIFY_NAMESPACE_NAME_IS_DISALLOWED) Description You cannot modify the namespace name after the class is created. Solution If required, delete this class and create a new one. 120078 Error The supplied character is not allowed in the name. (CMDB_ERROR_CHARACTER_DISALLOWED_IN_NAME) Description You specified invalid characters for the name. Solution Create a name containing the following valid characters: alphanumeric, underscore (_), or period (.)
313
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message The attribute name is too long. Must be 80 characters or less. (CMDB_ERROR_ATTRIBUTE_NAME_TOO_LONG) Description The attribute name you specified cannot exceed its character limit. Solution Specify an attribute name that is 80 characters or less.
120080
Error
Invalid value for the entry mode. (CMDB_ERROR_INVALID_ATTRIBUTE_ENTRY_MODE) Description You specified an invalid value for the entry mode subclasses. Solution Specify one of the valid values: 0-None, 1-Required, 2-Optional, 3-System, or 4-Display_Only.
120081
Error
The subclasses ID is not unique within the class or within the class hierarchy. (CMDB_ERROR_ATTR_subclasses_ID_NOT_UNIQUE) Description The subclasses ID you specified is already in use within the specified class hierarchy. Solution Specify a different subclasses ID.
120082
Error
Invalid data type for the attribute characteristic. (CMDB_ERROR_INVALID_DATATYPE_FOR_ATTR_CHARAC) Description The data type you specified for the attribute characteristic is invalid. Solution Specify one of the valid values: 0-None, 1-View_Perms, 2Change_Perms, 3-Hidden, 4-Primary_Key, 5Propogated_Owner, 6-Create_Mode, 7-Audit_Option, or 8Namespace.
314
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Setting the primary key attribute characteristic is not allowed. (CMDB_ERROR_SETTING_PRIMARY_KEY_CHARAC_DISALLOWED) Description The primary key characteristic is an invalid option for the attribute. Solution You cannot set the primary key attribute characteristic.
120084
Error
Setting the propagated owner attribute characteristic is not allowed. (CMDB_ERROR_SETTING_PROP_OWNER_CHARAC_DISALLOWED) Description The propagated owner characteristic is an invalid option for the attribute. Solution You cannot set the propagated owner attribute characteristic.
120085
Error
The namespace for the relationship end point class does not match the namespace of the relationship class. (CMDB_ERROR_REL_END_POINT_CLASS_NAMESPACE_MISMATCH) Description You are attempting to create a CI instance in a different namespace that the relationship class. Solution Specify a CI instance from the same namespace as the relationship class.
120086
Error
Enum name is invalid. (CMDB_ERROR_ENUM_NAME_INVALID) Description The enum name you specified is invalid. Solution Specify a valid enum name.
120087
Error
Attribute ID is not unique within the class or within the class hierarchy. (CMDB_ERROR_ATTRIBUTE_ID_NOT_UNIQUE) Description You specified an attribute ID that is not unique within the class hierarchy. Solution Specify a unique attribute ID within the class hierarchy.
315
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Invalid data type for the attribute limit structure. (CMDB_ERROR_INVALID_ATTR_LIMIT_DATA_TYPE) Description You specified an invalid value for the attribute limit structure. Solution The data type for the attribute limit structure must either match the data type of the attribute or be NULL.
120089
Error
You do not have access to the class. (CMDB_ERROR_NO_ACCESS_TO_CLASS) Description You do not have permissions to access the class. Solution Contact your CMDB system administrator.
120090
Error
You do not have access to the attribute. (CMDB_ERROR_NO_ACCESS_TO_ATTRIBUTE) Description You do not have permission to the access the attribute. Solution Contact your CMDB system administrator.
120092
Error
The dataset ID and Reconciliation Identity combination is not unique. (CMDB_ERROR_DATASET_ID_RECON_ID_NOT_UNIQUE) Description The combination of reconciliation ID and dataset ID is not unique. Solution Change one of these values to make the combination unique.
120094
Error
The direction provided for graph query is not valid. (CMDB_ERROR_QUERY_GRAPH_INVALID_DIRECTION) Description You specified an invalid direction value for the graph query. Solution Specify one of the valid values: 0-Direction_Out, or 1Direction_In.
316
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Current object store API version is deprecated. (CMDB_ERROR_CURRENT_API_IS_DEPRECATED) Description You are attempting to use an API call that is now deprecated. Solution Upgrade to the current version of the CMDB API.
120096
Warning
Instances skipped during import. (CMDB_WARN_IMPORT_INST_SKIPPED) Description This is a warning that certain instances were not imported during the import activity.
120097
Information
Instance import summary. (CMDB_INFO_IMPORT_INST_SUMMARY) Description This message signifies that the instance import summary follows.
120098
Error
Description You specified an invalid delete option for the class. Solution Specify one of the valid values: CMDB_DELETE_CLASS_OPTION_NONE, CMDB_DELETE_CLASS_OPTION_WITH_DATA, or CMDB_DELETE_CLASS_OPTION_ALL_DEPENDENCIES. 120099 Error The metadata status value specified is invalid. (CMDB_ERROR_INVALID_META_DATA_STATUS) Description You specified an invalid value for the metadata status. Solution Specify one of the valid values:
CMDB_META_DATA_STATUS_DELETE_PENDING or CMDB_META_DATA_STATUS_CHANGE_PENDING.
317
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message One of the endpoints specified for the relationship has an invalid class ID. (CMDB_ERROR_INVALID_REL_ENDPOINT_CLASS_ID) Description You specified an invalid class ID for one of the CI instances in the relationship. Solution Specify a valid class ID for the instance.
120101
Error
Internal system error. (CMDB_ERROR_ACCESS_TLS_BLOCK_FAILED) Description Access to thread local storage block failed. Solution Contact your CMDB system administrator.
120102
Error
A version string in the SHARE:Application_Properties form is invalid. (CMDB_ERROR_UNRECOGNIZED_VERSION_PATCH_STRING) Description The version string for the CMDB patch is invalid. Solution Replace the patch string with a valid version string.
120103
Error
Cascade Delete cannot be enabled for the relationship because its cardinality is invalid for cascade deletes. (CMDB_ERROR_INVALID_CASCADE_DELETE_VALUE) Description You specified an invalid cascade delete option for the relationship. Solution Specify a cardinality of one-to-many or one-to-one for the relationship.
120104
Error
Description An internal error has caused your reconciliation job to fail. Solution Contact BMC technical support for help.
318
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Description An internal error has caused an unsuccessful cancellation of your reconciliation job. Solution Contact BMC technical support for help. 120107 Error Failed to cancel a job not running.
(CMDBRE_ERROR_JOB_NOT_RUNNING)
Description You are attempting to cancel a job that is not running. Solution Before you cancel a job, make sure that the job is running. 120108 Error Failed to find the specified job.
(CMDBRE_ERROR_JOB_LOOKUP)
Description The job you are referring to does not exist. Solution Make sure that the associated job ID is correct. 120109 Error Failed to start an inactive job. (CMDBRE_ERROR_INACTIVE_JOB_START) Description You are attempting to start an inactive job. Solution A job must be in an active state before you start the it. 120110 Error Job does not exist.
(CMDBRE_ERROR_JOB_NOT_EXIST)
Description The job you are referring to does not exist. Solution Make sure that the job exists.
319
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Description You cannot start a job that is already running. Solution Please wait until the currently running job is completed. 120113 Error Number of IDs and Values does not match.
(CMDB_ERROR_ENUM_ID_VALUE_LEN_MISMATCH)
Description The number of IDs and their values you specified do not match. Solution Make sure that the number of IDs and the values match. 120114 Error Invalid Enum ID.
(CMDB_ERROR_ENUM_ID_INVALID)
Description You have specified an invalid Enum ID. Solution Make sure that the Enum ID is valid. 120116 Error The session ID in the supplied control structure is invalid.
(CMDB_ERROR_INVALID_AUDIT_COPY_TYPE)
Description The session ID that you specified for the login information is invalid. Solution Make sure that the control structure is correct and your API session is properly initialized. 120117 Error
(CMDB_ERROR_INVALID_AUDIT_LOG_TYPE)
Description If you specified the Copy audit option for your derived class, its superclasses cannot contain the Log audit option setting. Solution Make sure that the superclass and subclasses have the same audit option settings.
320
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Description The dataset ID you specified for the instance is invalid. Solution Perform the Set, Create, Delete operations. If the DatasetId attribute value is given in the attribute value list, make sure that the ID is the same as the DatasetId passed as parameter to the API call. 120121 Error The dataset ID does not exist.
(CMDB_ERROR_NO_SUCH_DATASET)
Description The dataset ID you specified does not exist. Solution Make sure that the If instance for the dataset ID you specified exists in the BMC.CORE:BMC_Dataset class. If the problem persists, restart the AR System server. 120122 Error The source dataset ID is missing.
(CMDB_ERROR_DATASET_OVERLAY_SOURCE_MISSING)
Description You did not specify the source dataset ID. Solution Make sure that the source dataset for the dataset provided exists. 120123 Error An internal error occurred.
(CMDB_ERROR_DATASET_UNDERLAY_INTERNAL_ERROR)
Description The specified class ID and reconciliation ID for the underlay dataset do not exist. Solution Make sure the specified class ID and reconciliation ID exist.
321
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Description You are attempting to access a dataset for which you do not have appropriate access. Solution Make sure that the access for the dataset is not set to read-only or writable by the client type. 120125 Warning Federated data corruption.
(CMDB_WARNING_DATASET_CACHE_LOADING)
Description An internal error occurred when accessing federated data. Solution Contact your CMDB system administrator. 120126 Error Federation foreign key expansion failed.
(CMDB_WARNING_FOREIGN_KEY_EXPAND_FAILED)
Description An error occurred when attempting to expand a federated link. Solution Make sure that the federated foreign key link has the appropriate BMC_FederatedKeyLink class name. 120127 Error The session ID in the supplied control structure is invalid.
(CMDB_ERROR_BULK_TRAN_API_SESSION_ID_BAD)
Description The API session information that you specified in the bulk transaction function is incorrect. Solution Make sure that the control structure is correct and that your API session is properly initialized.
322
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Cannot start another bulk transaction because a bulk transaction has already been started.
(CMDB_ERROR_BULK_TRAN_ALREADY_BEGUN)
Description You cannot start more than one bulk transaction function at a time. Solution Make sure no other bulk transaction function is in progress. 120129 Error The attempted operation cannot be performed because the bulk transaction has not started.
(CMDB_ERROR_BULK_TRAN_NOT_BEGUN)
Description You are attempting to perform a bulk transaction operation before starting a bulk transaction session. Solution The attempted operation can only be performed once a bulk transaction session is started. 120130 Error Failed to promote class, which has abstract superclass.
(CMDB_ERROR_SUPERCLASS_OF_TYPE_ABSTRACT)
Description You are attempting to promote a class that is derived from an abstract class. Solution You cannot promote a class that is derived from an abstract class. 120131 Error Federation launch failed.
(CMDB_ERROR_FEDLINK_LAUNCH_FAILED)
Description The federation link that you are attempting to launch failed. Solution Contact your CMDB system administrator.
323
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Description The superclass you specified is not found. Solution Make sure that the specified superclass exists. 120133 Error The CMDB RPC port specified is invalid.
(CMDB_ERROR_RPC_SOCKET_RANGE)
Description The RPC port that you specified for the BMC Atrium CMDB is invalid. Solution Specify a valid CMDB RPC port number. Valid port numbers include: 0, 390696, or 390697 (Admin thread). 120134 Error Failed to parse the qualification.
(CMDB_ERROR_FAILED_TO_RUN_QUALIFICATION)
Description The application failed to parse the specific qualification. Solution Correct the qualification based on the error message description provided. 120136 Error The requested object was not found in the import buffer. (CMDB_WARNING_REQUESTED_IMPORT_OBJECT_NOT_FOUND) Description The import item list object (class or attribute) that you requested does not exist in the .xml (import) file. Solution Make sure that the requested import object (class or attribute) exists in the .xml (import) file.
324
Developers Reference Guide Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Cannot import instance because the instance ID already exists.
(CMDB_ERROR_INSTANCE_ID_ALREADY_EXISTS)
Description The instance ID you specified already exists. Solution Make sure you specify a unique instance ID for the instance or select an import option other than 1. 120138 Error Invalid import data option.
(CMDB_ERROR_INVALID_DATA_IMPORT_OPTION)
Description The import option value you specified is incorrect. Solution Make sure you select the correct import option. 120139 Error The CoreDatasetId specified already exists.
(CMDB_ERROR_DUPLICATE_DATASET_ID)
Description The CoreDatasetId you specified already exists. Solution Specify a different CoreDatasetId. 120140 Error Attribute does not belong to the class specified.
(CMDB_ERROR_ATTRIBUTE_BELONGS_TO_SUPERCLASS)
Description The attribute you specified is inherited from a superclass and cannot be deleted from this subclass. Solution Delete the specified attribute from the superclass.
325
BMC Atrium CMDB 2.0.1 Table 7-1: BMC Atrium CMDB C API Error Messages
Error message Cant set MarkAsDeleted to No on the relationship instance because one or both of the relationship endpoints are MarkAsDeleted. (CMDB_ERROR_REL_ENDPOINT_MARK_AS_DELETED) Description You are attempting to set MarkAsDeleted to No for a relationship instance whose one or both endpoints are still soft deleted. (MarkAsDeleted) Solution Make sure you set MarkAsDeleted to No on both endpoints of the relationship before setting MarkAsDeleted to No on the relationship instance.
120142
Error
Description You are attempting to retrieve Copy audit data from a class whose audit type is set to a value other than Copy. Solution You cannot retrieve Copy audit data from a class whose audit type is set to a value other than Copy. 120145 Error Class ID and qualification information exceeded the limit of 4096 bytes.
(CMDB_ERROR_RE_START_JOB_RUN_INFO_EXCEED_LIMIT)
Description The combined length of the classQualList and datasetList parameters you specified exceeds 4096 bytes after encoding the qualification. Solution Divide the classQualList information into more than one API calls.
326
Error message Qualification for the Where clause not defined. Description You cannot leave the attribute, operator, and value fields empty when specifying a qualification for the instance search. Solution Make sure you specify the required fields for the qualification.
13003
Error
Qualification for the search operation not defined. Description You cannot search instances unless you specify the Where clause qualification, such as the attribute, operator, and value for the search. Solution Make sure you specify the Where clause qualification for the instance search.
13010
Error
Search name not defined. Description You are attempting to save a search without specifying a search name for it. Solution Make sure you specify a name for the search that you want to save.
13015
Error
Auditing not enabled for any class. Description The Audit option is not enabled for any class in the CDM. To view audit history, at least one class must be audit enabled. Solution Contact your CMDB system administrator to make sure the Audit option for classes is enabled both at the class and attribute level.
327
BMC Atrium CMDB 2.0.1 Table 7-2: CMDB Console active link error messages
Error message Instance not selected for viewing audit history. Description You did not select the instance for which the audit history is to be displayed. You can view audit history for only one instance at a given time. Solution Make sure you select an instance for the viewing the audit history.
13201
Error
Instances not selected for the comparison. Description You did not select the instances that you want to compare. You must select only two instances at a given time for the comparison. Solution Make sure you select two instances for the comparison.
13202
Error
A saved search with the specified name already exists. Description The name you specified for the search is already in use. Solution Make sure you specify a unique name for saving the search.
13203
Error
A Public saved search with the specified name already exists. Description The name you specified for the Public search is already in use. Solution Make sure you specify a unique name for saving the Public search.
13204
Error
You do not have access to any audited entry for this instance. Description You are attempting to view the audit history of the instance. You do not have access permissions to perform this operation. Solution Contact your CMDB system administrator.
328
Developers Reference Guide Table 7-2: CMDB Console active link error messages
Error message There is no audited entry for this instance. Description The instance for which you want to view audit history has no data. Solution Make sure there is data for the specific instance.
20152
Warning
OBJSTR:OnCancel_Cancel_Close/Undisplay Close operation canceled. No changes were saved. Description Your changes were not saved. Solution To save your changes before closing a form, use the Cancel button.
44000
Error
OBJSTR:Help_OpenHelpFile Online Help has not been installed. Description You have not installed the BMC Atrium CMDB 2.0 Help. Solution To install the online Help, see the Installation and Configuration Guide.
120065
Error
OBJSTR:AttributeDef_CheckCustomSelection You must provide ID Values for a Custom Selection. Description You did not specify ID values for the field values when creating a custom selection field. Solution Make sure you specify ID values for the custom selection field.
125000
Error
OBJSTR:AttributeDef_OnLoseFocus_subclassesID Invalid subclasses ID. The field ID you specified for the attribute is greater than the maximum value of a 32-bit signed integer data type. Solution Make sure that the field ID is less than or equal to 2147483647.
329
BMC Atrium CMDB 2.0.1 Table 7-2: CMDB Console active link error messages
Error message OBJSTR:AttributeDef_OnSelect_CharacteristicsTab01 Please specify Data Type. Description You did not specify a data type for a field on the Characteristics Tab. Solution Make sure you specify a data type for the field.
125003
Error
OBJSTR:AttributeDef_OnSelect_CharacteristicsTab02 Please specify Data Type. Description You did not specify the data type for a field on the Characteristics tab. Solution Specify a data type for the Characteristics tab.
125004
Error
OBJSTR:AttributeDef_OnSelect_CharacteristicsTab03 Please specify Data Type. Description You did not specify the data type for a field on the Characteristics tab. Solution Specify a data type for the Characteristics tab.
125005
Error
OBJSTR:AttributeDef_OnSelect_CharacteristicsTab04 Please specify Data Type. Description You did not specify the data type for a field on the Characteristics tab. Solution Specify a data type for the Characteristics tab.
125005
Error
OBJSTR:AttributeDef_OnSelect_CharacteristicsTab05 Please specify Data Type. Description You did not specify the data type for a field on the Characteristics tab. Solution Specify a data type for the Characteristics tab.
330
Developers Reference Guide Table 7-2: CMDB Console active link error messages
Error message OBJSTR:ClassDef_Attrib_AddSearchBtns_CheckForClassAndName space_Msg Namespace and Class Name must be entered before you can add or search attributes. Description You did not specify a namespace and classname for the attribute. Solution Make sure that you specify a namespace and classname.
125007
Error
OBJSTR:ClassDef_ChkDuplicateClass02 There is already an existing class with class name $490001100$ in the namespace $400109900$. Description The class name you specified is not unique within the class namespace. Solution Specify a different name for your class.
125008
Error
OBJSTR:ClassDef_ChkSuperclassIsNotFinalClass02 Invalid superclass. Class $400103900$ is a final class and cannot be used as a superclass. Description You are attempting to derive a subclass from a final class. Solution You cannot derive a subclass from a final class.
125009
Error
OBJSTR:ClassDef_OnSaveChkReqsubclasses Namespace and Class Name are required subclasses. Description You did not specify the classname and namespace attributes for the subclass. Solution Make sure you specify the classname and namespace attributes.
331
BMC Atrium CMDB 2.0.1 Table 7-2: CMDB Console active link error messages
Error message OBJSTR:ClassDef_OnSaveChkReqsubclassesForRelationship Class 1, Class 2, Role 1, Role 2, and Association Enforcement are required subclasses for relationship classes. Description You did not specify the required attributes for the relationship class. Solution Make sure you specify these values before saving.
125012
Error
OBJSTR:IdxCon-AttribAlreadyExist This attribute is already part of the Index. Description You are attempting to specify an attribute for the index that is already in use. Solution Specify a different attribute.
125013
Error
OBJSTR:IdxCon-GainFocusProperty_tbl Please enter the Index Name first. Description You must specify a name for the index before you create it. Solution Specify an index name.
125014
Error
OBJSTR:IdxCon-IndexNameLooseFocus01a There is already an index by the name of: $400111200$. Please use a different name. Description You are attempting to specify an attribute for the index that is already in use. Solution Specify a different attribute.
332
Developers Reference Guide Table 7-2: CMDB Console active link error messages
Error message OBJSTR:WRdlg-cmdMapWeakRel01 Please select an Attribute from Class 1 and Class 2. Description You did not specify the attribute that you want to propagate in the weak relationship. Solution You must specify an attribute from Class 1 and Class 2.
125029
Error
OBJSTR:WRdlg-cmdMapWeakRel02 Invalid data type mismatch. You can only map Attributes with the same data type. Description The data types of the attributes you specified do not match. Solution Make sure that the data types of the attributes match.
125030
Information
OBJSTR:AttributeDef_SaveChanges Attribute '$400009700$' has been saved. Description The attribute number specified in the message is saved.
125036
Error
AL: OBJSTR:ClassDef_OnSave_ValidateCategSubClass You must specify a superclass when creating a categorization class. Description You are attempting to create a categorization class without specifying its superclass. Solution Make sure that you specify a superclass for the categorization class.
333
Error message OBJSTR:Lookup Association Name5 No entry found in SHARE:AssociationType with associationTypeId = $500000041$. Description The association type you specified is not found. Solution Make sure that the association type exists.
20279
Error
BSM:AUD_AssocEnforce1-1Relationship 2 The relationship $490005100$ between $490021100$ and $490021101$ is defined as 1 to 1, and there is already an association of type $490005100$ between this $490021101$ and another $490021100$, or between this $490021100$ and another $490021101$. Description You are attempting to create a relationship for an instance that is already related to another instance. Solution Make sure that the instance name is correct. If you need to create more than one relationship for the specified instance, make sure you specify a many-to-one or one-to-many cardinality for it.
20280
Error
BSM:AUD_AssocEnforce1-ManyRelationship 2 The relationship $490005100$ between $490021100$ and $490021101$ is defined as 1 to Many, and there is already an association of type $490005100$ between this $490021101$ and another $490021100$. Description You are attempting to create a relationship for an instance that is already related to another instance. Solution Make sure that the instance name is correct. If you need to create more than one relationship for the specified instance, make sure you specify a many-to-one or one-to-many cardinality for it.
334
Developers Reference Guide Table 7-3: CMDB Console filter error messages
Error message BSM:AUD_AssocEnforceMany-1Relationship 2 The relationship $490005100$ between $490021100$ and $490021101$ is defined as Many to 1, and there is already an association of type $490005100$ between this $490021100$ and another $490021101$. Description You are attempting to create a relationship for an instance that is already related to another instance. Solution Make sure that the instance name is correct. If you need to create more than one relationship for the specified instance, make sure you specify a many-to-one or one-to-many cardinality for it.
20366
Error
OBJSTR:Lookup Localized String5 No entry found in SHARE:MenuItem_LT with Developer Name = $300132000$. Description The localized string for the menu item is not found. Solution Contact your CMDB system administrator.
20369
Error
OBJSTR:Lookup Form Name5 No entry found in SHARE:Object with Form Name = $-5$. Description The form name you specified is not found. Solution Contact your CMDB system administrator.
50030
Error
OBJSTR:Instance_CheckAbstractClassNoInstantiate Invalid instance related operation on this abstract class. Description You cannot derive an instance from an abstract class. Solution Make sure that the superclass name you specified for the instance is correct.
335
BMC Atrium CMDB 2.0.1 Table 7-3: CMDB Console filter error messages
Error message OBJSTR:Instance_CheckSingleton02 Class $400124700$ is a Singleton class and can only have one instance. Description You cannot derive more than one instance from a singleton class. Solution Make sure that the class name you specified for the singleton class is correct.
50040
Error
OBJSTR:Instance_CheckRelationshipEndpoint<endpoint number> The role <number> instance does not exist. The Class ID and Instance ID combination was not found. Class ID: $490008100$, Instance ID: $490008000$. Description The instance ID specified in the role <number> for the specified class is not found. Solution Make sure that the Instance ID for the specified Class ID exists.
50044
Error
OBJSTR:Instance_RelWeakRef:<class name>:<step number> Weak relationship instance cannot be created. Weak instance is already associated to another lead instance. Description You cannot assign the specified instance as a weak instance more than once. This instance is already a part of another weak relationship. Solution Make sure that the instance name you specified for the weak instance is correct.
50046
Error
OBJSTR:Instance_RelWeakRef:BMC:<class name>:<step number> Modifications to the lead class references values are not allowed. Description You are attempting to modify the reference values of the lead class in a weak relationship. Solution Make sure you do not modify the reference values for the lead class.
336
Developers Reference Guide Table 7-3: CMDB Console filter error messages
Error message OBJSTR:Instance_CheckDeleteOp Instances cannot be deleted from this form. Description You cannot delete an instance from the instance base form. Solution Make sure you are using the join form to delete the instance.
125016
Error
OBJSTR:AttributeDef_CheckForDupsubclassesID_Msg Duplicate subclasses ID $400004800$ for attribute $400009700$. Description The field ID you specified for the attribute is already in use in the class. Solution Make sure you specify a different field ID.
125016
Error
OBJSTR:AttributeDef_CheckForDupsubclassesName_Msg Duplicate subclasses Name for attribute $400009700$. Description The field name you specified for the attribute is already in use in the class. Solution Make sure you specify a different field name.
125017
Error
OBJSTR:AttributeDef_CheckRequiredsubclasses Data Type and Attribute Name must be specified. Description Data type and attribute name are required fields for the subclass. Solution Make sure you specify values for these required fields.
337
BMC Atrium CMDB 2.0.1 Table 7-3: CMDB Console filter error messages
Error message OBJSTR:AttributeDef_CheckReservedsubclassesID Invalid subclasses ID for attribute $400009700$. Subclasses IDs below 100 are reserved for Core subclasses. Description The ID you specified for the subclass is a reserved value. Solution Make sure that the ID you specify is not a system-reserved value. For more information about reserved values, see the cmdb.h header file.
125019
Error
OBJSTR:AttributeDef_CheckSelectionDefaltValue Invalid Default Value for selection subclasses. Description The default value you specified for the subclass is invalid. Solution Make sure that you specify a default value from the list of approved values.
125020
Error
OBJSTR:Class_ChkDuplicateClass02 There is already an existing class with class name $490001100$ in the namespace $400109900$. Please specify a different class name. Description The class name and namespace combination that you specified for the class is not unique. Solution Make sure that the class name is unique within the specified namespace.
125021
Error
OBJSTR:Class-ChkAbstractFinal This is an invalid combination of the Abstract and Final subclasses. Description You are attempting to derive a subclass as an abstract and final class. Solution Make sure you specify only one class type for the subclass.
338
Developers Reference Guide Table 7-3: CMDB Console filter error messages
Error message OBJSTR:Instance_Enforce1-1Relationship02 The relationship between $400126800$ and $400126900$ is defined as 1 to 1, and there is already a relationship instance between $400126800$ and $400126900$. Description The relationship cardinality for the specified instances is violated. Solution Make sure that you do not specify more than one relationship between the two instances.
125026
Error
OBJSTR:Instance_Enforce1-ManyRelationship02 The relationship between $400126800$ and $400126900$ is defined as 1 to Many, and there is already a relationship instance between $400126800$ and $400126900$. Description The relationship cardinality for the specified instances is violated. Solution Make sure that you do not specify more than one relationship between the two instances.
125027
Error
OBJSTR:Instance_EnforceMany-1Relationship02 The relationship between $400126800$ and $400126900$ is defined as Many to 1, and there is already a relationship instance between $400126900$ and $400126800$. Description The relationship cardinality for the specified instances is violated. Solution Make sure that you do not specify more than one relationship between the two instances.
125033
Error
OBJSTR:AttributeDef_CheckSpaceInName02 Spaces are not allowed in the Attribute Name Field. Description You are attempting to create an attribute name that has a blank character. Solution Make sure you create attribute name fields with no space or wildcard characters.
339
BMC Atrium CMDB 2.0.1 Table 7-3: CMDB Console filter error messages
Error message OBJSTR:Class_CheckSpaceInName02 Spaces are not allowed in the Class Name Field. Description You are attempting to create a class name that has a blank character. Solution Make sure you create class name fields with no space or wildcard characters.
125035
Error
OBJSTR:Class_CheckSpaceInSuperClass02 Spaces are not allowed in the Superclass Field. Description You are attempting to create a superclass field that has a blank character. Solution Make sure you create superclass fields with no space or wildcard characters.
340
Appendix
This appendix explains the CI Relationship Viewer events that you can use to transfer data to an AR System form. The CI Relationship Viewer provides the following types of events for data transfer with AR System forms. The following topics are provided:
! !
Events from AR System to CI Relationship Viewer (page 342) Events from CI Relationship Viewer to AR (page 344)
341
The possible Event Types and the Event Data required for them are explained in the following sections. For more information about the Run Process workflow action, see BMC Remedy Action Request System 7.0 Workflow Objects.
CIRV_SET_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
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.AS0050560C63F28d6HQQ YFQGAAKQAA
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>
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>
343
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>
Appendix
Representing graphs (page 346) The CMDBGraphQuery API function (page 347)
Note: Though this section does not discuss specific elements of the Java API and web services API, the concepts and strategies discussed here are the same for it as they are for the C API. To apply these concepts and strategies to a graph query with the Java API, see the Java documentation installed in the sdk/doc/javadoc/cmdbapi/ subdirectory of your BMC Atrium CMDB installation directory.
For more information about the web services graph query operation, see Chapter 6, Web services API operations and data structures.
345
Representing graphs
There are two standard ways to represent a graph G = ( V, E ) 1: as a collection of adjacency lists or as an adjacency matrix. The adjacency-list representation is usually preferred, because it provides a compact way to represent sparse graphsthose 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 undirected2 graph in Figure B-1 (a).
Figure B-1: Undirected graph and its equivalent adjacency list
V stands for vertices, E stands for edges. 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.
2
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
347
BMC Atrium CMDB 2.0.1 Figure B-3: Graph of data to use with example queries
Example 1
You want to start on a CI instance of class A:A with instance ID 1 and walk relationships of class A:rAA, which is defined as a relationship with A:A instances on both ends. You want to walk outward to the last level, so the value of the numLevels argument will be -1. 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 350 shows the data structures of the queryGraph argument for Figure B-4 (a). Figure B-6 on page 351 shows the data structures of the queryGraph argument for Figure B-4 (b).
349
BMC Atrium CMDB 2.0.1 Figure B-5: queryGraph data structures for Figure B-4 (a)
Developers Reference Guide Figure B-6: queryGraph data structures for Figure B-4 (b)
The path taken to walk this graph is shown by the bolded relationships in Figure B-7 on page 352. The bolded nodes are those returned in the objects list.
351
BMC Atrium CMDB 2.0.1 Figure B-7: Path walked and nodes returned by Query Example 1
Seven CI instances of A:A with instance IDs 2, 3, 8, 4, 5, 6, and 7. Eight relationship instances of A:rAA with instance IDs 1, 2, 3, 4, 5, 9, 6, and 7.
Example 2
You want to start on a CI instance of class A:A with instance ID 1 and walk relationships of class A:rAB, which is defined as a relationship with an A:A instance on the left and an A:B instance on the right. From A:B you want to walk relationship A:rBA which has class A:B on the left and class A:A on the right. You want to walk outward to the last level, so the value of the numLevels argument will be -1. 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 354 shows the data structures of the queryGraph argument for Figure B-8 (a). Figure B-10 on page 355 shows the data structures of the queryGraph argument for Figure B-8 (b).
353
BMC Atrium CMDB 2.0.1 Figure B-9: queryGraph data structures for Figure B-8 (a)
Developers Reference Guide Figure B-10: queryGraph data structures for Figure B-8 (b)
The path taken to walk this graph is shown by the bolded relationships in Figure B-11 on page 356. The bolded nodes are those returned in the objects list.
355
BMC Atrium CMDB 2.0.1 Figure B-11: Path walked and nodes returned by Query Example 2
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.
357
Glossary
abstract class attribute
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
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
An entity or party whose data is represented in the BMC Atrium CMDB, and to whom specific levels of permission can be granted. Specifying instance permission by account enables the BMC Atrium CMDB to support multitenancy.
activity
Permission to view or change the value in the attribute for any instance, assuming valid instance permissions.
attribute substitution
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.
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
The concept of prioritizing IT efforts to supports the overall goals of the business.
Glossary
359
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
A message sent to the CI Relationship Viewer from AR System workflow to change its settings. The CI Relationship Viewer can also send AR System events.
CIM
To automatically delete, or mark as deleted, the destination member of a relationship when the source member is deleted or marked.
Categories, Types, and Items (CTI)
A method formerly used for categorizing assets in BMC Remedy Asset Management. Category, Type, and Item are each an attribute on the BMC_BaseElement class, so you can use CTIs in the BMC Atrium CMDB.
categorization class
Metadata in the BMC Atrium CMDB that defines a type of object, usually a configuration item (CI) or relationship. Either of these types of class can store data as a regular class, categorization class, abstract class, or abstract class with data replication. You can apply the final class and singleton class options to it as well.
Class Manager
A class that does not have its own AR System form, but stores its instance data in the form of its superclass, preventing the need for a database join.
CDM
A component of the BMC Atrium CMDB where you can view, create, modify, and delete the classes and attributes that make up the data model, as well as view a list of subclasses for each class.
class permissions
See destination.
CI
Permission to view instances of a class in the BMC Atrium CMDB interface or access them with AR System workflow.
CMDB
A class that defines a type of configuration item (CI), such as a computer system or software application.
CI Relationship Viewer
The main user interface of the BMC Atrium CMDB, accessible from both web and BMC Remedy User clients.
CMDB Console User
A component of the BMC Atrium CMDB that graphically displays the relationships between CIs. It can also be embedded in other AR System-based applications.
An application role. Members can perform searches from the CMDB Console and view federation definitions.
360 Glossary
cmdbdriver
An application role. Members can perform searches from the CMDB Console, view, create, and modify federation definitions, and perform CMDB Console administrative tasks.
CMDB Data Change
A utility that executes BMC Atrium CMDB C API functions from a command line, prompting for parameters.
Common Data Model (CDM)
An application role. Members can view, create, and modify instances if they have row-level security.
CMDB Data Change All
An application role. Members can view, create, and modify instances independent of row-level security.
CMDB Data View
The object-oriented, hierarchical set of classes in the BMC Atrium CMDB used to represent types of CIs and relationships. The CDM is based on industry standards such as the Common Information Model (CIM) and Microsofts Windows Management Instrumentation.
Common Information Model (CIM)
An application role. Members can view instances if they have row-level security.
CMDB Definitions Admin
A definition of management information developed by the Distributed Management Task Force (DMTF) that facilitates the exchange of management information between systems.
Comparison activity
An application role. Members can view, create, modify, and delete classes.
CMDB Definitions Viewer
A Reconciliation Engine activity that compares identified instances between two datasets, either producing a report that shows the differences or executing workflow.
configuration data
An application role. Members can view, create, modify, and delete reconciliation definitions and can start and cancel jobs.
CMDB RE Manual Identification
A physical, logical, or conceptual entity that is part of your IT environment and has configurable attributes. Examples include computer systems, buildings, employees, software, and business services. One of the two types of classes in the BMC Atrium CMDB. See also relationship.
Configuration Management Database (CMDB)
An application role. Members can view reconciliation definitions and can start and cancel jobs.
A database that stores information about your IT configuration, including both CIs and relationships.
Glossary
361
consumer
An application that works with data in the BMC Atrium CMDB. It might view the data or modify it. See also provider.
Copy Dataset activity
A Reconciliation Engine activity that copies instances from one dataset to another.
CTI
A repository where approved software configurations are stored. Installed instances of the software can be checked against the DSL for compliance with licenses and policies.
Delete Dataset activity
An option for abstract classes. With this option, the instances of all subclasses are replicated to a single form to allow you to search the abstract class as though it had data. Only the attributes inherited from the abstract class are replicated.
dataset
A Reconciliation Engine activity that deletes instances from one or more datasets without removing the dataset itself. See also cascading delete, hard delete, and soft delete.
destination
The CI class defined as Class 2 in a relationship class, or an instance of that CI class as a member of such a relationship. Also known as the child member or weak member.
discovery
A logical group of data in the BMC Atrium CMDB. A dataset can represent data from a particular source, a snapshot from a particular date, or other purpose. The dataset used by BMC Software products for reconciled production data is named BMC Asset. See also overlay dataset.
Dataset Merge Precedence
An application that scans your environment for configuration data and can act as a provider to the BMC Atrium CMDB.
Distributed Management Task Force (DMTF)
A pairing of a dataset with a Precedence group. Each Merge activity references a collection of these, called a Dataset Merge Precedence set.
defined dataset
An organization appointed to facilitate the exchange of management information by promoting the initiation of industry standards and interoperability.
DMTF
One of a pair of dataset IDs that is specified when executing a job with dynamic dataset substitution. The job is executed with the working dataset in place of the defined dataset.
362 Glossary
federated interface
The BMC Remedy Enterprise Integration Engine is a product that enables you to transfer large amounts of data between third-party data sources and both the AR System and BMC Atrium CMDB.
event
An instance of the
BMC_FederatedInterface class that
specifies how to access a particular type of federated data. See also federated link.
federated link
A particular type of change to the instances of specified classes. You can publish an event so that any instance of it is written to the CMDB:Events form. You can receive notification each time an instance of the event occurs by polling the form. See also CI Relationship Viewer event.
Exclusion rule
A product that holds federated data. It can be linked to more than one federated interface.
federation
The act of linking CIs in the BMC Atrium CMDB to external data.
Federation Manager
A component of the BMC Atrium CMDB that you can use to manage federated data. From the Federation Manager, you can view, create, and modify federated products, federated interfaces, and federated links.
filter
A logical set of classes and attributes, usually in its own namespace, that is not part of the Common Data Model (CDM).
extension loader
A set of criteria for restricting the information displayed by the CI Relationship Viewer. This is different from an AR System filter.
final class
The cmdbExtLoader program, which is used for installing data model extensions and importing other BMC Atrium CMDB data and metadata.
federated data
Data linked from CIs in the BMC Atrium CMDB but stored externally. Federated data might represent more attributes of the CIs or related information such as change requests on the CIs.
A method of federation that assigns a key from the federated product to each linked CI. Foreign key substitution is useful when no attributes that also exist in the BMC Atrium CMDB are stored in the federated product.
Glossary
363
group
incident
A set of a particular type of reconciliation definition that is referenced by an activity. See also Identification group, Precedence group, Qualification group, Workflow Execution group.
GUID
Defined by ITIL as any event that is not part of the standard operation of a service and which causes, or might cause, an interruption to, or a reduction in, the quality of that service.
instance
A globally unique identifier, automatically generated by the AR System server. GUIDs are used for instance IDs, reconciliation IDs, and other cases where a unique value is needed without human interaction.
hard delete
An actual incarnation of a particular class, represented as a record in the BMC Atrium CMDB. Both CIs and relationships are instances of their respective classes.
instance ID
A GUID that the BMC Atrium CMDB applies to each instance to uniquely identify it.
instance permissions
A Reconciliation Engine activity that matches instances from two or more datasets and assigns them the same identity, meaning that they represent the same reallife object.
Identification group
The right to view or modify a specific instance. These permissions are called rowlevel security and write security, respectively.
ITIL
A set of Identification rules that collectively identify instances from a particular dataset against other datasets. Each dataset that participates in an Identification activity is paired with one Identification group.
Identification rule
The Information Technology Infrastructure Library (ITIL) is an internationally accepted set of best practices for management of IT services developed by the British government
job
A rule used when identifying instances between datasets. When two instances match the qualification for the rule, they are assigned the same reconciliation ID.
identity
A group of one or more reconciliation activities executed in sequence. You cannot run an activity by itself; only as part of a job. You can start a job manually, with a schedule, with an Execute Job activity, with workflow, or with an API program.
Merge activity
A Reconciliation Engine activity that merges two or more datasets into a single complete and correct dataset based on precedence values that favor the strengths of each dataset.
364 Glossary
metadata
production dataset
Definitions that describe the data stored in the BMC Atrium CMDB. Metadata includes classes in the data model and special classes to define things such as datasets and federation objects.
multitenancy
The dataset that serves as the single source of reference for your organization and from which you make business decisions. It acts as the target dataset in most Merge activities.
provider
The separation of data and access so that a single BMC Atrium CMDB can contain the data of multiple parties, but each party can access only their own data. See also account and role.
namespace
An application, often a discovery application, that loads bulk data into the BMC Atrium CMDB. See also consumer.
provisioning
A logical set of classes and attributes in the data model, usually related to a specific consumer or provider. The Common Data Model (CDM) uses the BMC.CORE namespace.
overlay dataset
The process of providing access to resources, such as printers, telephones, and such, and to information, such as permissions, databases, and so on.
publish
To make an event available so that instances of it can be written to the CMDB:Events form.
Purge Dataset activity
A dataset that provides a layer in which to make changes that are pending approval. API queries to the dataset seamlessly return its modified instances along with unmodified instances from the underlying regular dataset.
parent
A Reconciliation Engine activity that removes instances that have been marked as deleted from one or more datasets.
Qualification
See source.
Precedence group
A Boolean statement that is evaluated to determine whether an instance should be included in an activity.
Qualification group
The definition of an overall precedence value for a dataset. It can optionally contain precedence values for specific classes and attributes within the dataset.
precedence value
A set of Qualifications that can be used in various types of activity. An instance that meets one or more Qualifications in the group is included in the activity.
reconciliation
A method of assigning weight to specific datasets, classes, and attributes in a Merge activity. Attribute precedence values override class precedence values, which override dataset precedence values.
The process of managing data in multiple datasets using the Reconciliation Engine. The main activities of reconciliation are identifying, comparing, and merging datasets, though the Reconciliation Engine performs other activities as well.
Glossary
365
reconciliation definition
role
The component of the BMC Atrium CMDB that reconciles data from different datasets.
reconciliation ID
The permission required to view a specific instance. See also write security.
rule
A GUID that the Reconciliation Engine assigns to instances in different datasets that represent the same real-life object.
Reconciliation Manager
The component of the BMC Atrium CMDB that you can use to manage reconciliation definitions.
regular class
One or more criteria that, when met, cause an action. The types of rules used in the BMC Atrium CMDB are Exclusion rule, Identification rule, and Workflow Execution rule.
ruleset
A group of rules.
service level agreement
A class that stores its instance data in its own AR System form. See also abstract class, categorization class.
related information
A contract between a service provider and a purchaser that defines the level of service.
singleton class
Information about a CI that does not qualify as attributes of the CI, and should therefore not be stored in a Configuration Management Database (CMDB).
relationship
An optional class characteristic that restricts the class to holding only one instance.
snapshot
A connection between two CIs such as a dependency or membership. It is an instance of a relationship class. See also configuration item (CI).
relationship class
A set of data that represents a configuration at a certain point in time, usually stored in its own dataset. There can be multiple snapshots of a given configuration.
soft delete
The act of marking an instance as deleted from the BMC Atrium CMDB by setting the MarkAsDeleted attribute to Yes.
source
A class that defines a type of relationship between CIs, such as a dependency or membership.
relationship filter
See filter.
Rename Dataset activity
The CI class defined as Class 1 in a relationship class, or an instance of that CI class as a member of such a relationship. Also known as the parent member or strong member.
A reconciliation activity that renames a dataset without changing its ID, preserving references to the dataset from any reconciliation definitions.
366 Glossary
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 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
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.
weak reference
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
An optional characteristic for relationship classes, signifying that the members of a relationship form a composite object that can be reconciled as one. The child member is considered the weak member of a weak relationship, existing as part of the parent member.
Windows Management Instrumentation (WMI)
The permission required along with rowlevel security to modify or delete a specific instance.
Microsoft's application of the Web-Based Enterprise Management initiative for an industry standard for accessing management information.
WMI
AR System objects such as active links, escalations, and filters that perform actions against data.
Glossary
367
368 Glossary
Index
A
ActivateFederatedInContext operation 252 activating federated instances 177, 216, 293 active link error messages 327 adjacency items, storing for graphs 268 adjacency lists, representing graphs as 346 adjacency matrixes, representing graphs as 346 adjacent nodes, storing 208 API logging 88 AR System CI Relationship Viewer and 70 creating forms 142 storing related federation data 215, 294 transferring data from CI Relationship Viewer 344 to CI Relationship Viewer 342 architecture, CMDB API 16 AROS string, replaced in object names 33 ArrayOf_String structure 263 attachLimits structure 191 attachment limits, defining 191 AttachmentLimit structure 282 AttributeInfoIn structure 279 AttributeInfoList structure 278 AttributeLimit structure 281 AttributeLimitList structure 286 attributes C API data structures 186 creating 40, 96, 100, 242 data structures 186 attributes (continued) deleting 103, 119, 240, 245 expanding CI parameters 148 exporting definitions with cmdbdriver 64 installing extensions with cmdbExtLoader 61 managing 95 retrieving 104, 107, 241 setting 111, 113, 244 storing attachment limits 282 character limits 282 currency limits 283 data limits 281, 286 date limits 284 definitions 186 enum limits 284 index information 185, 276 information 200 information to retrieve 278 information to set 279 integer limits 285 lists of values 279 real data limits 285 retrieval information 186 sort information 195, 264 sort information by type 264 sources for propagation 194 targets for propagation 194 values 192, 193, 279 validating CI 147 web services API data structures 278
Index
369
AttributeValue structure 279 AttributeValueList structure 279 audience for this guide 10 AuditInfo structure 296 audits data structures 218, 295 functions 179 operations 256 retrieving CI instance logs 181 retrieving modified CI instances 179, 256 storing class options 219, 296 value lists 218, 219, 295 AuditValueList structure 295 AuditValueListList structure 295
C
C API data structures about 182 attribute about 186 attachLimits 191 charLimits 190 CMDBAttributeGetStruct 186 CMDBAttributeLimit 187 CMDBAttributeNameId 192 CMDBSortList 195 CMDBSortStruct 195 CMDBWeakPropagatedAttrs 194 CMDBWeakPropagatedAttrsList 194 currencyLimits 191 dateLimits 191 decimalLimits 190 enumLimits 191 integerLimits 190 realLimits 190 audit about 218 CMDBAuditInfoStruct 219 CMDBAuditValueList 218 CMDBAuditValueListList 219 class about 182 CMDBClassRelationship 183 CMDBClassTypeInfo 182 CMDBIndexList 184 CMDBIndexStruct 185 federation about 215 CMDBFederatedActivateInfo 216 CMDBFederatedARInfo 215 general purpose about 198 CMDBClassNameId 196 CMDBClassNameIdList 196 CMDBQualifierStruct 197 CMDBVersionInfo 198 CMDBVersionInfoList 198
B
BLOBs, retrieving instance 134 BMC Atrium CMDB accessing classes 87 cmdbdriver program 50 documents available for 10 error messages C API 298 Console active link 327 Console filter 334 exporting data 149 importing data 149 importing data with EIE 86 installing extensions 63 migrating data between servers 53 programming 38 programs header files 32 structure 38 storing version information 198, 286, 287 tools 4989 utilities 4989, 155, 260 bulk entries beginning transactions 139 committing transactions 140 ending transactions 140 invoking API calls 139 rolling back transactions 140 transaction functions 139
370
Index
graph query about 206 CMDBGetObjectList 206 CMDBGetObjectStruct 206 CMDBGetRelationList 207 CMDBGetRelationStruct 207 CMDBGraphAdjacentList 208 CMDBGraphAdjacentStruct 208 CMDBGraphList 209 CMDBGraphStruct 209 import and export about 199 CMDBExportItem 200 CMDBExportItemList 201 CMDBExportItemStruct 201 CMDBImportItem 202 CMDBImportItemList 203 CMDBImportItemStruct 204 CMDBItemTypeAttribute 200 CMDBItemTypeClass 199 CMDBXMLExportItemList 201 CMDBXMLImportItemList 203 instance about 196 CMDBAttributeValueList 192 CMDBAttributeValueListList 193 CMDBAttributeValueStruct 193 Reconciliation Engine about 212 CMDBREClassQualList 214 CMDBREClassQualStruct 213 CMDBREDatasetList 215 CMDBREDatasetPair 214 CMDBREJobRunInfo 213 CMDBREJobRunInfoList 212 user interface component about 210 CMDBUIComponentInfo 210 CMDBUIComponentResult 211 CMDBUIComponentResultList 212 C API functions about 95 audit about 179 CMDBGetCopyAuditData 179
C API functions (continued) audit (continued) CMDBGetLogAuditData 181 bulk entry transaction about 139 CMDBBeginBulkEntryTransaction 139 CMDBEndBulkEntryTransaction 140 data model management about 95 CMDBCreateAttribute 96 CMDBCreateClass 116 CMDBCreateMultipleAttribute 100 CMDBDeleteAttribute 103 CMDBDeleteClass 119 CMDBGetAttribute 104 CMDBGetClass 120 CMDBGetListClass 122 CMDBGetMultipleAttribute 107 CMDBSetAttribute 111 CMDBSetClass 123 CMDBSetMultipleAttribute 113 environment about 141 CMDBGetServerPort 143 CMDBInitialization 141 CMDBSetServerPort 144 CMDBSynchMetaData 142 CMDBSystemInit 142 CMDBTermination 145 federation about 176 CMDBActivateFederatedInContext 177 CMDBGetRelatedFederatedInContext 1 76 free about 157 FreeCMDBAttributeGetStruct 163 FreeCMDBAttributeLimit 159 FreeCMDBAttributeLimitList 160 FreeCMDBAttributeLimitStruct 159 FreeCMDBAttributeValueList 169 FreeCMDBAttributeValueListList 169 FreeCMDBClassNameIdList 158 FreeCMDBClassTypeInfo 166
Index
371
C API functions (continued) free (continued) FreeCMDBExportItemList 162 FreeCMDBExportItemStruct 161 FreeCMDBGetObjectList 168 FreeCMDBGetRelationList 167 FreeCMDBGraphAdjacentList 164 FreeCMDBGraphAdjacentStruct 164 FreeCMDBGraphList 166 FreeCMDBGraphStruct 165 FreeCMDBImportItemList 162 FreeCMDBIndexList 161 FreeCMDBQualifierStruct 167 FreeCMDBREJobRunInfoList 171 FreeCMDBSortList 170 FreeCMDBVersionInfoList 158 import and export about 149 CMDBExport 149 CMDBExportData 151 CMDBExportDef 150 CMDBImport 152 CMDBImportData 154 CMDBImportDef 153 instance management about 126 CMDBCreateInstance 126 CMDBDeleteInstance 127 CMDBGetInstance 129 CMDBGetInstanceBLOB 134 CMDBGetListInstance 130 CMDBGetMultipleInstances 132 CMDBGraphQuery 135, 347 CMDBSetInstance 138 Reconciliation Engine about 172 CMDBCancelJobRun 175 CMDBGetJobRun 173 CMDBGetListJobRun 174 CMDBStartJobRun 172 user interface component about 146 CMDBExpandParametersForCI 148 CMDBGetCMDBUIComponents 146 CMDBRunQualificationForCI 147
C API functions (continued) utility about 155 CMDBCreateGuid 155 CMDBGetVersions 156 C API sessions initializing 141 terminating 145 C APIs about 17 compilers 29 components 17 data structures 182 driver source code 24 error messages 298 function calls 17 function definitions 94 functions 95 header files 24 installing package 24 library files 25 library links 30 calls C API function 17 data structure changes 35 debugging with data structure contents 89 debugging with log information 88 invoking bulk entry API 139 canceling reconciliation jobs 175, 251 CancelJobRun operation 251 character limits, defining 190 CharLimit structure 282 charLimits structure 190 CI instances. See instances CI Relationship Viewer about 70 AR System and 70 configuring 77 creating context menus 78 creating definitions 82 creating events 84 embedding in AR System forms 73 events CIRV_LAYOUT 343 CIRV_NOTIFY_AR 344
372
Index
CI Relationship Viewer (continued) events (continued) CIRV_REFRESH 343 CIRV_SELECT_CI 343 CIRV_SET_AS_ROOT 343 CIRV_SET_CUSTOM_FILTER 342 CIRV_SET_FILTER 342 CIRV_SHOW 343 SELECTED_CI 344 filters 77 launching 71, 75 opening 71, 75 transferring data with events from AR System 342 to AR System 344 CIRV_LAYOUT event 343 CIRV_NOTIFY_AR event 344 CIRV_REFRESH event 343 CIRV_SELECT_CI event 343 CIRV_SET_AS_ROOT event 343 CIRV_SET_CUSTOM_FILTER event 342 CIRV_SET_FILTER event 342 CIRV_SHOW event 343 class forms creating instances in 226 setting instances in 225 classes accessing BMC Atrium CMDB directly 87 C API data structures 182 configuration item about 38 creating 38 creating attributes 40 creating instances 42 creating attributes 40 with cmdbdriver program 50 with core attributes 116, 237 data structures 182 deleting 119, 240 exporting data with cmdbdriver 55 definitions 149, 150 definitions with cmdbdriver 55, 64 qualified 151
classes (continued) importing data 154 data with cmdbdriver 57 definitions 152, 153 definitions with cmdbdriver 57 installing extensions with cmdbExtLoader 61 managing 95 relationship about 44 creating 44 retrieving 238 retrieving 120, 122, 235 retrieving list of UI components 146, 258 setting properties 123, 236 storing attribute index information 185 audit options 219 CI definitions 182 CI properties 275 CI relationship information 273 class names 192 display properties 277 display property structures 277 index information 184, 276 information to retrieve 273 information to set 272 names 196, 199, 263 namespace names 192, 196, 263 qualification information 291 relationship definitions 182 relationship information 183 type information 182 web services API data structures 272 ClassInfoIn structure 272 ClassInfoOut structure 273 ClassNameId structure 263 ClassNameIdList structure 263 ClassProperties structure 275 ClassQualifier structure 291 ClassQualifierList structure 291 ClassRelationship structure 273 CMDB APIs about 16 architecture 16
Index
373
CMDB APIs (continued) C APIs 17 call changes 35 data structure changes 35 function changes 34 Java APIs 19 logging option 88 migrating to 33 objects, deprecated 33 objects, renamed 33 parameter changes 34 programming 20 programs, when to write 20 sample source code 32 terminology changes 21 web services APIs 18 CMDB Console active link errors 327 API programming and 20 filter errors 334 CMDB. See BMC Atrium CMDB CMDBActivateFederatedInContext function 177 CMDBAttributeGetStruct structure 186 CMDBAttributeLimit structure 187 CMDBAttributeNameId structure 192 CMDBAttributeValueList structure 192 CMDBAttributeValueListList structure 193 CMDBAttributeValueStruct structure 193 CMDBAuditInfoStruct structure 219 CMDBAuditValueList structure 218 CMDBAuditValueListList structure 219 CMDBBeginBulkEntryTransaction function 139 CMDBCancelJobRun function 175 CMDBClassNameId structure 196 CMDBClassNameIdList structure 196 CMDBClassRelationship structure 183 CMDBClassTypeInfo structure 182 CMDBCreateAttribute function 96 CMDBCreateClass function 116 CMDBCreateGuid function 155 CMDBCreateInstance function 126 CMDBCreateMultipleAttribute function 100 CMDBDeleteAttribute function 103 CMDBDeleteClass function 119 CMDBDeleteInstance function 127
cmdbdriver program about 50 exporting class data 55 class definitions 55 instance data 56 subclass definitions 55 importing class data 57 class definitions 57 instance data 58 starting 54 using from command line 50 using on UNIX 52 CMDBEndBulkEntryTransaction function 140 CMDBExpandParametersForCI function 148 CMDBExport function 149 CMDBExportData function 151 CMDBExportDef function 150 CMDBExportItem structure 200 CMDBExportItemList structure 201 CMDBExportItemStruct structure 201 cmdbExtLoader program about 61 file structure 62 starting 69 CMDBFederatedActivateInfo structure 216 CMDBFederatedARInfo structure 215 CMDBGetAttribute function 104 CMDBGetClass function 120 CMDBGetCMDBUIComponents function 146 CMDBGetCopyAuditData function 179 CMDBGetInstance function 129 CMDBGetInstanceBLOB function 134 CMDBGetJobRun function 173 CMDBGetListClass function 122 CMDBGetListInstance function 130 CMDBGetListJobRun function 174 CMDBGetLogAuditData function 181 CMDBGetMultipleAttribute function 107 CMDBGetMultipleInstances function 132 CMDBGetObjectList structure 206 CMDBGetObjectStruct structure 206 CMDBGetRelatedFederatedInContext function 176
374
Index
CMDBGetRelationList structure 207 CMDBGetRelationStruct structure 207 CMDBGetServerPort function 143 CMDBGetVersions function 156 CMDBGraphAdjacentList structure 208 CMDBGraphAdjacentStruct structure 208 CMDBGraphList structure 209 CMDBGraphQuery function 135, 347 CMDBGraphStruct structure 209 CMDBImport function 152 CMDBImportData function 154 CMDBImportDef function 153 CMDBImportItem structure 202 CMDBImportItemList structure 203 CMDBImportItemStruct structure 204 CMDBIndexList structure 184 CMDBIndexStruct structure 185 CMDBInitialization function 141 CMDBItemTypeAttribute structure 200 CMDBItemTypeClass structure 199 CMDBQualifierStruct structure 197 CMDBREClassQualList structure 214 CMDBREClassQualStruct structure 213 CMDBREDatasetList structure 215 CMDBREDatasetPair structure 214 CMDBREJobRunInfo structure 213 CMDBREJobRunInfoList structure 212 CMDBRunQualificationForCI function 147 CMDBSetAttribute function 111 CMDBSetClass function 123 CMDBSetInstance function 138 CMDBSetMultipleAttribute function 113 CMDBSetServerPort function 144 CMDBSortList structure 195 CMDBSortStruct structure 195 CMDBStartJobRun functions 172 CMDBSynchMetaData function 142 CMDBSystemInit function 142 CMDBTermination function 145 CMDBUIComponentInfo structure 210 CMDBUIComponentResult structure 211 CMDBUIComponentResultList structure 212 CMDBVersionInfo structure 198 CMDBVersionInfoList structure 198 CMDBWeakPropagatedAttrs structure 194
CMDBWeakPropagatedAttrsList structure 194 CMDBXMLExportItemList structure 201 CMDBXMLImportItemList structure 203 commands, cmdbdriver program 50 committing bulk entry transactions 140 compilers, C APIs 29 components C API 17 web services API 19 configuration items See also instances classes 38 creating instances 42 querying instances 47 viewing relationships 70 context menus, creating 78 CreateAttribute operation 242 CreateClass operation 237 CreateInstance operation 226 CreateRelationInstance operation 229 creating AR System forms 142 attributes 96, 100, 242 CI classes 38 CI Relationship Viewer context menus 78 definitions 82 events 84 classes 116, 237 classes with cmdbdriver program 50 forms 142 globally unique IDs 155 installation activity file 67 instances CI 42, 126 in class forms 226 relationship 126 with cmdbdriver program 50 instances relationship 229 package.xml file 64 relationship classes 44 currency limits, defining 191 CurrencyLimit structure 283 currencyLimits structure 191
Index
375
D
data importing with EIE 86 limits, defining 191 data models management functions, C API 95 managing 95 operations, web services API 234 data structures C API about 182 attribute 186 audit 218 class 182 export 199 federation 215 general purpose 198 graph query 206 import 199 instance 196 Reconciliation Engine 212 user interface component 210 CMDB API, changed 35 printing contents 89 web services API about 262 attribute 278 audit 295 class 272 federation 293 graph 267 instance 262 job 290 user interface component 288 utility 286 DatasetPair structure 292 DatasetPairList structure 292 DateLimit structure 284 dateLimits structure 191 debugging calls with data structure contents 89 calls with log information 88 debugging APIs 88 decimal limits, defining 190 decimalLimits structure 190
defining attachment limits 191 character limits 190 currency limits 191 date limits 191 decimal limits 190 enum limits 191 integer limits 190 query graph lists 209 real limits 190 definitions creating CI Relationship Viewer 82 exporting attribute with cmdbdriver 64 class 149, 150 class with cmdbdriver 55, 64 subclass with cmdbdriver 55 importing class 152, 153 class with cmdbdriver 57 storing attribute 186 CI 182 relationship 182 Delete Attribute operation 245 DeleteClass operation 240 DeleteInstance operation 228 deleting attributes 103, 245 classes 119, 240 instances 127, 228 deprecated CMDB API objects 33 display properties, storing for classes 277 documents, available for CMDB 10
E
EIE, importing data with 86 Enterprise Integration Engine. See EIE enum limits, defining 191 EnumLimit structure 284 enumLimits structure 191 environment functions 141 error messages C API 298 Console active link 327
376
Index
error messages (continued) Console filter 334 events creating CI Relationship Viewer 84 transferring from AR System to CI Relationship Viewer 342 CI Relationship Viewer to AR System 344 ExecuteJobRun operation 247 expanding federated instances 177, 252 exporting attribute definitions with cmdbdriver 64 C API data structures 199 C API functions 149 class data with cmdbdriver 55 data, qualified 151 definitions 149, 150 definitions with cmdbdriver 55, 64 CMDB data 149 instance data with cmdbdriver 56 storing data for 199 subclass definitions with cmdbdriver 55
F
features Java API 19 Web services API 18 FederatedActivateInfo structure 293 FederatedARInfo structure 294 federation data structures 215, 293 expanding instances 177, 252 functions 176 launching instances 177, 252 operations 252 retrieving instances 176, 254 storing AR system data 215, 294 storing instance activation data 216, 293 filters CI Relationship Viewer 77 error messages 334 forms, creating 142 free functions 157 FreeCMDBAttributeGetStruct function 163 FreeCMDBAttributeLimit function 159
FreeCMDBAttributeLimitList function 160 FreeCMDBAttributeLimitStruct function 159 FreeCMDBAttributeValueList function 169 FreeCMDBAttributeValueListList function 169 FreeCMDBClassNameIdList function 158 FreeCMDBClassTypeInfo function 166 FreeCMDBExportItemList function 162 FreeCMDBExportItemStruct function 161 FreeCMDBGetObjectList function 168 FreeCMDBGetRelationList function 167 FreeCMDBGraphAdjacentList function 164 FreeCMDBGraphAdjacentStruct function 164 FreeCMDBGraphList function 166 FreeCMDBGraphStruct function 165 FreeCMDBImportItemList function 162 FreeCMDBIndexList function 161 FreeCMDBQualifierStruct function 167 FreeCMDBREJobRunInfoList function 171 FreeCMDBSortList function 170 FreeCMDBVersionInfoList function 158 functions C API audit 179 bulk entry transaction 139 calls 17 data model management 95 environment 141 federation 176 free 157 import and export 149 instance management 126 Reconciliation Engine 172 user interface component 146 utility 155 CMDB API, changed 34 web services API 222
G
general purpose data structures 198 GetAttributes operation 241 GetClass operation 235 GetCopyAuditData operation 256 GetInstances operation 223 GetJobRun operation 248 GetListJobRun operation 250
Index
377
GetRelatedFederatedInContext operation 254 GetUIComponents operation 258 GetVersions operation 260 Graph structure 267 GraphAdjacency structure 268 GraphAdjacencyList structure 268 GraphList structure 267 GraphQuery operation 231 graphs adjacency lists, collections of 346 adjacency matrixes 346 query data structures C API 206 web services API 267 representing 346 storing adjacency items 268
H
header files C API 24 CMDB program 32
I
icon, New 10 IDs, creating globally unique 155 import and export functions 149 importing C API data structures 199 C API functions 149 class data 154 data with cmdbdriver 57 definitions 152, 153 definitions with cmdbdriver 57 CMDB data 149 data with EIE 86 instance data with cmdbdriver 58 storing data for 199 IndexInfo structure 276 IndexList structure 276 initializing networks 142 servers 142 installation activity file, creating 67 installing
attribute extensions with cmdbExtLoader 61 C API package 24 class extensions with cmdbExtLoader 61 CMDB extensions 63 InstanceInfo structure 265 InstanceInfoList structure 264 instances See also configuration items and relationships C API management functions 126 C API structures 196 creating CI 126 configuration item 42 in class forms 226 relationship 126 with cmdbdriver program 50 data operations 222 data structures 262 deleting 127, 228 expanding CI parameters 148 expanding federated 177, 252 exporting data with cmdbdriver 56 importing data with cmdbdriver 58 launching federated 177 management functions 126 managing 126 querying 47, 231 retrieving audit logs 181 BLOBs 134 CI audit data 179, 256 federated 176 list of 130, 223 multiple 132 single 129 retrieving federated 254 searching for related 135 setting CI 138 setting in class forms 225 setting relationship 138 storing CI 206 data 196 list of values 264 relationship 207
378
Index
instances (continued) storing (continued) values 265 structures 196 viewing relationships 70 web services API data structures 262 web services API operations 222 integer limits, defining 190 integerLimits attribute structure 190 IntLimit structure 285
M
managing attributes 95 classes 95 data models 95 instances 126 reconciliation jobs 172 matrixes, representing graphs as 346 memory, releasing 157 menus, creating context 78 migrating CMDB data between servers 53 known issues 61 to BMC Atrium CMDB 2.0 API 33
J
Java APIs about 19 environment components 31 features 19 program requirements 31 JobRunInfo structure 290 JobRunInfoList structure 291 jobs. See reconciliation jobs
N
names storing class 192, 196, 263 storing namespace 192, 196, 263 networks, initializing 142 New icon 10
K
known issues, migrating CMDB data 61
L
launching CI Relationship Viewer 71, 75 federated instances 177, 252 library files, C API 25 links, C API 30 limits, defining attachment 191 character 190 currency 191 date 191 decimal 190 enum 191 integer 190 real 190 linking libraries, C API 30 ListClasses operation 238 log files, BMC Atrium CMDB 88 logging option for API calls 88 login information, storing 262
O
ObjectQueryInfo structure 270 ObjectQueryInfoList structure 269 objects deprecated from CMDB API 33 renamed in CMDB API 33 opening, CI Relationship Viewer 71, 75 operations, web services API about 222 audit 256 data model 234 federation 252 reconciliation job 247 storing status 265 user interface component 258 utility 260 OS string, replaced in object names 33
Index
379
P
package.xml file, creating 64 parameters changed CMDB API 34 expanding CI 148 ports retrieving 143 setting 144 print.c file 89 printing data structure contents 89 print.c file 89 programs cmdbdriver program 50 cmdbExtLoader 61 propagating attribute values 194 PropInfo structure 277 PropInfoList structure 277
Q
qualifications, storing strings 197 querying C API graph query data structures 206 instances 47 instances related to CIs 231 storing CIs for 270 graph list definitions for 209 graph nodes for 209 graphs for 267 list of CIs for 269 list of relationships for 270 relationships for 271
R
real data limits, defining 190 RealLimit structure 285 realLimits attribute structure 190 Reconciliation Engine C API data structures 212 C API functions 172 managing jobs 172 reconciliation jobs canceling 175, 251 data structures 290
reconciliation jobs (continued) operations 247 retrieving data for running 173 list of running 174, 250 logs for running 173 single running 248 starting 172, 247 storing all running 291 datasets 214, 215, 292 qualifications 213, 214 running 212, 213 single 290 RelationQueryInfo structure 271 RelationQueryInfoList structure 270 relationship instances, creating 229 relationships See also instances classes 44 querying instances 47 viewing 70 releasing memory 157 renamed CMDB API objects 33 retrieving attributes 104, 107, 241 audit data 179, 256 audit logs 181 classes 120, 122, 235 federated instances 176, 254 instance BLOBs 134 instances 129, 130, 132, 223 ports 143 reconciliation jobs 173, 174, 248, 250 relationship classes 238 server ports 143 UI component lists 146, 258 version of CMDB components 156, 260
S
samples C API driver programs 24 CMDB API source code 32 searching for instances 135 SELECTED_CI event 344
380
Index
server ports retrieving 143 setting 144 servers initializing 142 retrieving ports 143 setting ports 144 sessions initializing C API 141 terminating C API 145 SetAttribute operation 244 SetClass operation 236 SetInstance operation 225 setting attributes 111, 113, 244 class properties 123, 236 instances 138 instances in class forms 225 ports 144 server ports 144 sorting attributes 264 sorting attributes by type 264 SortOrder structure 264 SortOrderList structure 264 source code C API driver 24 sample CMDB API 32 SQL views 87 starting bulk entry transactions 139 cmdbdriver program 54 cmdbExtLoader program 69 reconciliation jobs 172, 247 Status structure 265 status, storing 265 StatusList structure 265 storing adjacent nodes 208 AR System federated data 215, 294 attributes attachment limits 282 character limits 282 currency limits 283 data limits 281, 286 date limits 284
storing (continued) attributes (continued) definitions 186 enum limits 284 index information 185, 276 information 200, 278, 279 integer limits 285 real data limits 285 retrieval information 186 sort information 195, 264 sort information by type 264 values 192, 193, 279 audit options 219, 296 audit value lists 218, 219, 295 CI definitions 182 CI instances 206 CIs to query 269, 270 classes CI properties 275 CI relationship information 273 data 182 display properties 277 display property structures 277 index information 184, 276 information to retrieve 273 information to set 272 names 192, 196, 199, 263 namespace names 192, 196, 263 qualification information 291 type information 182 export data 199 federated instance activation data 216, 293 graph adjacency items 268 graph nodes 209 import data 199 instance data 196 instance values 264, 265 items to export 200, 201 items to import 202, 203, 204 login information 262 operation statuses 265 qualification strings 197 query graph list definitions 209 query graphs 267 reconciliation job datasets 214, 215, 292
Index
381
storing (continued) reconciliation job qualifications 213, 214 reconciliation jobs 290, 291 relationships definitions 182 information 183 instances 207 to query 270, 271 running reconciliation jobs 212, 213 source attributes 194 strings 263 target attributes 194 UI component information 289 UI component query results 211, 212, 289 UI components to retrieve 210, 288 versions of CMDB components 198, 286, 287 XML items to export 201 XML items to import 203 strings, storing 263 structures. See data structures subclasses, exporting definitions 55
utilities CMDB 4989, 155, 260 functions 155 operations 260 web services API data structures 286
V
validating attributes, CI 147 VersionInfo structure 287 VersionInfoList structure 286 versions, retrieving CMDB component 156, 260 viewing configuration item relationships 70 instance relationships 70 views, SQL 87
W
web services API data structures attribute about 278 AttachmentLimit 282 AttributeInfoIn 279 AttributeInfoList 278 AttributeLimit 281 AttributeLimitList 286 AttributeValue 279 AttributeValueList 279 CharLimit 282 CurrencyLimit 283 DateLimit 284 EnumLimit 284 IntLimit 285 RealLimit 285 audit about 295 AuditInfo 296 AuditValueList 295 AuditValueListList 295 class about 272 ClassInfoIn 272 ClassInfoOut 273 ClassProperties 275 ClassRelationship 273 IndexInfo 276
T
terminating C API sessions 145 terminology changes 21 CMDB and API 21 tools, CMDB 4989
U
UI components. See user interface components UIComponentInfo structure 288 UIComponentResult structure 289 UIComponentResultList structure 289 user interface components data structures 210 functions 146 operations 258 retrieving list of 146, 258 storing information 289 query results 211, 212, 289 to retrieve 210, 288 web services API data structures 288 user login information, storing 262
382
Index
web services API data structures (continued) class (continued) IndexList 276 PropInfo 277 PropInfoList 277 federation about 293 FederatedActivateInfo 293 FederatedARInfo 294 graph about 267 Graph 267 GraphAdjacency 268 GraphAdjacencyList 268 GraphList 267 ObjectQueryInfo 270 ObjectQueryInfoList 269 RelationQueryInfo 271 RelationQueryInfoList 270 instance about 262 ArrayOf_String 263 ClassNameId 263 ClassNameIdList 263 InstanceInfo 265 InstanceInfoList 264 LoginInfo 262 SortOrder 264 SortOrderList 264 Status 265 StatusList 265 job about 290 ClassQualifier 291 ClassQualifierList 291 DatasetPair 292 DatasetPairList 292 JobRunInfo 290 JobRunInfoList 291 user interface component about 288 UIComponentInfo 288 UIComponentResult 289 UIComponentResultList 289
web services API data structures (continued) utility about 286 VersionInfo 287 VersionInfoList 286 web services API operations audit about 256 GetCopyAuditData 256 data model about 234 CreateAttribute 242 CreateClass 237 Delete Attribute 245 DeleteClass 240 GetAttributes 241 GetClass 235 ListClasses 238 SetAttribute 244 SetClass 236 federation about 252 ActivateFederatedInContext 252 GetRelatedFederatedInContext 254 instance data about 222 CreateInstance 226 CreateRelationInstance 229 DeleteInstance 228 GetInstances 223 GraphQuery 231 SetInstance 225 reconciliation job about 247 CancelJobRun 251 ExecuteJobRun 247 GetJobRun 248 GetListJobRun 250 user interface component about 258 GetUIComponents 258 utility about 260 GetVersions 260
Index
383
web services APIs about 18 components 19 data structures 262 features 18 functions 222 operations 222
384
Index
*64742*