Intrinsic Methods

Intrinsic methods are those designed to be built into the WBEM server (but may not all be supported by every WBEM server ”see the description of the Interop common model on page 250 for the method a WBEM client may use to discover precisely which operations a WBEM server supports). Intrinsic methods are oriented towards the manipulation of the model itself and include methods to retrieve, delete, create, list ("enumerate" in CIM-speak), and generally manipulate classes, instances, associations, and qualifiers.

A full description of each of the intrinsic methods is given in the DMTF's document DSP0200 and I do not intend to repeat it here. Instead, I give a short list of the intrinsic methods in Table 7.1 and details of a few representative operations below (indicated by bold type in the table). I list these methods again in Figure 13.2 on page 253 where they are grouped into sets which different WBEM servers may or may not be able to handle.

Table 7.1: The Intrinsic Methods
Class-Oriented Methods
GetClass	Return the specification of a particular class
CreateClass	Create a new class
DeleteClass	Remove a class
ModifyClass	Change the specification of a class
EnumerateClasses	List all classes with particular characteristics
EnumerateClassNames	List the names of all classes with particular characteristics
Instance-Oriented Methods
GetInstance	Return an instance defined by a unique combination of keys
CreateInstance	Create an instance of a particular class
DeleteInstance	Remove an instance
ModifyInstance	Modify one or more properties of an instance
EnumerateInstances	List some or all of the properties of instances with particular characteristics
EnumerateInstanceNames	List the names of instances with particular characteristics
GetProperty	Get the value of one property in an instance
SetProperty	Set the value of one property in an instance
Qualifier-Oriented Methods
GetQualifier	Return a qualifier from a given namespace
SetQualifier	Create or modify a particular qualifier in a given namespace
DeleteQualifier	Remove a qualifier from a namespace
EnumerateQualifiers	List qualifiers in a namespace
Association-Oriented Methods
Associators	Return a list of instances associated with a particular instance or classes associated with a particular class
AssociatorNames	List the names of instances associated with a particular instance or classes associated with a particular class
References	Return a list of associations for a particular class or instance
ReferenceNames	Return a list of names of associations for a particular class or instance
Miscellaneous Methods
ExecQuery	Execute a ( potentially complex) database-style query on the classes and instances

Notice that although getProperty and setProperty appear in Table 7.1, they are effectively redundant since getInstance and modifyInstance both allow a subset of properties (including one) to be specified.

Enumerating (i.e., Listing) Instances

Because clients often need access to particular properties of instances, I will describe this operation very fully. This will then give a flavour for the other operations which I will describe more superficially.

The function EmumerateInstances is defined as follows to allow a client to retrieve a list of all instances satisfying certain criteria:

 <namedInstance>*EnumerateInstances          [IN] <className> ClassName,          [IN,OPTIONAL] boolean LocalOnly = true,          [IN,OPTIONAL] boolean DeepInheritance = true,          [IN,OPTIONAL] boolean IncludeQualifiers = false,          [IN,OPTIONAL] boolean IncludeClassOrigin = false,          [IN,OPTIONAL,NULL] string PropertyList [] = NULL)

I have used here the pseudocode employed by the DMTF in their specifications. It is reasonably self-explanatory with the possible exception of IN, OUT, and OPTIONAL. These define whether the parameter is passed into the WBEM server (IN) or whether the WBEM server returns a value in the parameter (OUT). OPTIONAL means that the parameter does not have to be present ”the default value given after the equals sign being taken if it is absent.

This call effectively says, "Give me a list of properties X, Y, and Z for all instances of class C." More formally , you need to provide:

ClassName to define the class for which instances are required. Note that this is the full class name , including namespace.

LocalOnly and DeepInheritance to define precisely the properties that are to be returned. Table 7.2 shows that the properties from the specified class are always candidates for return but that properties from subclasses and superclasses of the specified class can be included or excluded as required.

Table 7.2: Properties Retrieved by EnumerateInstances( )
			.. Properties in ..
