Navigating Schema

A key property has all the characteristics of any other property in a CIM class, only with the additional semantics associated with having the Key qualifier. These characteristics of a property include that its related qualifiers are inherited by all subclasses. The combination of all key properties defined for a class makes up the compound key for the class. The following example MOF fragment shows a class definition for the class CIM_OperatingSystem where the combination of properties CSCreationClassName, CSName, CreationClassName, and Name (the key properties) makes up the key of the class.

Example 5-1 Abridged MOF declaration of CIM_OperatingSystem

// ======================================================== // OperatingSystem // ======================================================== class CIM_OperatingSystem : CIM_LogicalElement { [Propagated ("CIM_ComputerSystem.CreationClassName"), Key, . . . ] string CSCreationClassName; [Propagated ("CIM_ComputerSystem.Name"), Key, . . . ] string CSName; [Key, . . . ] string CreationClassName; [Override ("Name"), Key, . . .] string Name; uint16 OSType; string OtherTypeDescription; . . . // additional properties and methods . . . };

Key properties may be defined for an abstract class (a class with the Abstract qualifier). If a class has a concrete class as its parent, it must have the same keys. Only concrete classes can have instances.

A class inherits all the keys of its superclass. This fact is of particular importance when considering a class whose parent is a class with keys. All subclasses of a class with keys will have the same set of key properties; a subclass of a class that has keys cannot add additional keys. While initially not being able to add keys to a subclass may sound like a limitation to the CIM model, in fact it is a powerful feature which enables greater flexibility for clients in dealing with classes for which a provider has identified additional subclasses. Clients are able to access a class and all its subclasses in a consistent manner through the use of a common key structure.

Many important DMTF CIM superclasses include a key property called CreationClassName. The creation class name is typically the name of the class itself or in some cases that of a superclass.

The creation class name is of particular use on managed systems where subclasses are implemented by a number of independent providers. In such cases, the providers can ensure uniqueness of their instances through specifying the name of the class itself for the CreationClassName property. Thus, while other properties on a given class and its subclasses may have the same values, the CreationClassName property's unique value ensures that each instance of the class and its subclasses is unique. A portion of the DMTF schema which extensively uses the CreationClassName key property is CIM_LogicalDevice and its subclasses. While instances of CIM_DiskDrive, CIM_PowerSupply, and CIM_SCSIController (all subclasses of CIM_LogicalDevice) might have common values for DeviceID, having values for CreationClassName which match their individual class names ensures uniqueness.

When a client performs the enumerateInstanceNames CIM operation, it specifies a namespace and a class name. The CIM server then returns values of the key properties for instances of that class within the specified namespace. Each instance is uniquely defined by the values of its key properties. The enumerateInstanceNames operation returns all instances of the class specified, which include instances of all of its subclasses, since those are also instances of the specified class. For example, enumerating instance names of CIM_LogicalPort would return any instances of its subclasses, CIM_USBPort and CIM_FibrePort, as well as possible instances of CIM_LogicalPort, if any, that are not instances of those subclasses.

The enumerateInstances operation works in a similar manner though it also returns the other properties of the class and subclasses. Thus in the example above, in addition to the set of keys defined for CIM_LogicalPort, the enumerateInstances operation would return all properties on the instances returned. In particular, it would also return any additional properties of CIM_USBPort and CIM_FibrePort that may be unique to these subclasses.

Propagated keys define a context or scope within which instances of a particular class are unique. Examples of scoping relationships include:

For each of these examples, an instance of the first class is more completely defined by understanding within which instance of the second class it is scoped. Note that in the last example, a process is scoped within the context of both its operating system and its computer system.

The scope for a given class is defined by the set of key properties that are copied (propagated) from the scoping class or classes. A propagated key property, making up a part of a class's key, will not only have the Key qualifier as discussed above, but also will have the Propagated qualifier to indicate that it has been propagated from a scoping class. The following MOF fragments illustrate the relationship between the CIM_System and CIM_LogicalDevice classes, showing how keys in CIM_LogicalDevice are propagated from CIM_System:

Example 5-2 Abridged MOF declaration of CIM_LogicalDevice

class CIM_System : CIM_LogicalElement { [ Key ]string CreationClassName; [ Key ] string Name;...};...class CIM_LogicalDevice : CIM_LogicalElement {[ Propagated("CIM_System.CreationClassName"), Key ]string SystemCreationClassName;[ Propagated("CIM_System.Name"), Key ]string SystemName;[ Key ]string CreationClassName;[ Key ]string DeviceID;...};

The use of propagated keys effectively creates associations between classes without explicitly defining an association class for which instances would need to exist in order for a client to be able to find associated objects. When a client receives an instance of an explicitly defined association class, the paths to referenced objects are obtained directly from the properties of the association instance. In contrast, when a client application encounters an association linking two classes through the use of propagated keys, it must construct object paths from the values of the propagated keys in order to access the referenced objects.

For example, as shown above, instances of CIM_LogicalDevice are associated with a CIM_System by the presence of two keys, SystemCreationClassName and SystemName, that are propagated from the keys of CIM_System. The referenced CIM_System can be accessed by constructing an object path specifying:

The object path so constructed would then look like:

CIM_System.CreationClassName="CIM_ComputerSystem",Name="sys7.hp.com"

As discussed in the provider implementation section on “Keys”, a short cut may be available when getting an instance of a class that contains propagated keys. Instead of requiring filling in the propagated key properties when obtaining an instance of a scoped class, the client may be able to use the empty string as the value for the propagated keys.

Support for the short cut realizes a performance benefit for both clients and providers. Thus, clients can realize greater interoperability in managing heterogeneous platforms through not needing to specify different key values for each platform. Further, clients do not need to obtain and store key information from a class where there is likely to be only one instance in the namespace (e.g. CIM_System) and then use that information in performing a getInstance operation on the scoped class (e.g. CIM_LogicalDevice).

This short cut may not be available with all providers; if it is, this should be identified in the provider's documentation.

Client applications can maximize platform interoperability by using DMTF-defined classes (classes with names usually having the CIM_ prefix). Clients can successfully use DMTF superclasses, yet still obtain information from platform-specific subclasses, since:

For example, a general-purpose client could enumerate instances of CIM_USBPort, obtaining property values of interest, rather than referencing a particular vendor's subclass (e.g. vendor ACME's USB port, supported by the ACME_USBPort subclass of CIM_USBPort). When performing one of the enumeration operations, the client must specify appropriate values for the DeepInheritance and LocalOnly flags as discussed below (see also the DMTF Specification for CIM Operations for additional details). Thus, when a client performs one of the these operations on a DMTF-defined class, the CIM Server will return all instances of the DMTF-defined class, which include those of any subclasses.

Only those clients that actually plan to use additional properties or methods of a vendor subclass need to write their application specific to the added information in that subclass. Clients may find they can support their management needs with the properties and methods in the DMTF classes only.

The DeepInheritance flag indicates that the enumerateInstances operation should return all properties defined in the designated class and its subclasses. A value of FALSE would indicate that none of the properties defined in subclasses should be returned (just those properties inherited from superclasses and local to the class specified in the operation).

HP WBEM Services only supports the value TRUE for the DeepInheritance flag.

The LocalOnly flag indicates that the enumerateInstance and getInstance operations should return only properties defined in the designated class and none of those defined in superclasses. A value of FALSE would indicate that those properties defined in superclasses should also be returned. Note that for either value of the LocalOnly flag, properties that are overridden in the specified class are returned.

HP WBEM Services only supports the value FALSE for the LocalOnly flag.