SWbemObject.Put_ method

Article
01/07/2021

The Put_ method of SWbemObject creates or updates an instance or a class object to Windows Management Instrumentation (WMI). You can use this method after you modify any properties or methods in an SWbemObject, and your changes are written to WMI.

For an explanation of this syntax, see Document Conventions for the Scripting API.

Syntax

objObjectPath = .Put_( _
  [ ByVal iFlags ], _
  [ ByVal objwbemNamedValueSet ] _
)

Parameters

iFlags [in, optional]

This parameter determines if the call creates or updates the class or instance and if the call returns immediately. This parameter can accept the following values.

wbemChangeFlagUpdateCompatible (0 (0x0))

Allows a class to be updated if there are no derived classes and there are no instances for that class. It also allows updates in all cases if the change is just to unimportant qualifiers (for example, the Description qualifier). This is the default behavior for this call and is used for compatibility with previous versions of WMI. If the class has instances the update fails.

wbemChangeFlagUpdateSafeMode (32 (0x20))

Allows updates of classes even if there are child classes if the change does not cause any conflicts with child classes. You can use this flag when adding a new property to a base class that was not previously mentioned in any of the child classes. If the class has instances the update fails. If the class has instances the update fails.

WbemChangeFlagUpdateForceMode (64 (0x40))

This flag forces updates of classes when conflicting child classes exist. For example, this flag will force an update if a class qualifier was defined in a child class, and the base class tries to add the same qualifier and in conflict with the existing one. In force mode this conflict would be resolved by deleting the conflicting qualifier in the child class. If the class has instances the update will fail.

Using force mode to update a static class results in the deletion of all instances of that class. A forced update on a provider class does not delete instances of the class.

wbemChangeFlagCreateOrUpdate (0 (0x0))

Causes the class or instance to be created if it does not exist or overwritten if it exists already.

wbemChangeFlagCreateOnly (2 (0x2))

Used for creation only. The call fails if the class or instance already exists.

wbemChangeFlagUpdateOnly (1 (0x1))

Causes this call to update. The class or instance must exist for the call to be successful.

wbemFlagReturnImmediately (16 (0x10))

Causes the call to return immediately.

wbemFlagReturnWhenComplete (0 (0x0))

Causes this call to block until the query has completed.

wbemFlagUseAmendedQualifiers (131072 (0x20000))

Causes WMI to write class amendment data as well as the base class definition. For more information about amended qualifiers, see Localizing WMI Class Information.

objwbemNamedValueSet [in, optional]

Typically, this is undefined. Otherwise, this is an SWbemObjectPath object whose elements represent the context information that can be used by the provider that is servicing the request. A provider that supports or requires such information must document the recognized value names, data type of the value, allowed values, and semantics.

Return value

If the call is successful, an SWbemObjectPath object is returned. This object contains the object path of the instance or class that has been successfully committed to WMI.

Error codes

After the completion of the Put_ method, the Err object may contain one of the error codes in the following list.

wbemErrAccessDenied - 2147749891: Current user does not have permission to update an instance of the specified class.
wbemErrAlreadyExists - 2147749913 (0x80041019): The wbemChangeFlagCreateOnly flag was specified, but the instance already exists.
wbemErrFailed - 2147749889 (0x80041001): Unspecified error.
wbemErrIllegalNull - 2147749898 (0x8004100A): A value of Nothing was specified for a property that may not be Nothing. An example of such a property is one marked by a Key, Indexed, or Not_Null qualifier.
wbemErrInvalidObject - 2147749908 (0x80041014): The specified instance is not valid.
wbemErrInvalidParameter - 0x80041008: A specified parameter is not valid.
wbemErrNotFound - 2147749890 (0x80041002): The wbemChangeFlagUpdateOnly flag was specified, but the instance or class does not exist.
wbemErrIncompleteClass - 2147749920 (0x80041020): Required properties for classes have not all been set.
wbemErrOutOfMemory - 2147749894 (0x80041006): Not enough memory to complete the operation.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Header	Wbemdisp.h
Type library	Wbemdisp.tlb
DLL	Wbemdisp.dll
CLSID	CLSID_SWbemObject
IID	IID_ISWbemObject