SWbemServices.ExecQuery method

The ExecQuery method of the SWbemServices object executes a query to retrieve objects. These objects are available through the returned SWbemObjectSet collection.

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

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

Syntax

objWbemObjectSet = .ExecQuery( _
  ByVal strQuery, _
  [ ByVal strQueryLanguage ], _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ] _
)

Parameters

strQuery

Required. String that contains the text of the query. This parameter cannot be blank. For more information on building WMI query strings, see Querying with WQL and the WQL reference.

strQueryLanguage [optional]

String that contains the query language to be used. If specified, this value must be "WQL".

iFlags [optional]

Integer that determines the behavior of the query and determines whether this call returns immediately. The default value for this parameter is wbemFlagReturnImmediately. This parameter can accept the following values.

wbemFlagForwardOnly (32 (0x20))

Causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but they do not allow calls to SWbemObject.Clone_.

wbemFlagBidirectional (0 (0x0))

Causes WMI to retain pointers to objects of the enumeration until the client releases the enumerator.

wbemFlagReturnImmediately (16 (0x10))

Causes the call to return immediately.

wbemFlagReturnWhenComplete (0 (0x0))

Causes this call to block until the query is complete. This flag calls the method in the synchronous mode.

wbemQueryFlagPrototype (2 (0x2))

Used for prototyping. This flag stops the query from happening and returns an object that looks like a typical result object.

wbemFlagUseAmendedQualifiers (131072 (0x20000))

Causes WMI to return class amendment data with the base class definition. For more information, see Localizing WMI Class Information.

Return value

If no error occurs, this method returns an SWbemObjectSet object. This is an object collection that contains the result set of the query. The caller can examine the collection using the implementation of collections for the programming language you are using. For more information, see Accessing a Collection.

Error codes

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

wbemErrAccessDenied - 2147749891 (0x80041003)

Current user does not have the permission to view the result set.

wbemErrFailed - 2147749889 (0x80041001)

Unspecified error.

wbemErrInvalidParameter - 2147749896 (0x80041008)

Invalid parameter was specified.

wbemErrInvalidQuery - 2147749911 (0x80041017)

Query syntax is not valid.

wbemErrInvalidQueryType - 2147749912 (0x80041018)

Requested query language is not supported.

wbemErrOutOfMemory - 2147749894 (0x80041006)

Not enough memory to complete the operation.

Remarks

ExecQuery is one of the most commonly-used calls to retrieve WMI information. A standard call to ExecQuery looks like the following:

strComputer = "."
Set objWMIService = GetObject("winmgmts:" & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")

Set colServices = objWMIService.ExecQuery ("Select * from Win32_Service where Name='Alerter'")
For Each objService in colServices
    Return = objService.StopService()
    If Return <> 0 Then
        Wscript.Echo "Failed " &VBNewLine & "Error code = " & Return 
    Else
       WScript.Echo "Succeeded"
    End If
Next

Note that you create the SWbemServices object with a moniker that represents the appropriate namespace and security, then make the ExecQuery call through the service. For a more complete discussion, see Creating a WMI Script and Enumerating WMI.

Like the InstancesOf method, the ExecQuery method always returns an SWbemObjectSet collection. Thus your WMI script must enumerate the collection ExecQuery returns in order to access each managed resource instance in the collection, as shown here:

strComputer = "."
Set objSWbemServices = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set colSWbemObjectSet = objSWbemServices.ExecQuery _
   ("SELECT * FROM Win32_Service")
For Each objSWbemObject In colSWbemObjectSet
    Wscript.Echo "Name: " & objSWbemObject.Name
Next

Other SWbemServices methods that return an SWbemObjectSet include AssociatorsOf, ReferencesTo, and SubclassesOf.

It is not an error for the query to return an empty result set. The ExecQuery method returns key properties whether or not the key property is requested in the strQuery argument. If an error occurs when executing this method and you do not use the wbemFlagReturnImmediately flag, the Err object is not set until you attempt to access the returned object set. However, if you use the wbemFlagReturnWhenComplete flag, the Err object is set when the ExecQuery method is called.

There are limits to the number of AND and OR keywords that can be used in WQL queries. Large numbers of WQL keywords that are used in a complex query can cause WMI to return the WBEM_E_QUOTA_VIOLATION error code as an HRESULT value. The limit of WQL keywords depends on how complex the query is.

Examples

The following VBScript code example locates all the disk drives on the local computer and displays the device ID and the type of the disk drive.

Set colDisks = GetObject( _
    "Winmgmts:").ExecQuery("Select * from Win32_LogicalDisk")
For Each objDisk in colDisks
 
    Select Case objDisk.DriveType
        Case 1
            Wscript.Echo "No root directory. Drive type could not be determined."
        Case 2
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Removable drive" 
        Case 3
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Local hard disk" 
        Case 4
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Network disk" 
        Case 5
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Compact disk" 
        Case 6
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = RAM disk" 
        Case Else
            Wscript.Echo "Drive type could not be determined."
    End Select
Next

Requirements

See also

SWbemServices

SWbemServices.Get

Querying with WQL

Creating a WMI Script

Enumerating WMI