LocalOnly	DeepInheritance	Class	Subclasses	Superclasses
True	True	Yes	Yes	No
True	False	Yes	No	No
False	True	Yes	Yes	Yes
False	False	Yes	No	Yes

As the use of these two parameters might not be intuitive (!), consider Figure 7.4.

click to expand
Figure 7.4: The DeepInheritance and LocalOnly Parameters

Assume that we issue an EnumerateInstances call for the class B and assume that we set PropertyList to accept everything (i.e., leave it as NULL). Then the actual properties returned are as illustrated in Table 7.3.

Table 7.3: Behaviour of LocalOnly and DeepInheritance
LocalOnly	DeepInheritance	Properties Retrieved
True	True	ValueB and ValueC
True	False	ValueB
False	True	ValueA, ValueB and ValueC
False	False	ValueA and ValueB

IncludeQualifiers to specify whether or not qualifiers for each instance and property are to be returned. If support for qualifiers on instances is dropped by the DMTF then this parameter may also disappear.
IncludeClassOrigin to specify whether the name of the class in which the property or method was defined (possibly a superclass of this one) should be included in the response.
PropertyList to specify which properties of the instances should be returned. If you leave this parameter as NULL then all properties are returned. If the list contains names which are not properties of the class then the WBEM server is required to ignore those names and process the other items in the list.

Note that PropertyList, LocalOnly, and DeepInheritance all define the properties that are to be returned. The properties actually returned are the those common to all three parameters.

If successful, EnumerateInstances returns the requested instances. Otherwise it returns one of the following status codes:

CIM_ERR_ACCESS_DENIED to indicate that the WBEM client was not authorised to access the WBEM server with this request. Deciding whether the operator does or does not have the authorisation to carry out an operation lies primarily with the provider. This error might mean something as simple as the operator not having the right to access a particular file needed for the operation.
CIM_ERR_NOT_SUPPORTED to indicate that the WBEM server does not support this function. This should not occur if the WBEM server has previously supported the function but it may occur the first time that an intrinsic method is invoked. A WBEM client can, to some extent, ask the WBEM server what methods it supports but the standard allows the WBEM server to lie ”see page 250.
CIM_ERR_INVALID_NAMESPACE to indicate that the specified namespace does not exist.
CIM_ERR_INVALID_PARAMETER to indicate that at least one parameter is missing, duplicated , unrecognised or is otherwise incorrect.
CIM_ERR_INVALID_CLASS to indicate that the specified class does not exist.
CIM_ERR_FAILED to indicate that some other, unspecified error occurred.

If multiple errors occur then only the one earliest in this list is returned.

Sometimes it would be convenient for the provider handling an EnumerateInstances call from a WBEM client to return a different error code, indicating the type of error in an application-specific manner. At present, this is not possible, but a descriptive field is associated with each error and could be used by the provider to pass additional coded or free-text information.

The XML which would pass between the WBEM client and the WBEM server for an invocation of EnumerateInstances is given in Figure 7.5. Again, this is adapted from the openPegasus test suite and is therefore subject to the openPegasus licence. Notice again the IMETHODCALL parameter, this time with a name of EnumerateInstances. The parameters of the EnumerateInstances call follow in the remaining XML.

 <?xml version="1.0" ?> <CIM CIMVERSION="2.0" DTDVERSION="2.0">  <MESSAGE ID="51007" PROTOCOLVERSION="1.0">   <SIMPLEREQ>    <IMETHODCALL NAME="EnumerateInstances">     <LOCALNAMESPACEPATH>      <NAMESPACE NAME="root"/>      <NAMESPACE NAME="cimv2"/>     </LOCALNAMESPACEPATH>     <IPARAMVALUE NAME="ClassName">        <CLASSNAME NAME="CIM_ComputerSystem"/>     </IPARAMVALUE>     <IPARAMVALUE NAME="DeepInheritance">        <VALUE> FALSE </VALUE>     </IPARAMVALUE>     <IPARAMVALUE NAME="LocalOnly">        <VALUE> FALSE </VALUE>     </IPARAMVALUE>     <IPARAMVALUE NAME="IncludeQualifiers">        <VALUE> FALSE </VALUE>     </IPARAMVALUE>     <IPARAMVALUE NAME="IncludeClassOrigin">        <VALUE> FALSE </VALUE>     </IPARAMVALUE>    </IMETHODCALL>   </SIMPLEREQ>  </MESSAGE> </CIM>

