3.73 Query

Provides query information and actions. This object can represent either a stand-alone query (which does not persist in the message database) or a query associated with a query folder (which does persist in the message database).

3.73.1 Properties

The following table lists properties along with their access and descriptions.

Property	Access	Description
Application	R/O	Application. The Application object.
Completed	R/O	Boolean. TRUE if the query has finished or has never before been started. FALSE if the query is still executing. When logged into a remote database, a running query will not complete until the user synchronizes (downloads) the query results.
CompletionDate	R/O	Date. The date and time the query was last completed, or if the query is still in progress, the date and time of the last update.
Expression	R/W	DEFAULT. String. The filter expression to be matched. This can be set to NULL or an empty string (""). In either case, no filtering will be applied to the query. See Section 5.0, Filter Expressions.
Locations	R/O	Locations collection. The locations to be searched. Can contain Account, DocumentLibrary, and Folder objects.
Parent	R/O	Object. The Account object (for stand-alone queries) or Folder object (for query folders) that owns this object.
QueryMessages	R/O	MessageList. The messages that match the filter expression. Returns snapshots of the partial results if Completed = FALSE, or the final results if Completed = TRUE.
SearchLocally	R/W	Boolean. TRUE means execute the search locally, FALSE means execute the search on the master system (applies only when running Remote).
StartOnOpen	R/W	Boolean. TRUE means the client will automatically start the query when the query folder is opened. Affects only client behavior. Object API behavior is unaffected because folder objects are not opened.

3.73.2 Methods

Folder CreateFolder(String FolderName, [Folder ParentFolder]): Creates a new query folder based on this query. The new folder will have its own private query instance. FolderName is the name of the new folder. ParentFolder is the folder in which the new folder is created; if omitted, the new folder is created in the root folder. Returns the new folder.

Refresh()

Forces this Query object to reread property values from the message database.

If this Query object belongs to a query folder, the folder’s Messages collection is not refreshed (consider refreshing the folder instead). Use this method to obtain a new snapshot while the query is executing.
If the Query object belongs to a query folder, it is also refreshed when its owning Folder object is refreshed.
If the Query object is a stand-alone query, it is not refreshed when its owning Account object is refreshed.

The actual reading of a specific property may be postponed until the next time the property is accessed. This "lazy evaluation" is an optimization that avoids unnecessary reading of unaccessed properties. Because Refresh may be used to update the Completed property, the reading of the QueryMessages property should be postponed. The CompletionDate and QueryMessages properties must be in sync (they must be read as simultaneously as possible).

Start(): Starts execution of the query. Sets Completed to FALSE and causes the QueryMessages property, or the parent folder's Messages collection, to start returning partial results.

Stop(): Stops execution of the query. It issues a HALT command to the GroupWise Search Engine. The HALT is handled the next time a set of Search Results is returned. The Stop method does not set the Query.Completed flag to TRUE. You can take the current set of found messaages and start using them.

3.73.3 Procedures

To perform a query:

Call the Account object's CreateQuery method to create a new Query object.
Set the Query’s Expression, Location, and SearchLocally properties to the desired values.
Initiate the query by calling the Start method. Because queries can take some time, they execute asynchronously.
Poll the Completed property to determine when the query is done.

While the query is executing, QueryMessages returns snapshots of the partial results. (To examine the partial results, copy the QueryMessages collection to a variable and examine the variable, since QueryMessages returns a new snapshot each time it is accessed.) Once the query has completed, QueryMessages contains the final results.

To create a query folder:

Create a stand-alone Query object as described above, or access the Query object in an existing query folder.
Call the Query object's CreateFolder method to create the new query folder.

The query folder's query can be re-executed by calling Folder.Query.Start( ). The results, both partial and final, appear in Folder.Messages (Folder.Query.QueryMessages is always empty).

3.73.4 Remarks

When a Query object is refreshed, it recursively refreshes the Locations collection returned by its Location property. It also updates the Message objects by its QueryMessages property, but it does not recursively refresh the Messages objects themselves.