Querying

The enumeration APIs return all instances in a class or class hierarchy. You can choose to return the instance names or the details of the instance. Querying allows you to narrow your search by specifying a query string. You can search for instances that match a specified query in a particular class or in all classes in a particular namespace. For example, you can search for all instances of the Solaris_DiskDrive class that have a particular value for the Storage_Capacity property.

The execQuery Method

The execQuery method retrieves an enumeration of CIM instances that match a query string. The query string must be formed using the WBEM Query Language (WQL).

Syntax

The syntax for the execQuery method is:

Enumeration execQuery(CIMObjectPath relNS, java.lang.String query, int ql)

The execQuery method takes the following parameters and returns an enumeration of CIM instances:

Example

The following execQuery call returns an enumeration of all instances of the CIM_device class in the current namespace.

cc.execQuery(new CIMObjectPath(), SELECT * FROM CIM_device, cc.WQL)

Using the WBEM Query Language

The WBEM Query Language is a subset of standard American National Standards Institute Structured Query Language (ANSI SQL) with semantic changes to support WBEM on Solaris. Unlike SQL, in this release WQL is a retreval-only language. You cannot use WQL to modify, insert, or delete information.

SQL was written to query databases, in which data is stored in tables with a row-column structure. WQL has been adapted to query data that is stored using the CIM data model. In the CIM model, information about objects is stored in CIM classes and CIM instances. CIM instances can contain properties, which have a name, data type, and value. WQL maps the CIM object model to SQL tables.

Supported WQL Key Words

The Sun WBEM SDK supports Level 1 WBEM SQL, which enables simple select operations without joins. The following table describes the WQL key words supported in the Sun WBEM SDK.

WBEM Query Language Operators

The following table lists the standard WQL operators that can be used in the WHERE clause of a SELECT statement.

Making a Data Query

Data queries are statements that request instances of classes. To issue a data query, applications use the execQuery method to pass a WBEM Query Language string to the CIM Object Manager.

The SELECT Statement

The SELECT statement is the SQL statement for retrieving information, with a few restrictions and extensions specific to WQL. Although the SQL SELECT statement is typically used in the database environment to retrieve particular columns from tables, the WQL SELECT statement is used to retrieve instances of a single class. WQL does not support queries across multiple classes.

The SELECT statement specifies the properties to query in an object specified in the FROM clause.

The basic syntax for the SELECT statement is:

SELECT instance FROM class

The following tables shows examples of using arguments in the SELECT clause to refine a search.

The WHERE Clause

You can use the WHERE clause to narrow the scope of a query. The WHERE clause can contain a property or key word, an operator, and a constant. All WHERE clauses must specify one of the predefined WQL operators.

The basic syntax for appending the WHERE clause to the SELECT statement is:

SELECT instance FROM class WHERE expression

The expression is composed of a property or key word, an operator, and a constant. You can append the WHERE clause to the SELECT statement using one of the following forms:

SELECT instance FROM class [[WHERE property operator constant]]

SELECT instance FROM class [[WHERE constant operator property]]

Valid WHERE clauses follow these rules:

• The value of the constant must be of the correct data type for the property.

• The operator must be one of the valid WQL operators listed in Table 4–4.

• Either a property name or a constant must appear on either side of the operator in the WHERE clause.

• Arbitrary arithmetic expressions cannot be used. For example, the following query returns only instances of the Solaris_Printer class that represent a printer with ready status:

  SELECT * FROM Solaris_Printer WHERE Status = “ready”

  The following is an invalid query:

  SELECT * FROM PhysicalDisk WHERE Partitions < (8 + 2 - 2)

Multiple groups of properties, operators, and constants can be combined in a WHERE clause using logical operators and parenthetical expressions. Each group must be joined with the AND, OR, or NOT operators as shown in the following table.