ICatalogManager::Query
.gif "Ee811700.c++_off(en-US,CS.10).gif")
.gif "Ee811700.vb_on(en-US,CS.10).gif")
Use this method to perform queries against product, variant, and category data in one or more catalogs.
Definition
HRESULT ICatalogManager::Query(BSTRstrPhrase,VARIANTstrCatalogsToSearch,VARIANTeClassTypeRequired,VARIANTstrPropertiesToReturn,VARIANTstrPropertyToSortOn,VARIANT_BOOLfSortAscending,VARIANTlStartingRecord,VARIANTlRecordsToRetrieve,VARIANT*plTotalRecordsInQuery,_Recordset**ppRSResult);
Parameters
strPhrase
[in] A BSTR that contains the search phrase.
strCatalogsToSearch
[in, optional] A VARIANT that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
eClassTypeRequired
[in, optional] A Variant that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.
strPropertiesToReturn
[in, optional] A VARIANT that contains the properties to return as a comma-separated list.
strPropertyToSortOn
[in, optional] A VARIANT that contains the property on which to sort.
fSortAscending
[in, defaultvalue (-1)] A VARIANT_BOOL that specifies whether to sort in ascending or descending order. A value of True indicates that the returned recordset will be sorted in ascending order. A value of False indicates that the returned recordset will be sorted in descending order.
lStartingRecord
[in, optional] A VARIANT that contains the starting record to retrieve. This is an offset from the first record.
lRecordsToRetrieve
[in, optional] A VARIANT that contains the number of records to retrieve, beginning from the starting record.
plTotalRecordsInQuery
[out, optional] A pointer to a VARIANT used to return the total number of records matching the query.
ppRSResult
[out, retval] A pointer to a _Recordset object used to return the search results.
Return Values
This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.
Error Values
This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.
The following table shows the custom COM errors that this method can return.
| Constant | Value | Description |
| E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | 0x8898000F | The strPropertiesToReturn parameter must be specified if the search is done across multiple catalogs. |
| E_CAT_NO_CATALOGS | 0x88980013 | There were no catalogs in the Product Catalog System. |
Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.
Remarks
The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully.
The Query method is used to perform arbitrary queries against product, product-variant, and category data in one or more catalogs. The strPhrase parameter is very similarly to the ADO recordset Filter property. Simple queries should follow the key-operator-value convention (for example, length < 100). Queries whose value is a String data type should enclose that value in single quotes (for example, color = 'Blue').
More sophisticated queries can be constructed by using the AND and OR operators to group multiple clauses, such as (level > 10) OR (Name = 'Bob' AND Title='CPA').
The programming rules regarding the strPropertiesToReturn parameter vary depending if a single catalog name is passed in the strCatalogsToSearch parameter, or if multiple catalog names are passed. When a single catalog name is passed, the strPropertiesToReturn parameter is optional and defaults to all properties. When multiple catalog names are passed, the strPropertiesToReturn parameter is required.
The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.
| Name | Value | Description |
| cscCategoryClass | 1 | Requests category data. |
| cscProductVariantClass | 2 | Requests product variant data. |
| cscProductClass | 4 | Requests product data. |
| cscProductFamilyClass | 8 | Requests product family data. |
| cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested. |
| CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested. |
CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.
If no value is specified for the strPropertiesToReturn parameter the method returns all fields in the specified catalog, otherwise it returns only the fields specified in the strPropertiesToReturn parameter.
For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.