Figure 7.5: Example XML for EnumerateInstances

Enumerating (i.e., Listing) Classes

The pseudocode for enumerating classes is as follows:

 <class>*EnumerateClasses (          [IN,OPTIONAL,NULL] <className> ClassName=NULL,          [IN,OPTIONAL] boolean DeepInheritance = false,          [IN,OPTIONAL] boolean LocalOnly = true,          [IN,OPTIONAL] boolean IncludeQualifiers = true,          [IN,OPTIONAL] boolean IncludeClassOrigin = false)

In this call:

The ClassName parameter defines the class for the enumeration and, if it is missing, all classes within the namespace are chosen .
DeepInheritance and LocalOnly are almost as complex as they are for EnumerateInstances :
- If DeepInheritance is true, then all subclasses of the specified class are returned. If it is false, then only immediate child subclasses are returned.
- If LocalOnly is true, then only CIM Elements (properties, methods, and qualifiers), defined or overridden within the definition of the selected class (i.e., not those of subclasses) are returned.
IncludeQualifiers specifies whether or not the qualifiers for each selected class should be returned.
IncludeClassOrigin specifies whether the CLASSORIGIN attribute should be returned. This field contains the name of the class in which the method or property was originally defined (possibly a superclass of the class being returned).

If successful, EnumerateClasses returns zero or more classes that meet the required criteria. If unsuccessful , EnumerateClasses returns one of the status codes described for EnumerateInstances above.

I give an example of the XML which might pass between the WBEM client and the WBEM server to invoke the EnumerateClasses method in Figure 7.6. Again note the use of the IMETHODCALL tag to indicate that this is an intrinsic method call and the SIMPLEREQ tag to indicate that only a single request is contained in the invocation. And, once again, this example is modified slightly from an openPegasus test program and so is subject to the openPegasus licence. If more than one method call were contained in the command then SIMPLEREQ would be replaced by MULTIREQ and any number of IMETHODCALLs and METHODCALLs could be included.

 <?xml version="1.0" encoding="utf-8"?> <CIM CIMVERSION="2.0" DTDVERSION="2.0">   <MESSAGE ID="42002" PROTOCOLVERSION="1.0">     <SIMPLEREQ>       <IMETHODCALL NAME="EnumerateClasses">         <LOCALNAMESPACEPATH>           <NAMESPACE NAME="test"/>           <NAMESPACE NAME="cimv2"/>         </LOCALNAMESPACEPATH>         <IPARAMVALUE NAME="ClassName">           <CLASSNAME NAME="CIM_ComputerSystem"/>         </IPARAMVALUE>         <IPARAMVALUE NAME="DeepInheritance">           <VALUE> FALSE </VALUE>         </IPARAMVALUE>         <IPARAMVALUE NAME="LocalOnly">           <VALUE> FALSE </VALUE>         </IPARAMVALUE>         <IPARAMVALUE NAME="IncludeQualifiers">           <VALUE> FALSE </VALUE>         </IPARAMVALUE>         <IPARAMVALUE NAME="IncludeClassOrigin">           <VALUE> FALSE </VALUE>         </IPARAMVALUE>       </IMETHODCALL>     </SIMPLEREQ>   </MESSAGE> </CIM>

Figure 7.6: Example XML for EnumerateClasses

Creating an Instance

I am sure that the pattern for these WBEM client operations is becoming clear; a straightforward function defined by the DMTF in pseudocode, possibly with a couple of nonintuitive parameters such as DeepInheritance and LocalOnly, and then a very straightforward mapping into XML.

