ICatalogManager3::FreeTextSearch Method [C++]

Article
11/12/2009

You can use this method to perform a free-text search of catalogs, however the recommended method to implement this functionality is the Search method.

Definition

[C++]

HRESULT ICatalogManager3::FreeTextSearch(BSTRstrPhrase,
  VARIANTstrCatalogsToSearch,
  VARIANTeClassTypeRequired,
  VARIANTstrPropertiesToReturn,
  VARIANTstrPropertyToSortOn,
  VARIANT_BOOLfSortAscending,
  VARIANTlStartingRecord,
  VARIANTlRecordsToRetrieve,
  VARIANT*plTotalRecordsInQuery,
  _Recordset**ppRSResult);

[Visual Basic]

Function FreeTextSearch(strPhrase As String,
  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 plTotalRecordsInQuery As Variant) As _Recordset

Parameters

strPhrase[C++]

[in] A BSTR that contains the search phrase.

strPhrase[Visual Basic]

A String that contains the search phrase.

strCatalogsToSearch[C++]

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

strCatalogsToSearch[Visual Basic]

A Variant that contains the catalogs to search in 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. This is a comma-delimited String.

strPropertiesToReturn[Visual Basic]

A Variant that contains the properties to return. This is a comma-delimited String.

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 strPropertiesToSortOn parameter. RANK is a built-in feature of the SQL Server search engine. FREETEXTSEARCH_RANK returns a value that contains the relevance ranking for each row (the value can be between 1-1000). The FREETEXTSEARCH_RANK property indicates how well a row matched the search phrase. In this method, it can be used only of the strFTSPhrase parameter is specified. You can specify the FREETEXTSEARCH_RANK in the PropertiestoReturn parameter and also rank results by specifying it in the PropertiesToSortOn parameter. For more information about RANK, see SQL Server 2000 online books at https://go.microsoft.com/fwlink/?LinkId=19235 and browse to RANK which is located at the bottom of the page.

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 strPropertiesToSortOn parameter. The FREETEXTSEARCH_RANK property indicates how well a row matched the search phrase. . In this method, it can be used only of the strFTSPhrase parameter is specified.

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 number of the starting record to retrieve. A value of one (1) indicates the first record.
lStartingRecord[Visual Basic]
A Variant that contains the number of 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 number of records returned in the search.
plTotalRecordsInQuery[Visual Basic]
A Variant used to return the number of records returned in the search.
ppRSResult[C++]
[out, retval] A pointer to a _Recordset object that will be used to return the query 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 that contains the search results.

Error Values

If the method fails then no error will be returned. In case of an error ppRSResult will be set to Null. The error will also be written to the event log.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

The following table describes the custom COM errors 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	Error. The recordset will be 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.

[Visual Basic] The recordset returned by this method contains valid data only if the method completes successfully.

The FreeTextSearch method is used to perform arbitrary lexical comparisons on words or phrases in one or more catalogs. The FreeTextSearch functionality in the Product Catalog System is based on full text indexing in SQL Server, and therefore, inherits keywords and operators from SQL Server for controlling the free text search.

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 cscProductClassORcscProductVariantClass will return both product and product variant data.

The search results for multilingual catalogs will be returned in a single language. The language will be selected differently depending 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, data will not be returned for the language sensitive properties. The properties will be returned in the recordset.

Use the Search method to specify the search language and for doing a free-text search and a query simultaneously.

The programming rules regarding the strPropertiesToReturn parameter vary depending on whether a single catalog name is passed in the strCatalogsToSearch parameter or whether 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, or when specifying the strPropertyToSortOn parameter, 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.

[C++] For more information, see CatalogProduct Recordset.

[Visual Basic] For more information, see CatalogProduct Recordset.

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