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.

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.

Value	Meaning
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.

 

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 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 table.

Remarks

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

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application 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.Get

Querying with WQL

Send comments about this topic to Microsoft

Build date: 11/19/2012