IReposQuery::GetCollection

IReposQuery::GetCollection

This method is used to filter relationship collections in a workspace or in the whole repository.

Syntax

HRESULT GetCollection(
    BSTR Filter,
    long Flags
    IObjectCol2 **ppObjCol

);

Parameters

Filter

[in]
A text string that limits the objects that appear in the collection. This string can be a maximum of 255 characters in length.

Flags

[in]
An optional parameter to control the synchronicity of the query (default = 0). The following flag values are supported.

Flag enumerator	Value	Description
FILTERCOL_SYNCH	0	The collection is fetched synchronously (default).
FILTERCOL_ASYNCH	2	The collection is fetched asynchronously. The collection pointer returned is an IObjectCol2 interface, which can be used to query the status of the asynchronous fetch.

*ppObjCol

[out, retval]
A pointer to the object collection.

Filter Text String

The text string of the Filter parameter is case insensitive. The engine will return an error code if the syntax of the Filter parameter is wrong. The Filter parameter obeys these rules:

1. The string format is based on the SQL WHERE clause format. For example,

   [PROPA] = 'employee' AND [PROPB]>10.
   

2. Property names are provided in the format:

   [property identifier]
   

   where the property identifier can either be the object identifier of the property definition, or in the format:

   typelib.interface.property.
   

   As a result, any occurrence of the character [ has to be escaped if it is not marking the start of a property identifier. The escape sequence is \ (that is, you must use \[ whenever you want to specify [ ).

   If the typelib or the interface part is omitted, the following rules apply:

   • If the filtering applies to a relationship collection, the omitted type library is assumed to be the same as the type library in which the relationship collection was defined. In addition, the omitted interface name is assumed to be the same as the target
     
     
   • If filtering applies to the repository session, an E_REP_UNKNOWNPROPERTY error is returned.
3. The following operators are supported:
   • The Boolean operators AND, OR, and NOT.
     
     
   • The comparison operators =, <, <=, >, >=, IN, and LIKE.
     
     
   • Grouping of conditions by parentheses.
4. The following special, case-insensitive clauses are supported:
   • InstanceOf (class definition list)

     The class definition list is a comma-delimited list of class definition object identifiers. The collection returned contains those objects that are instances of these class definitions. The list elements are considered to be connected together by the OR logical operator.

   • Implements (interface definition list)

     The interface definition list is a comma-delimited list of interface definition object identifiers. The collection returned contains those objects that support the interfaces given. The list elements are considered to be connected together by the OR logical operator.

5. If the Filter parameter is empty, all objects in the collection are returned.

   The Filter parameter can include an Order By clause that accepts a comma-separated list of property names. The property names follow the same rules as property names in the selection part of the Filter parameter.

   The following is an example of a valid Filter parameter:

   [FirstName]='Jason' AND [Age]>20 ORDER BY [LastName]
   

Return Value

S_OK

The method completed successfully.

Error Values

This method failed to complete successfully.

See Also

Filtering Collections

Filtering Derived Collections

IReposQuery Interface