Following this pattern, creating an instance is defined in pseudocode as follows:

 <instanceName>CreateInstance (         [IN] <instance> NewInstance)

It is hard to think of a simpler interface, but, of course, the parameter itself is more complex this time. This can be most easily seen by looking at the XML for a call to CreateInstance; see Figure 7.7 (again taken from the openPegasus test suite). This example creates an instance of the CIM_IndicationFilter class. At present you do not need to understand what this class does ”I explain it in detail on page 157 ”simply accept that such a class exists and has properties such as SystemName, SystemCreationClassName, and Query.

 <?xml version="1.0" encoding="utf-8"?> <CIM CIMVERSION="2.0" DTDVERSION="2.0">   <MESSAGE ID="53000" PROTOCOLVERSION="1.0">     <SIMPLEREQ>       <IMETHODCALL NAME="CreateInstance">         <LOCALNAMESPACEPATH>           <NAMESPACE NAME="root"/>           <NAMESPACE NAME="cimv2"/>         </LOCALNAMESPACEPATH>         <IPARAMVALUE NAME="NewInstance">           <INSTANCE CLASSNAME="CIM_IndicationFilter">            <PROPERTY NAME="SystemCreationClassName" TYPE="string">             <VALUE>CIM_UnitaryComputerSystem</VALUE>            </PROPERTY>            <PROPERTY NAME="SystemName" TYPE="string">             <VALUE>server001.acne.com</VALUE>            </PROPERTY>            <PROPERTY NAME="CreationClassName" TYPE="string">             <VALUE>CIM_IndicationFilter</VALUE>            </PROPERTY>            <PROPERTY NAME="Name" TYPE="string">             <VALUE>ACNESubscription12345</VALUE>            </PROPERTY>            <PROPERTY NAME="SourceNamespace" TYPE="string">              <VALUE>root/cimv2</VALUE>            </PROPERTY>            <PROPERTY NAME="Query" TYPE="string">             <VALUE>              SELECT Description, AlertType \                 FROM CIM_AlertIndication WHERE PerceivedSeverity = 3             </VALUE>            </PROPERTY>            <PROPERTY NAME="QueryLanguage" TYPE="string">             <VALUE>WQL</VALUE>            </PROPERTY>           </INSTANCE>         </IPARAMVALUE>       </IMETHODCALL>     </SIMPLEREQ>   </MESSAGE> </CIM>

Figure 7.7: Example XML for CreateInstance

Again the XML shows that CreateInstance is an intrinsic call (IMETHODCALL) and the general structure of the XML is:

 <IMETHODCALL NAME="CreateInstance">  <LOCALNAMESPACEPATH>   <NAMESPACE NAME="AAAAAA"/>  </LOCALNAMESPACEPATH>  <IPARAMVALUE NAME="NewInstance">   <INSTANCE CLASSNAME="CIM_IndicationFilter">    <PROPERTY NAME="XXXXXXXX" TYPE="YYYYYY">             <VALUE>ZZZZZZZZZ</VALUE>    </PROPERTY>   </INSTANCE>  </IPARAMVALUE> </IMETHODCALL>

where the PROPERTY tag is repeated for each property in the instance, each time giving the property's name, type, and value.

Deleting an Instance

With EnumerateInstances and CreateInstance well understood , you will find DeleteInstance trivial. Here is the pseudocode:

 void DeleteInstance([IN] <instanceName> InstanceName)

