CatalogManager3.Search Method (PIA)

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

Definition

[Visual Basic .NET]

Imports Microsoft.CommerceServer.Interop.Catalog
Imports ADODB26Lib     ‘ for _Recordset
…
Public Function Search(Optional strSQLClause As Object ,
  Optional strFTSPhrase As Object ,
  Optional strCatalogsToSearch As Object ,
  Optional eClassTypeRequired As Object ,
  Optional strPropertiesToReturn As Object ,
  Optional strPropertyToSortOn As object ,
  Optional fSortAscending As Boolean,
  Optional lStartingRecord As Object ,
  Optional lRecordsToRetrieve As Object ,
  Optional varLanguage As Object ,
  Optional plTotalRecordsInQuery As Object) As _Recordset

[C#]

using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset Search(object strSQLClause,
  objectstrFTSPhrase,
  objectstrCatalogsToSearch,
  objecteClassTypeRequired,
  objectstrPropertiesToReturn,
  objectstrPropertyToSortOn,
  boolfSortAscending,
  objectlStartingRecord,
  objectlRecordsToRetrieve,
  objectvarLanguage,
  ref objectplTotalRecordsInQuery);

Parameters

[Visual Basic .NET]

• strSQLClause
  An Object that contains the SQL search query.
• strFTSPhrase
  An Object that contains the free-text search phrase.
• strCatalogsToSearch
  An Object that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
• eClassTypeRequired
  An Object that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
• strPropertiesToReturn
  An Object that contains the properties to return as a comma-separated list.
• strPropertyToSortOn
  An Object that contains the property on which to sort. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
• fSortAscending
  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
  An Object that contains the starting record to retrieve. A value of one (1) indicates the first record.
• lRecordsToRetrieve
  An Object that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
• varLanguage
  An Object that contains the ISO 639+1 language identifier.
• plTotalRecordsInQuery
  An Object used to return the total number of records matching the query.

[C#]

• strSQLClause
  An object that contains the SQL search query.
• strFTSPhrase
  An object that contains the free-text search phrase.
• strCatalogsToSearch
  An object that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.
• eClassTypeRequired
  An object that contains the catalog class wanted. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
• strPropertiesToReturn
  An object that contains the properties to return as a comma-separated list.
• strPropertyToSortOn
  An object that contains the property on which to sort. This must be a property in the returned recordset. If not included, the returned recordset will be unsorted.
• fSortAscending
  A 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. The default value is True.
• lStartingRecord
  An object that contains the starting record to retrieve. A value of one (1) indicates the first record.
• lRecordsToRetrieve
  An object that contains the number of records to retrieve, beginning from the starting record. A value of minus one (-1) indicates return all records.
• varLanguage
  An object that contains the ISO 639+1 language identifier.
• plTotalRecordsInQuery
  An object used to return the total number of records matching the query.

Return Values

[Visual Basic .NET] If this method completes successfully, it returns the _Recordset interface to a Recordset object that contains the search results.

[C#] This method returns a _Recordset interface to a Recordset object that will be used to return the query results.

Exceptions

This method may throw one of many mapped exceptions or an exception of type COMException. See Standard COM Errors for additional details.

The following table shows the custom COM errors that a COMException can wrap.

Remarks

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

The Search method is used to perform arbitrary lexical comparisons on words and phrases, and on 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 used specifically for searching within a category.

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 functions like the Query method. If you only supply the strFTSPhrase parameter, this method functions 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, and shows their associated names, and describes their use.

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

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

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows Server 2003

Assembly: cataloglib (in cataloglib.dll)

See Also

CatalogManager3 Class

Copyright © 2005 Microsoft Corporation.
All rights reserved.