Section I Developing programs with the CMDB APIs
Chapter 6 Web services API operations and data structures
Chapter
5
C API functions and data
structures
This section describes the C API functions. The following topics are provided:
Related files (page 82) Functions (page 82) Data structures (page 158)
Related files
Thecmdb.h and cmdbfree.h files contain the C API function definitions. For a complete list of header files required for the BMC Atrium CMDB, see Chapter 2, “Header files.”
Functions
The CMDB C API functions are categorized by the type of actions these functions perform. The function categories include data model, instance, and general purpose functions, such as session, authentication, and import or export definition functions.
NOTE
In the C API function descriptions, the usage of the term specified for a given parameter denotes that the parameter is listed under the Synopsis heading of the API function.
Data model functions
The data model functions manipulate the attribute and class. The C API functions for data model include:
CMDBCreateAttribute (page 83) CMDBCreateMultipleAttribute (page 86) CMDBDeleteAttribute (page 88) CMDBGetAttribute (page 89) CMDBGetMultipleAttribute (page 92) CMDBSetAttribute (page 95) CMDBSetMultipleAttribute (page 97) CMDBCreateClass (page 99) CMDBDeleteClass (page 101) CMDBGetClass (page 102) CMDBGetListClass (page 104) CMDBSetClass (page 105)
Functions
CMDBCreateAttribute
Description Creates a new attribute with the specified name for the specified class.
Privileges CMDB Administrator
Synopsis #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateAttribute( 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 two-part structure that contains the namespace and the classname. The name of the class must be unique.
attributeName
The name of the attribute to create. The name of the attribute must be unique within the specified class and within its superclasses and subclasses.
attributeID
The ID of the attribute to create.
dataType
The datatype of the attribute to create. 1: Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD) 2: Integer (CMDB_ATTR_DATA_TYPE_INTEGER) 3: Real (CMDB_ATTR_DATA_TYPE_REAL) ARControlStruct *control, CMDBClassNameId classNameID, ARNameType attributeName, ARNameType attributeId,
unsigned int dataType,
ARInternalId *arsubclassesId,
unsigned int entryMode,
CMDBAttributeLimit *attributeLimit,
ARValueStruct *defaultValue,
ARPropList *characList, ARPropList *customCharacList,
4: Character (CMDB_ATTR_DATA_TYPE_CHAR)
5: Diary (CMDB_ATTR_DATA_TYPE_DIARY)
6: Selection (CMDB_ATTR_DATA_TYPE_ENUM)
7: Time (CMDB_ATTR_DATA_TYPE_TIME)
10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL)
11: Attachment (CMDB_ATTR_DATA_TYPE_ATTACH)
12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY)
13: Date (CMDB_ATTR_DATA_TYPE_DATE)
14: Time of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY)
37: Attachment pool (CMDB_ATTR_DATA_TYPE_ATTACH_POOL)
arsubclassesId
The AR System subclasses ID of the attribute to create. The IDs of all attributes must be unique within the class. Specify 0 for this parameter if you want the system to generate the ID.
entryMode
The entry mode for the attribute. Entry mode can be set to any one of the following: required, optional, or display only.
1: Users must enter data when the entry mode is set to required
(CMDB_ATTR_ENTRYMODE_REQUIRED).
2: Users do not have to enter data when the entry mode is set to optional but they can if they want to (CMDB_ATTR_ENTRYMODE_OPTIONAL).
4: Users cannot enter data when the entry mode is set to display only (CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY).
attributeLimit
The value limits for the attribute and other properties specific to the attribute’s type. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute you are creating. The limits and properties you assign must be of the same data type as the attribute. Specify NULL
for this parameter if you do not want to change the attribute limits and properties.
defaultValue
The value to apply if a user submits an entry with no attribute value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute. Specify NULL if you do not want to specify a default value.
characList
A list of characteristics for the attribute. It includes the following characteristics: View Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description.
Functions
1: Users can specify a list of groups or roles that have permissions to view this attribute (CMDB_ATTR_CHARAC_VIEW_PERMS). When querying for attributes, you will see all attributes including the hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;-5.
2: Users can specify a list of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS). 3: Users can set the flag to false so that this attribute is hidden
(CMDB_ATTR_CHARAC_HIDDEN). This setting marks the atribute as hidden for a group or a role. When querying for classes, you can retrieve hidden attributes. You can specify one or more group IDs or role IDs for the permissions separated by a semicolon, for example, 20;3.
5: The class ID and the attribute ID of the lead class attribute from which the attribute is propagated (CMDB_ATTR_CHARAC_PROPAGATED_OWNER). The format for this value is <leadclassID>|<lead attribute>.
6: CMDB_ATTR_CHARAC_CREATE_MODE
7:Users can set the audit option on to store the audit history for the attribute.
CMDB_ATTR_CHARAC_AUDIT_OPTION
9:Users can set the description for the attribute. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacList
A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX). After the properties list structure you specify is serialized, it is converted into the <list_size><prop_id><data_type><prop_value>
format, where:
<list_size>: The number of items in the properties list.
<prop_id>: The ID for the property, which is within the 300000 - 399999 range.
<data_type>: The data type for the property, which can be of any native data type.
<prop_value>: The value for the property.
An example for the serialized property list is 1\300050\2\1.
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBCreateMultipleAttribute
Description Creates multiple new attributes with the specified names for the specified class.
Privileges CMDB Administrator
Synopsis #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBCreateMultipleAttribute( 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.
dataTypeList
The list of data types for the attributes being created.
arsubclassesIdList
The AR System subclasses IDs of the attributes being created.
ARControlStruct *control, CMDBClassNameId *classNameID, ARNameList *attributeNameList, ARNameList *attributeIdList, ARUnsignedIntList *dataTypeList, ARInternalIdList *arsubclassesIdList, ARUnsignedIntList *entryModeList, CMDBAttributeLimitList *attributeLimitList, ARValueList *defaultValueList, ARPropListList *characListList, ARPropListList *customCharacListList, ARStatusList *status)
Functions
entryModeList
The list of entry modes for the attributes being created. Options include display only, required, and optional.
1: Users must enter data when the 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.
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). 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>.
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.
An example for the serialized property list is 1\300050\2\1.
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBDeleteAttribute
Description 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.
Privileges CMDB Administrator
Synopsis #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBDeleteAttribute( 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.
ARControlStruct *control,
CMDBClassNameId classNameID,
ARNameType attributeName,
unsigned int deleteOption,
Functions
classNameID
The name of the class from which to delete the attribute.
attributeName
The name of the attribute to delete.
deleteOption
A value indicating the action to take if the specified attribute contains data.
0: Do not delete the attribute (AR_ATTRIBUTE_CLEAN_DELETE).
1: Delete if the attribute contains 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).
Return values
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
CMDBGetAttribute
Description Retrieves a single attribute.Privileges CMDB administrator
Synopsis #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetAttribute( ARControlStruct *control, CMDBClassNameId *classNameId, ARNameType attributeName, ARNameType attributeId,
unsigned int *dataType,
unsigned int *attributeType,
CMDBClassNameId *baseClassNameId,
ARInternalId *arsubclassesId,
unsigned int *entryMode,
CMDBAttributeLimit *attributeLimit, ARValueStruct *defaultValue, ARPropList *characList, ARPropList *customCharacList,
Input arguments
control
The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user, sessionId, and server subclasses are required.
classNameId
The name of the class. It is a two-part structure that contains the namespace and the classname. The name of the class must be unique.
attributeName
The name of the attribute to retrieve.
Return values
attributeId
The ID of the attribute.
dataType
The datatype of the attribute.
1: Keyword (CMDB_ATTR_DATA_TYPE_KEYWORD) 2: Integer (CMDB_ATTR_DATA_TYPE_INTEGER) 3: Real (CMDB_ATTR_DATA_TYPE_REAL) 4: Character (CMDB_ATTR_DATA_TYPE_CHAR) 5: Diary (CMDB_ATTR_DATA_TYPE_DIARY) 6: Selection (CMDB_ATTR_DATA_TYPE_ENUM) 7: Time (CMDB_ATTR_DATA_TYPE_TIME)
10: Fixed-point decimal (CMDB_ATTR_DATA_TYPE_DECIMAL)
12: Currency (CMDB_ATTR_DATA_TYPE_CURRENCY)
13: Date (CMDB_ATTR_DATA_TYPE_DATE)
14: Time of day (CMDB_ATTR_DATA_TYPE_TIME_OF_DAY)
37: Attachment pool (CMDB_ATTR_DATA_TYPE_ATTACH_POOL)
attributeType
The type of attribute to retrieve.
1: CMDB_ATTR_TYPE_CORE_INTERNAL 2: CMDB_ATTR_TYPE_CORE
3: CMDB_ATTR_TYPE_REGULAR
baseClassNameId
The name of the class that owns this attribute.
arsubclassesId
Functions
entryMode
The entry mode for the attribute list. Entry mode can be set to any one of the following: display only, required, optional.
1: CMDB_ATTR_ENTRYMODE_REQUIRED 2: CMDB_ATTR_ENTRYMODE_OPTIONAL 4: CMDB_ATTR_ENTRYMODE_DISPLAY_ONLY
attributeLimit
The value limits for the attribute and other properties specific to the attribute’s type. See the CMDBsubclassesLimitStruct definition in cmdb.h to find the contained structure that applies to the type of attribute you are creating. The limits and properties you assign must be of the same data type as the attribute. Specify NULL
for this parameter if you do not want to change the attribute limits and properties.
defaultValue
The value to apply if a user gets an entry with no attribute value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute.
characList
A list of characteristics for each attribute. Characteristics include View
Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description.
1: List of groups or roles that have permissions to view this attribute
(CMDB_ATTR_CHARAC_VIEW_PERMS).
2: List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
3: The flag value of the Hidden characteristic. If the flag is set to false, users cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN).
4: Specifies whether the attribute is a part of the primary key of the class
(CMDB_ATTR_CHARAC_PRIMARY_KEY).
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
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 Retrieves multiple attributes.Privileges CMDB Administrator
Synopsis #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBGetMultipleAttribute( 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. ARControlStruct *control, CMDBClassNameId *classNameId, ARBoolean getHiddenAttrs, ARBoolean getDerivedAttrs, ARNameList *nameList, ARPropList *attrCharacQueryList, ARBooleanList *existList, ARNameList *attributeNameList, ARNameList *attributeIdList, ARUnsignedIntList *dataTypeList, ARUnsignedIntList *attributeTypeList, CMDBClassNameIdList *baseClassNameIdList, ARInternalIdList *arsubclassesIdList, ARUnsignedIntList *entryModeList, CMDBAttributeLimitList *attributeLimitList, ARValueList *defaultValueList, ARPropListList *characList, ARPropListList *customCharacList, ARStatusList *status)
Functions
classNameId
The name of the class to retrieve. It is a two-part structure that contains the namespace and the classname.
getHiddenAttrs
A flag indicating whether to retrieve the hidden attributes. Specifying FALSE will not retrieve the hidden attributes.
getDerivedAttrs
A flag indicating whether to retrieve attributes derived from a superclass. Specifying FALSE will not retrieve the derived attributes.
nameList
A list of attributes to retrieve.
attrCharacQueryList
A list of attribute characteristic queries to retrieve.
Return values
existList
A list of flags and corresponding Boolean values indicating whether the attribute list exists. The value TRUE indicates that the attribute list exists; FALSE indicates that the attribute list does not exist.
attributeNameList
The list of attribute names retrieved.
attributeIdList
The list of attribute IDs retrieved.
dataTypeList
The list of data types for the attribute.
attributeTypeList
The list of the attribute’s type.
baseClassNameIdList
The name of the base class attribute to retrieve.
arsubclassesIdList
The AR System subclasses ID of the attribute.
entryModeList
The entry mode for the attribute list. Options include display only, required, and optional.
1: Users must enter data when the entry 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 attribute’s type. See “CMDBAttributeLimit” on page 162 to find the contained structure that applies to the type of attribute you are modifying. The limits and properties you assign must be of the same data type as the attribute. Specify NULL
for this parameter if you do not want to change the attribute limits and properties.
defaultValueList
The value to apply if a user submits an entry with no attribute list value. The default value can be as many as 255 bytes in length and must be of the same datatype as the attribute.
characList
A list of characteristics for each attribute. Characteristics include View
Permissions, Change Permissions, Hidden, Primary Key, Propagated Owner, Create Mode, Audit Option, and Description.
1: List of groups or roles that have permissions to view this attribute
(CMDB_ATTR_CHARAC_VIEW_PERMS).
2: List of groups or roles that have permissions to view and modify the characteristics of the attribute (CMDB_ATTR_CHARAC_CHANGE_PERMS).
3: The flag value of the Hidden characteristic. If the flag is set to false, users cannot see hidden attributes (CMDB_ATTR_CHARAC_HIDDEN).
4: Specifies whether the 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: The description of the attribute. CMDB_ATTR_CHARAC_DESCRIPTION
customCharacList
A list of user-defined custom characteristics for the attribute. The attributes must be in the range between 300000 (CMDB_ATTR_CUSTOM_CHARAC_MIN) and 399999 (CMDB_ATTR_CUSTOM_CHARAC_MAX).
status
A list of zero or more notes, warnings, or errors generated from a call of this function.
Functions
CMDBSetAttribute
Description Sets an attribute with the specified name for the specified class.
Privileges CMDB Administrator
Synopsis #include "ar.h" #include "arextern.h" #include "cmdb.h" int CMDBSetAttribute( 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