Extrinsic Methods

Extrinsic operations are operations carried out by a method provider which may do anything. They may, for example, shut a system down, bring it up or perform any other complex operation.

In management systems such as SNMP, it is not possible to specify and invoke a particular function on a managed object ”the equivalent functionality is achieved by having a side effect associated with a property; change this property and that function is automatically performed. This is less intuitive than simply calling a method and more liable to inadvertent invocation by the unwary programmer or operator. WBEM therefore provides a very simple way of remotely invoking a function (method) on an instance of a class.

As an example, consider the PositionAtRecord() function on the CIM_MessageLog class, as defined in the System common model. The mof for this class is shown in Figure 7.9 and, as the description of the class says, a CIM_MessageLog is any form of logging device.

 [Version ("2.7.0"), Description (     "MessageLog represents any type of event, error or "     "informational register or chronicle. The object "     "describes the existence of the log and its "     "characteristics. Several methods are defined for "     "retrieving, writing and deleting log entries, and "     "maintaining the log.") ] class CIM_MessageLog : CIM_EnabledLogicalElement { // ==== many properties deleted    [Description (        "Requests that the Log's iteration identifier be "         "advanced or retreated a specific number of records, "         "or set to the entry at a specified numeric location. "         "=== much description deleted =__ ") ]    uint32 PositionAtRecord (        [IN, OUT]        string IterationIdentifier,        [IN, Description ("Advancing or retreating the "            "IterationIdentifier is achieved by setting the "            "MoveAbsolute boolean to FALSE, and specifying "            "the number of entries to advance or retreat "            "as positive or negative values in the RecordNumber "            "parameter. Moving to a specific record number is "            "accomplished by setting the MoveAbsolute parameter "            "to TRUE, and placing the record number into the            "RecordNumber parameter.") ]        boolean MoveAbsolute,        [IN, OUT]        sint64 RecordNumber);    };

Figure 7.9: mof for the PositionAtRecord Method

Once stripped of all of the descriptions, this fragment of the CIM_MessageLog mof defines a method, called PositionAtRecord(), which, very informally, has the following C++-style prototype:

 uint32 PositionAtRecord(char *IterationIdentifier,                         bool MoveAbsolute,                         long long *RecordNumber);

Note in passing the use of the IN and OUT qualifiers. These specify respectively that the parameter is an input to the PositionAtRecord function or is a returned (output) value. IterationIndentifier and RecordNumber are both: they are used to pass a value to PositionAtRecord and also bring a value back to the WBEM client.

The XML which the WBEM client would have to generate to invoke this function is listed in Figure 7.10. The namespace, name of the function, and values of the parameter are specified together with the key values of the instance to which the call is addressed. These allow the WBEM server to identify the instance and invoke a method with the given parameters. The PositionAtRecord function returns a uint32 value representing the success (zero) or failure (nonzero) of the method. The XML which would be returned by the CIM server to the client following successful completion is shown in Figure 7.11.

 <?xml version="1.0" encoding="utf-8" ?> <CIM CIMVERSION="2.0" DTDVERSION="2.0">  <MESSAGE ID="87872" PROTOCOLVERSION="1.0">   <SIMPLEREQ>    <METHODCALL NAME="PositionAtRecord">     <LOCALINSTANCEPATH>      <LOCALNAMESPACEPATH>       <NAMESPACE NAME="root"/>       <NAMESPACE NAME="cimv2"/>      </LOCALNAMESPACEPATH>      <INSTANCENAME CLASSNAME="CIM_MessageLog">       <KEYBINDING NAME="CreationClassName">        <KEYVALUE VALUETYPE ="string">ACNEComputing</KEYVALUE>       </KEYBINDING>       <KEYBINDING NAME="Name">        <KEYVALUE VALUETYPE ="string">PrivateLog</KEYVALUE>       </KEYBINDING>      </INSTANCENAME>     </LOCALINSTANCEPATH>     <PARAMVALUE NAME="IterationIdentifier">      <VALUE>ZZFRED762</VALUE>     </PARAMVALUE>     <PARAMVALUE NAME="MoveAbsolute">      <VALUE>true</VALUE>     </PARAMVALUE>     <PARAMVALUE NAME="RecordNumber">      <VALUE>145</VALUE>     </PARAMVALUE>    </METHODCALL>   </SIMPLEREQ>  </MESSAGE> </CIM>

Figure 7.10: XML for Invoking the PositionAtRecord Method

 <?xml version="1.0" encoding="utf-8" ?> <CIM CIMVERSION="2.0" DTDVERSION="2.0">  <MESSAGE ID="87872" PROTOCOLVERSION="1.0">   <SIMPLERSP>    <METHODRESPONSE NAME="SetPowerState">     <RETURNVALUE>      <VALUE>0</VALUE>     </RETURNVALUE>     <PARAMVALUE NAME="IterationIdentifier">      <VALUE>ZZHFGD653</VALUE>     </PARAMVALUE>     <PARAMVALUE NAME="RecordNumber">      <VALUE>145</VALUE>     </PARAMVALUE>    </METHODRESPONSE>   </SIMPLERSP>  </MESSAGE> </CIM>

Figure 7.11: XML Returned by PositionAtRecord Method

Most of the error codes which may be returned by the WBEM server following the invocation of an extrinsic method are the same as those described above for EnumerateInstances , but the new possibilities are:

CIM_ERR_METHOD_NOT_FOUND to indicate that the extrinsic method does not exist.
CIM_ERR_METHOD_NOT_AVAILABLE to indicate that, although the method exists, the CIM server was, for some reason, unable to invoke it.

Notice that, because of the query/response nature of the HTTP protocol, these extrinsic function invocations are effectively synchronous (i.e., the calling program (the client in this instance) is suspended until the result arrives back). Some work is being carried out within the DMTF to allow the invocation of extrinsic functions to be asynchronous (call and forget) but this has not reached maturity yet.