ASSOCIATORS OF Statement

The ASSOCIATORS OF statement retrieves all instances that are associated with a particular source instance. The instances that are retrieved are referred to as the endpoints. Each endpoint is returned as many times as there are associations between it and the source object. For example, assume there are instances A, B, X, and Y. Two association instances exist, one that links A and X and another that links B and Y. The following query returns the single endpoint X:

ASSOCIATORS OF {A}

However, if there is another association linking A and X, the above query returns two X endpoints.

The basic syntax for the ASSOCIATORS OF statement is:

ASSOCIATORS OF {ObjectPath}

Note that the braces are part of the syntax. Any valid object path can be used for ObjectPath. The tokens within the object path cannot contain any white space. For example, the query in the following list returns instances that are associated with the specified logical disk:

Query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"}

Results:

Win32_Directory.Name="C:\\"

Win32_ComputerSystem.Name="mycomputer"
Win32_DiskPartition.DeviceID="Disk #0, Partition #0"

As with the SELECT statement, an ASSOCIATORS OF statement can include a WHERE clause, but the WHERE clause for an ASSOCIATORS OF statement is very different from the SELECT statementWHERE clause.

The WHERE clause of the ASSOCIATORS OF statement can include one or more of the following predefined keywords and their values:

ASSOCIATORS OF {ObjectPath} WHERE
    AssocClass = AssocClassName
    ClassDefsOnly
    RequiredAssocQualifier = QualifierName
    RequiredQualifier = QualifierName
    ResultClass = ClassName
    ResultRole = PropertyName
    Role = PropertyName

Note that the optional subclauses are not separated by commas.

The AssocClass keyword indicates that the returned endpoints must be associated with the source through the specified class or one of its derived classes. For example, the query in the following list returns only endpoints that are associated with the source through the Win32_SystemDevices association class or any of its derived classes:

Query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"} WHERE AssocClass = Win32_SystemDevices

Results:

Win32_ComputerSystem.Name="mycomputer"

The ClassDefsOnly keyword indicates that the clause returns a result set of class definition objects rather than actual instances of the classes. These objects are the definitions of classes to which the endpoint instances belong. For example, the query in the following list returns definitions for the Win32_Directory and Win32_ComputerSystem classes:

Query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"} WHERE ClassDefsOnly

Results:

Win32_Directory

Win32_ComputerSystem
Win32_DiskPartition

The ClassDefsOnly and ResultClass keywords are mutually exclusive. Using them together causes an invalid query error.

The RequiredAssocQualifier keyword indicates that the returned endpoints must be associated with the source object through an association class that includes the specified qualifier. This type of filtering is used to eliminate broad ranges of endpoints unless the endpoints are associated with the target through a particular set of tagged association classes. For example, the query in the following list returns endpoint instances if the association class includes a qualifier called Association.

Query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"}
   WHERE RequiredAssocQualifier = Association

Results:

Win32_Directory.Name="C:\\"

Win32_ComputerSystem.Name="mycomputer"
Win32_DiskPartition.DeviceID="Disk #0, Partition #0"

The RequiredQualifier keyword indicates that the returned endpoints associated with the source object must include the specified qualifier. The RequiredQualifier keyword can be used to include particular types of instances in the result set. For example, the query in the following list returns endpoint instances that include a qualifier called Locale.

Query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"} WHERE RequiredQualifier = Locale

Results:

Win32_Directory.Name="C:\\"

Win32_ComputerSystem.Name="mycomputer"
Win32_DiskPartition.DeviceID="Disk #0, Partition #0"

The ResultClass keyword indicates that the returned endpoints associated with the source object must belong to or be derived from the specified class. For example, the query in the following list returns endpoint instances that are derived from the CIM_Directory class:

Query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"} WHERE ResultClass = Cim_Directory

Results:

Win32_Directory.Name="C:\\"

The ClassDefsOnly and ResultClass keywords are mutually exclusive. Using them together causes an invalid query error.

The ResultRole keyword indicates that the returned endpoints must play a particular role in their association with the source object. The role is defined by the specified property, a reference property of type ref. For example, the ResultRole keyword can be used to retrieve all endpoints that have the GroupComponent property in their association with a source object, as the following query illustrates.

Query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"} WHERE ResultRole = GroupComponent

Results:

Win32_ComputerSystem.Name="mycomputer"

The Role keyword indicates that the returned endpoints participate in an association with the source object where the source object plays a particular role. The role is defined by the specified property, a reference property of type ref. For example, the Role keyword can be used to retrieve all endpoints associated with a source object that have the GroupComponent property, as the following query illustrates.

Query:

ASSOCIATORS OF {Win32_LogicalDisk.DeviceID="C:"}
   WHERE Role = GroupComponent

Results:

Win32_Directory.Name="C:\\"

Note

Complex queries cannot use "And" or "Or" to separate keywords for ASSOCIATORS OF and REFERENCES OF statements. Furthermore, the equal sign is the only valid operator that can be used in such queries. For example, the following query is valid:

 

ASSOCIATORS OF {win32_LogicalDisk="C:"} WHERE resultClass = Win32_Directory requiredQualifier = Dynamic

Note

The next examples are not valid. The first example does not use the equal sign and the second example erroneously attempts to use the AND keyword.

 

Associators of {win32_LogicalDisk="C:"} where resultClass = Win32_Directory requiredQualifier <> Dynamic

Associators of {win32_LogicalDisk="C:"} where resultClass = Win32_Directory AND requiredQualifier = Dynamic