IProductCatalog3::GuaranteedSpecificationSearch Method [C++]

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

Definition

[C++]

HRESULT IProductCatalog3::GuaranteedSpecificationSearch(VARIANT*pstrSearchHandle,
  VARIANTeClassTypeRequired,
  VARIANTlDesiredRecords,
  VARIANT*plTotalRecordsAvailable,
  VARIANT*pRSNewPropValuesList,
  VARIANTvrPropertiesRequired,
  _Recordset**ppRSSearchResults);

[Visual Basic]

Function GuaranteedSpecificationSearch(pstrSearchHandle As Variant,
  Optional eClassTypeRequired As Variant,
  Optional lDesiredRecords As Variant,
  Optional plTotalRecordsAvailable As Variant,
  Optional pRSNewPropValuesList As Variant,
  Optional vrPropertiesRequired As Variant) As _Recordset

Parameters

• pstrSearchHandle[C++]
  [in, out] A VARIANT that contains the specification search handle. The modified search handle will be returned by this parameter.
• pstrSearchHandle[Visual Basic]
  A Variant that contains the specification search handle.
• 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.
• lDesiredRecords[C++]
  [in, optional] A VARIANT that contains the number of records wanted.
• lDesiredRecords[Visual Basic]
  A Variant that contains the number of records wanted.
• plTotalRecordsAvailable[C++]
  [out, optional] A pointer to a VARIANT used to return the total records available.
• plTotalRecordsAvailable[Visual Basic]
  A Variant used to return the total records available.
• pRSNewPropValuesList[C++]
  [out, optional] A Recordset object used to return the new property values list.
• pRSNewPropValuesList[Visual Basic]
  A Recordset object used to return the new property values list.
• vrPropertiesRequired[C++]
  [in, optional] A VARIANT that contains the properties required in a comma-delimited String.
• vrPropertiesRequired[Visual Basic]
  A Variant that contains the properties required in a comma-delimited String.
• ppRSSearchResults[C++]
  [out, retval] 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 that contains the search results.

Error Values

[C++] This method returns S_OK (0x00000000) or S_FALSE (&H00000001) to indicate success and standard COM HRESULT error values, to indicate failure. This method may succeed and yet not return a valid output parameter. The output parameter(s) will be invalid if either and error value or S_FALSE is returned. 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) or S_FALSE (&H00000001) to indicate success and to either standard or custom COM error values to indicate failure. This method may succeed and yet return a property or object that is Nothing due to a syntax error, such as requesting a property or object that does not exist. Test the return value for Nothing before relying on it. For more information about standard COM errors, see Standard COM Errors.

In the context of this method, S_FALSE indicates:

• The pRSNewPropValuesList parameter is specified and there are no properties in the catalog that are marked for specification search.
• The pRSNewPropValuesList parameter is specified and there are no products under the category selected for specification search.

The following table shows the custom COM error that this method can return.

[C++] 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] 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 pstrSearchHandle, plTotalRecordsAvailable, pRSNewPropValuesList, and ppRSSearchResults parameters contain valid data only if the method was accessed successfully.

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 SAFEARRAY. The SAFEARRAY 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.

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

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

When field names begin with a number or contain spaces, they must be enclosed in brackets. Data errors occur if the field names are not formatted correctly. If the vrPropertiesRequired parameter is omitted, 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.

The CatalogClassTypeEnum enumeration values can be combined in the eClassTypeRequired parameter with logical ORs, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

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

[Visual Basic]

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 
SET rsMySearchResults = myProductCatalog.GuaranteedSpecificationSearch('strSearchHandle , 20, plTotalRecordsAvailable, pRSNewPropValuesList)

See Also

[C++]ProductCatalog Object

[Visual Basic]ProductCatalog Object

[C++]IProductCatalog3::AddSpecificationSearchClause

[Visual Basic]ProductCatalog.AddSpecificationSearchClause

[C++]IProductCatalog3::PerformSpecificationSearch

[Visual Basic]ProductCatalog.PerformSpecificationSearch

[C++]IProductCatalog3::RemoveSpecificationSearchClause

[Visual Basic]ProductCatalog.RemoveSpecificationSearchClause

Copyright © 2005 Microsoft Corporation.
All rights reserved.