Updating Part of an Instance
Occasionally, you may want to update only part of an instance. For example, some instances have a large number of properties. If you had to update a large number of these instances, you may reduce system performance. Therefore, you can choose to update only part of the instance, and thus reduce the amount of information you must send and retrieve to and from WMI. However, WMI does not directly support partial-instance operations, nor do most providers. Therefore, if you write an application that uses partial-instance operations, be prepared for your calls to fail with either the WBEM_E_PROVIDER_NOT_CAPABLE or WBEM_E_NOT_SUPPORTED error code in C++. In scripting languages the error codes are either wbemErrProviderNotCapable or wbemErrNotSupported.
In scripting, this operation is only necessary to aid performance when updating one or two writeable properties in a very large number of objects over an enterprise. Otherwise, the normal calls to SWbemObject.Put_ or SWbemObject.PutAsync_, while seeming to write the entire object, are actually only updating the properties which the provider has write-enabled.
The following procedure describes how to request a partial-instance update using VBScript.
To request a partial-instance update using VBScript
- Create an SWbemNamedValueSet context object.
- Add the Put extension values __PUT_EXTENSIONS and __PUT_EXT_CLIENT_REQUEST to the context object using the SWbemNamedValueSet.Add method.
- Set up an array listing the names of the properties to be updated and add this array to the SWbemNamedValueSet context object with the Put extension value __PUT_EXT_PROPERTIES.
- Set the iFlags parameter of the SWbemObject.Put_ call to wbemChangeFlagUpdateOnly. Without this flag the call will fail with an invalid context.
- Pass your flag and context object to the provider in the objwbemNamedValueSet parameter of either SWbemObject.Put_ or SWbemObject.PutAsync_.
The following procedure describes how to request a partial-instance update using C++.
To request a partial-instance update using C++
- Create an
IWbemContext object with a call to CoCreateInstance.
A context object is an object that WMI uses to pass in more information to a WMI provider. In this case, you are using the IWbemContext object to instruct the provider to accept partial-instance updates.
- Add the __PUT_EXTENSIONS and __PUT_EXT_CLIENT_REQUEST named values to the
IWbemContext object with a call to IWbemContext::SetValue.
The following table lists the meaning of __PUT_EXTENSIONS and __PUT_EXT_CLIENT_REQUEST.
Named value Description __PUT_EXTENSIONS VT_BOOL set to VARIANT_TRUE. A value indicating that one or more of the other context values has been specified. This allows a quick check of the context object inside the provider to determine if partial-instance updates are being used. __PUT_EXT_CLIENT_REQUEST VT_BOOL set to VARIANT_TRUE. Set by the client during the initial request. This value is used to prevent reentrancy errors.
- Add the __PUT_EXT_STRICT_NULLS, __PUT_EXT_PROPERTIES, or __PUT_EXT_ATOMIC in any combination as needed to the
IWbemContext object with another call to IWbemContext::SetValue.
The following table lists the meaning of the named values.
Named value Description __PUT_EXT_STRICT_NULLS VT_BOOL set to VARIANT_TRUE. Indicates that the client has intentionally set properties to VT_NULL and expects the write operation to succeed. If the provider cannot set the values to NULL, an error should be reported. __PUT_EXT_PROPERTIES SAFEARRAY of strings containing a list of property names to be updated. May be used alone or in combination with __PUT_EXT_PROPERTIES. The values are in the instance being written. __PUT_EXT_ATOMIC VT_BOOL set to VARIANT_TRUE. Indicates that all updates must succeed simultaneously (atomic semantics) or the provider must revert back. There can be no partial success. May be used alone or in combination with other flags.
- Set the iFlags parameter to WBEM_FLAG_UPDATE_ONLY. Without this flag the call will fail with an invalid context.
- Pass the
IWbemContext context object into any calls IWbemServices::PutInstance or IWbemServices::PutInstanceAsync in the pCtx parameter.
Passing the IWbemContext object instructs the provider to allow partial-instance updates. In a full-instance update, you would set pCtx to NULL.
The provider may write any necessary properties if the context object present in the call does not contain __PUT_EXTENSIONS. If __PUT_EXTENSIONS is present in the context object, WMI requires the provider to either obey the semantics of the operation exactly or else fail the call. For more information, see Handling Access Denied Messages in a Provider.