ICatalogManager3::Search [C++]

Article
11/12/2009

Use this method to perform searches against product, variant, and category data in one or more catalogs. This method combines the abilities of the Query and FreeTextSearch methods while adding the ability to specify the language of the returned data.

Definition

[C++]

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

[Visual Basic]

Function Search(Optional strSQLClause As Variant,
  Optional strFTSPhrase As Variant,
  Optional strCatalogsToSearch As Variant,
  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 varLanguage 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.

strCatalogsToSearch[C++]

[in, optional] A VARIANT that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.

strCatalogsToSearch[Visual Basic]

A Variant that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.

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. To search. by rank, you must pass the FREETEXTSEARCH_RANK key to the strPropertyToSortOn parameter.

strPropertyToSortOn[Visual Basic]

A Variant that contains the property on which to sort. This must be a property in the returned recordset. To search by rank, you must pass the FREETEXTSEARCH_RANK key to the strPropertyToSortOn parameter.

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.
varLanguage[C++]
[in, optional] A VARIANT that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
varLanguage[Visual Basic]
A Variant that contains the culture name. The culture name follows the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>" where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase two-letter code derived from ISO 3166. Some culture names have prefixes that specify the script; for example, "Cy" specifies the Cyrillic script, and "Lt" specifies the Latin script. For more information, see . Table of Language Culture Names, Culture Codes, and ISO Values.
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.

Error Values

[C++] 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.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM 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.

Name	Value	Description
E_CAT_CATMGR_NOT_INITIALIZED	[C++] 0x889800B [Visual Basic] &H8898005	The CatalogManager object has not been initialized. The CatalogManager object should be initialized before calling this method.
E_CAT_INVALID_RS_POINTER	[C++] 0x889800B [Visual Basic] &H8898007	The recordset pointer that you specified is invalid.
E_INVALIDARG	[C++] 0x8007005 [Visual Basic] &H8007007	One or more arguments are invalid.
E_CAT_INVALID_RETURN_PROPS	[C++] 0x8898011 [Visual Basic] &H889801D	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++] 0x8898011 [Visual Basic] &H889801E	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.
S_FALSE	1	The search Failed. The recordset is now set to NULL.
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS	[C++] 0x8898000 [Visual Basic] &H889800F	When performing a query against multiple catalogs, you should specify the actual properties to return.

Remarks

[C++] The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully.The error will also be written to the windows event log.

[Visual Basic] The returned Recordset object and the plTotalRecordsInQuery parameter contain valid data only if the method completes successfully. The error will also be written to the windows event log.

The Search method is used to perform arbitrary lexical comparisons on both words and phrases, and product, product-variant, and category data in one or more catalogs. It combines the functionality of the Query method and the FreeTextSearch method. It also adds the varLanguage parameter, which allows you to specify the language of the search. The Category.Search method is a related method specifically for searching within a category.

The strSQLClause and strFTSPhrase parameters are both optional. 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 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 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 the varLanguage parameter is omitted the default value will depend on the number of catalogs specified in the strCatalogsToSearch parameter. If a single catalog is specified, the results will be returned in the default language of the catalog. If multiple catalogs are specified, the results will be returned in the default system language of the Web server. If a catalog does not support the selected language only language insensitive properties will be returned for that catalog.

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.

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. When specifying properties to return , and when specifying the strPropertyToSortOn paramenter, enclose the field names in square brackets to avoid unintentional side effects in the SQL query created by this method. For example, use "[Property1], [Property2]" to specify two properties.

While doing a free-text search you can also specify FREETEXTSEARCH_RANK as a property to return and property to sort on. FREETEXTSEARCH_RANK contains a relevance ranking value for each row in the recordset.The FREETEXTSEARCH_RANK specifies the relative closeness of this row to the value passed in strPhrase parameter. You can specify the FREETEXTSEARCH_RANK in the PropertiestoReturn parameter and also rank results by specifying it in the PropertiesToSortOn parameter. In this method, this parameter can be used only if the srtFTSPhrase parameter is specified.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.