Share via

ProductCatalog3.GuaranteedSpecificationSearch Method (PIA)

  • Article

Use this method to guarantee results when performing a specification search of a catalog.

Definition

[Visual Basic .NET]

Imports Microsoft.CommerceServer.Interop.Catalog
Import ADODB26Lib     ‘ for _Recordset
…
Public Function GuaranteedSpecificationSearch(pstrSearchHandle As Object,
  Optional eClassTypeRequired As Object,
  Optional lDesiredRecords As Object,
  Optional plTotalRecordsAvailable As Object,
  Optional pRSNewPropValuesList As Object,
  Optional vrPropertiesRequired As Object) As _Recordset

[C#]

using Microsoft.CommerceServer.Interop.Catalog;
using ADODB26Lib;                              //For _Recordset
…
public _Recordset GuaranteedSpecificationSearch(ref object pstrSearchHandle,
  object eClassTypeRequired,
  object lDesiredRecords,
  ref object plTotalRecordsAvailable,
  ref object pRSNewPropValuesList,
  object vrPropertiesRequired);

Parameters

[Visual Basic .NET]

  • pstrSearchHandle
    An Object that contains the specification search handle.
  • eClassTypeRequired
    An Object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.
  • lDesiredRecords
    An Object that contains the number of records desired.
  • plTotalRecordsAvailable
    An Object used to return the total records available.
  • pRSNewPropValuesList
    A Recordset used to return the new property values list.
  • vrPropertiesRequired
    An Object that contains the properties required in a comma-delimited String.

[C#]

  • pstrSearchHandle
    An object that contains the specification search handle.
  • eClassTypeRequired
    An object that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below. Set to Type.Missing in order to not specify a catalog class.
  • lDesiredRecords
    An object that contains the number of records desired. Set to Type.Missing to indicate all records.
  • plTotalRecordsAvailable
    An object used to return the total records available. Set an object to Type.Missing if the returned total is not needed.
  • pRSNewPropValuesList
    A Recordset used to return the new property values list. Set an object to Type.Missing if the returned Recordset is not needed.
  • vrPropertiesRequired
    An object that contains the properties required in a comma delimited String. Set to Type.Missing to not specify a list of properties.

Return Values

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

[C#] This method returns a Recordset containing the search 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 COMException may wrap as exceptions for this method.

Constant Value Description
E_POINTER

[C#] 0x80004003

[Visual Basic .NET] &H80004003

 The pointer is invalid.
E_CAT_INVALID_PARAMETER

[C#] 0x889800B6

[Visual Basic .NET] &H889800B6

 The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE

[C#] 0x8898010D

[Visual Basic .NET] &Hx8898010D

 The search handle that you specified is invalid. The search handle should be of the form [CatalogName][CategoryName] AND (Search Clause1) AND (SearchClause2) ....
E_INVALIDARG

[C#] 0x80070057

[Visual Basic .NET] &H80070057

 One or more arguments are invalid.
E_CAT_INVALID_RETURN_PROPS

[C#] 0x8898011D

[Visual Basic .NET] &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_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE

[C#] 0x88980049

[Visual Basic .NET] &H88980049

 The category you specified does not exist or is not marked as specification searchable.

Remarks

This method is similar to the PerformSpecificationSearch method. The optional output parameter, pRSNewPropValuesList, is a single-row Recordset. This Recordset contains one field for each searchable property for the products under the category specified in the BeginSpecificationSearch method. Each field contains a System.Array. The System.Array contains a set of distinct values for that property. The set is all the values in all the products that match the search clauses in the search handle. Only the properties that are marked as searchable are returned in the Recordset. A property can be marked as searchable by setting the IncludeInSpecSearch attribute of that property to true.

This method guarantees that results will be returned from a specification search of the catalog by removing search constraints in the reverse order that they were added until a match is found. Therefore, remember to add constraints to a specification search in order of decreasing importance.

The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. If the parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Ee784456.note(en-US,CS.20).gif Note

  • When field names begin with a number or contain spaces they must be enclosed in brackets. Data errors will occur if the field names are not formatted correctly. For example, "[123_Prop1],[123_ Prop2]". If the vrPropertiesRequired property is omitted then the data in all fields will be returned correctly.

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.

[Visual Basic .NET]

Example

'strSearchHandle contains a search handle returned 
'from AddSpecificationSearchClause or BeginSpecificationSearch
'The following parameters should be examined after the call returns.
'plTotalRecordsAvailable is a Long
'pRSNewPropValuesList is an empty recordset 
rsMySearchResults = myProductCatalog.GuaranteedSpecificationSearch('strSearchHandle , 20, plTotalRecordsAvailable, pRSNewPropValuesList)

Requirements

Namespace: Microsoft.CommerceServer.Interop.Catalog

Platforms: Windows 2000, Windows Server 2003

Assembly: cataloglib (in cataloglib.dll)

See Also

ProductCatalog3 Class

ProductCatalog3.AddSpecificationSearchClause

ProductCatalog3.PerformSpecificationSearch

ProductCatalog3.RemoveSpecificationSearchClause

Copyright © 2005 Microsoft Corporation.
All rights reserved.