and the associated XML example taken from the openPegasus test suite is in Figure 7.8. The XML this time simply contains those properties that are keys on a CIM_IndicationFilter so that the WBEM server can uniquely identify the instance to be deleted; see Frequently Asked Question 27 on page 148.

 <?xml version="1.0" encoding="utf-8"?> <CIM CIMVERSION="2.0" DTDVERSION="2.0">   <MESSAGE ID="53000" PROTOCOLVERSION="1.0">     <SIMPLEREQ>       <IMETHODCALL NAME="DeleteInstance">         <LOCALNAMESPACEPATH>           <NAMESPACE NAME="root"/>           <NAMESPACE NAME="cimv2"/>         </LOCALNAMESPACEPATH>         <IPARAMVALUE NAME="InstanceName">           <INSTANCENAME CLASSNAME="CIM_IndicationFilter">             <KEYBINDING NAME="SystemCreationClassName">               <KEYVALUE VALUETYPE="string">                CIM_UnitaryComputerSystem               </KEYVALUE>             </KEYBINDING>             <KEYBINDING NAME="SystemName">               <KEYVALUE VALUETYPE="string">                server001.acne.com               </KEYVALUE>             </KEYBINDING>             <KEYBINDING NAME="CreationClassName">               <KEYVALUE VALUETYPE="string">                CIM_IndicationFilter               </KEYVALUE>             </KEYBINDING>             <KEYBINDING NAME="Name">               <KEYVALUE VALUETYPE="string">                ACNESubscription12345               </KEYVALUE>             </KEYBINDING>           </INSTANCENAME>         </IPARAMVALUE>       </IMETHODCALL>     </SIMPLEREQ>   </MESSAGE> </CIM>

Figure 7.8: Example XML for DeleteInstance

Traversing Associations

The Associators method and its companions References , ReferenceNames and AssociatorNames allow you to manipulate associations. Associations, however, are just normal classes and so can be manipulated with the class operations that we discussed above so these additional operations are convenient but not strictly required.

Associators and AssociatorNames are used to find out which instances are associated with a particular instance or which classes are associated with a particular class. The only difference between the operations is that Associators returns the whole object (using the strict definition of this word) and AssociatorNames returns only the names. The pseudocode for Associators is

 <objectWithPath>*Associators   (     [IN] <objectName> ObjectName,     [IN,OPTIONAL,NULL] <className> AssocClass = NULL,     [IN,OPTIONAL,NULL] <className> ResultClass = NULL,     [IN,OPTIONAL,NULL] string Role = NULL,     [IN,OPTIONAL,NULL] string ResultRole = NULL,     [IN,OPTIONAL] boolean IncludeQualifiers = false,     [IN,OPTIONAL] boolean IncludeClassOrigin = false,     [IN,OPTIONAL,NULL] string PropertyList [] = NULL )

This means, in effect, " please give me a list of all objects (instances or classes) which are associated with object Y." The additional properties allow the search to be pruned to include only objects which are associated through a specific association class or where the objects take particular roles in the association.

Note that Associators , References , ReferenceNames , and AssociatorNames differ from the other intrinsic methods in that they may operate on classes ("with what other classes is class A associated?") or on instances ("with what instances is instance B associated?"). Other intrinsic calls operate on either classes (e.g., DeleteClass ) or on instances (e.g., DeleteInstance ). If an Associators , References , ReferenceName or AssociatorNames request is made for a class then it is satisfied by the WBEM server; if the request is made for an instance then the WBEM server passes it to the appropriate provider if there is one.

References and ReferenceNames work similarly, returning not the objects at the far end of the references but the references themselves . These operations effectively answer the question, "By means of which associations is object A associated with anything?"

Executing Complex Queries

The ExecQuery method allows the WBEM client to make a database-style query request. The pseudocode for the operation is quite simple but hides a wealth of discussion and implementation issues for the WBEM server:

 <object>*ExecQuery (     [IN] string QueryLanguage,     [IN] string Query)

This call says, "Here is a query which I have encoded in the X query language." This is, of course, of little use unless the WBEM server can interpret the X query language and so the DMTF has thoughtfully provided a discovery mechanism, which I describe on page 249, to allow the WBEM client to determine which query languages the WBEM server supports.

DMTF specification DSP0200 makes no recommendation about particular query languages. In practice, two query languages are emerging, WQL and CQL, as described on page 158.