Share via

ICategory3::Search Method [C++]

  • Article

Use this method to perform queries against product, variant, and category data in this category, and, optionally, all of the descendent categories for this category.

Definition

[C++]

HRESULT ICategory3::Search(VARIANTstrSQLClause,
  VARIANTstrFTSPhrase,
  VARIANT_BOOLfRecursive,
  VARIANTeClassTypeRequired,
  VARIANTstrPropertiesToReturn,
  VARIANTstrPropertyToSortOn,
  VARIANT_BOOLfSortAscending,
  VARIANTlStartingRecord,
  VARIANTlRecordsToRetrieve,
  VARIANT*plTotalRecordsInQuery,
  _Recordset**ppRSResult);

[Visual Basic]

Function Search(Optional strSQLClause As Variant,
  Optional strFTSPhrase As Variant,
  Optional fRecursive As Boolean,
  Optional eClassTypeRequired As Variant,
  Optional strPropertiesToReturn As Variant,
  Optional strPropertyToSortOn As Variant,
  Optional fSortAscending As Boolean,
  Optional lStartingRecord As Variant,
  Optional lRecordsToRetrieve As Variant,
  Optional plTotalRecordsInQuery As Variant) As Recordset

Parameters

  • strSQLClause[C++]
    [in, optional] A VARIANT that contains the SQL search query.
  • strSQLClause[Visual Basic]
    A Variant that contains the SQL search query.
  • strFTSPhrase[C++]
    [in, optional] A VARIANT that contains the free-text search phrase.
  • strFTSPhrase[Visual Basic]
    A Variant that contains the free-text search phrase.
  • fRecursive[C++]
    [in, optional, defaultvalue (-1)] A VARIANT_BOOL that specifies whether the query is recursive, that is, whether the scope of the query includes all descendent categories. A value of True (-1) indicates that the query is recursive. A value of False (0) indicates that the query is not recursive.
  • fRecursive[Visual Basic]
    A Boolean that specifies whether the query is recursive, that is, whether the scope of the query includes all descendent categories. A value of True indicates that the query is recursive. A value of False indicates that the query is not recursive. The default value is True.
  • eClassTypeRequired[C++]
    [in, optional] A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
  • eClassTypeRequired[Visual Basic]
    A Variant that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
  • strPropertiesToReturn[C++]
    [in, optional] A VARIANT that contains the properties to return as a comma-separated list.
  • strPropertiesToReturn[Visual Basic]
    A Variant that contains the properties to return as a comma-separated list.
  • strPropertyToSortOn[C++]
    [in, optional] A VARIANT that contains the property on which to sort. This must be a property in the returned recordset.
  • strPropertyToSortOn[Visual Basic]
    A Variant that contains the property on which to sort. This must be a property in the returned recordset.
  • fSortAscending[C++]
    [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.
  • fSortAscending[Visual Basic]
    A Boolean 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. The default value is True.
  • lStartingRecord[C++]
    [in, optional] A VARIANT that contains the starting record to retrieve. A value of one (1) indicates the first record.
  • lStartingRecord[Visual Basic]
    A Variant that contains the starting record to retrieve. A value of one (1) indicates the first record.
  • lRecordsToRetrieve[C++]
    [in, optional] A VARIANT that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
  • lRecordsToRetrieve[Visual Basic]
    A Variant that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
  • plTotalRecordsInQuery[C++]
    [out, optional] A pointer to a VARIANT used to return the total number of records matching the query.
  • plTotalRecordsInQuery[Visual Basic]
    A Variant used to return the total number of records matching the query.
  • ppRSResult[C++]
    [out, retval] A pointer to a _Recordset object used to return the search results.

Return Values

[C++] This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[Visual Basic] If this method completes successfully, it returns a Recordset object containing the search results.

The following table describes the COM errors this method can return.

Constant Value Description
E_CAT_INVALID_RS_POINTER

[C++] 0x889800B7

[Visual Basic] &H889800B7

 The recordset pointer that you specified is invalid
E_INVALIDARG

[C++] 0x80070057

[Visual Basic] &H80070057

 One or more arguments are invalid
E_CAT_INVALID_SEARCH_CLAUSE

[C++] 0x8898011C

[Visual Basic] &H8898011C

 The search condition that you specified is invalid for one of the following reasons: It contains -- or /* which should not be used outside of property names and property values The parentheses in the search condition do not match in number or alignment.
E_CAT_INVALID_RETURN_PROPS

[C++] 0x8898011D

[Visual Basic] &H8898011D

 The properties to return that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.
E_CAT_INVALID_SORT_PROPS

[C++] 0x8898011E

[Visual Basic] &H8898011E

 The properties to sort that you specified are invalid. Properties that contain a space should be enclosed in square brackets. Properties should not contain [ or ] and /* or -- in property names.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. 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.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

[C++]

The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully.

This method is very similar to the ICatalogManager3.Query method. The primary difference is that this method returns results limited to a single category, and, optionally all the descendent categories for this category. Multilingual results will be returned in the language specified by the IProductCatalog3::get_Language method of the catalog that contains this category.

[Visual Basic]

The returned Recordset object and the plTotalRecordsInQuery parameter contain valid data only if the method completes successfully.

This method is very similar to the CatalogManager.Search method. The primary difference is that this method returns results limited to a single category, and, optionally all descendent categories for this category. Multilingual results will be returned in the language specified in the ProductCatalog.Language property of the catalog that contains this category.

The Search method is used to perform arbitrary lexical comparisons on both words and phrases, product, product-variant, and category data in one or more catalogs. It combines the functionality of the Query method and the FreeTextSearch method.

The strSQLClause and strFTSPhrase parameters are both optional, but at least one of them must be supplied. If you only supply the strSQLClause parameter, this method acts like the Query method. If you only supply the strFTSPhrase parameter, this method acts like the FreeTextSearch method. If you supply both parameters, then only data that satisfies both search conditions will be returned. This allows you to construct sophisticated and very specific searches.

The strPropertiesToReturn parameter is optional and defaults to all properties.

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.

The CatalogClassTypeEnum enumeration values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClassORcscProductVariantClass 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.

[Visual Basic]

Example

'plTotalRecordsInQuery is an existing Long. 
'Examine it after the method returns to see if 
'there are more records to get.
Set rsResults = myCategory3.Query("[Productid]='blue suede'", "slightly scuffed", True, cscProductClass, "Price, SKU, Size", "SKU", TRUE, 1, 25, plTotalRecordsInQuery)

See Also

[C++]Category Object

[Visual Basic]Category Object

CatalogManager.Search

Copyright © 2005 Microsoft Corporation.
All rights reserved.