SWbemServices.ExecMethod method

The ExecMethod method of the SWbemServices object executes a method that is exported by a method provider. This method blocks while the method that is forwarded to the appropriate provider executes. The information and status are then returned. The provider, rather than WMI, implements the method.

This method is called in the synchronous mode. For more information, see Calling a Method.

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

Syntax

objOutParams = .ExecMethod( _
  ByVal strObjectPath, _
  ByVal strMethodName, _
  [ ByVal objWbemInParams ], _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ] _
)

Parameters

strObjectPath

Required. String that contains the object path of the object for which the method is executed. For more information, see Describing the Location of a WMI Object.

strMethodName

Required. Name of the method for the object.

objWbemInParams [optional]

An SWbemObject object that contains the input parameters for the method being executed. By default, this parameter is undefined. For more information, see Constructing InParameters Objects and Parsing OutParameters Objects.

iFlags [optional]

Reserved. This value must be zero.

objWbemNamedValueSet [optional]

Typically, this is undefined. Otherwise, this is an SWbemNamedValueSet 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 method is successful, an SWbemObject object is returned. The returned object contains the out parameters and return value for the method that is being executed.

Error codes

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

wbemErrFailed - 2147749889 (0x80041001)

Unspecified error.

wbemErrInvalidClass - 2147749904 (0x80041010)

Specified class was not valid.

wbemErrInvalidParameter - 2147749896 (0x80041008)

A specified parameter is not valid.

wbemErrOutOfMemory - 2147749894 (0x80041006)

Not enough memory to complete the operation.

wbemErrInvalidMethod - 2147749934 (0x8004102E)

Requested method was not available.

wbemErrAccessDenied - 2147749891 (0x80041003)

Current user was not authorized to execute the method.

Remarks

Use SWbemServices.ExecMethod as an alternative to direct access for executing a provider method in cases where it is not possible to execute a method directly. The ExecMethod method allows you to obtain output parameters, if the provider supplies them, with a scripting language that does not support output parameters. Otherwise, the recommended means of invoking a method is to use direct access. For more information, see Manipulating Class and Instance Information.

For example, the following code example that calls the StartService provider method in Win32_Service uses direct access.

oService = GetObject("winmgmts:Win32_Service=Alerter")
iStatus = oService.StartService()

This example calls SWbemServices.ExecMethod to execute the StartService method. Note that an object path is required because SWbemServices.ExecMethod is not operating on the object already, unlike SWbemObject.ExecMethod.

Set WbemServices = GetObject("winmgmts:")
Set oService = GetObject("winmgmts:Win32_Service='Alerter'")
Set oPath = GetObject("winmgmts:Win32_Service='Alerter'").Path_
WbemServices.ExecMethod oPath, "StartService"

The SWbemServices.ExecMethod method requires an object path. If the script already holds an SWbemObject object, use the SWbemObject.ExecMethod method.

Examples

The following example shows the ExecMethod method. The script creates a Win32_Process object that represents a process that is running Notepad. It shows the setting up of an InParameters object and how to obtain results from an OutParameters object. For a script that shows the same operations performed asynchronously, see SWbemServices.ExecMethodAsync. For an example of using direct access, see Create Method in Class Win32_Process. For an example of the same operation using an SWbemObject, see SWbemObject.ExecMethod.

' Connect to WMI
set Services = getobject("winmgmts:root\cimv2")

' Obtain the class definition object of a Win32_Process object.
Set oProcess = Services.Get("Win32_Process")

' Create the SWbemMethod.InParameters object
' to hold the input parameter needed
' for the Win32_Process.Create method call.
' The oProcess.Methods_("Create") call
' obtains obtains a class object that
' defines the correct input parameters
' for the Win32_Process.Create call.
' The InParameters object is an 
' SWbemObject object so SWbemObject.SpawnInstance_ 
'can be called to create it.

Set oInParams = _
    oProcess.Methods_("Create").InParameters.SpawnInstance_
oInParams.CommandLine = "Notepad.exe"

'Call SWbemServices.ExecMethod with the WMI path Win32_Process
Set oOutParams = _
    Services.ExecMethod( "Win32_Process", "Create", oInParams)

If oOutParams.ReturnValue = 0 Then
    wscript.echo "Create method executed successfully."
Else
' If the Create method failed to execute,
' an empty OutParameters object is returned. 
    If IsNull(oOutParams.ReturnValue) Then
        wscript.echo "Create method failed to execute."  
    Else
        wscript.echo "Create method executed" _
            & " but had error " _
            & "0x" & hex(oOutParams.ReturnValue)
    End If
End If

Requirements

See also

SWbemServices

SWbemObject.ExecMethod_

Calling a Provider Method

Manipulating Class and Instance Information