IProductCatalog3::PerformSpecificationSearch Method [C++]

Article
11/12/2009

Use this method to perform a specification search of a catalog.

Definition

[C++]

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

[Visual Basic]

Function PerformSpecificationSearch(strSearchHandle As String,
  Optional eClassTypeRequired As Variant,
  Optional lDesiredRecords As Variant,
  Optional plTotalRecordsAvailable As Variant,
  Optional pRSNewPropValuesList As Variant,
  Optional vrPropertiesRequired As Variant) As _Recordset

Parameters

strSearchHandle[C++]
[in] A BSTR that contains the name of the search to perform.
strSearchHandle[Visual Basic]
A String that contains the name of the search to perform.
eClassTypeRequired[C++]
[in, optional] A VARIANT that contains the catalog class required. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
eClassTypeRequired[Visual Basic]
A Variant that contains the catalog class required. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section.
lDesiredRecords[C++]
[in, optional] A VARIANT that contains the records wanted.
lDesiredRecords[Visual Basic]
A Variant that contains the records wanted.
plTotalRecordsAvailable[C++]
[out, optional] A pointer to a VARIANT used to return the total number of records available.
plTotalRecordsAvailable[Visual Basic]
A Variant used to return the total number of records available.
pRSNewPropValuesList[C++]
[out, optional] A pointer to a VARIANT used to return the Recordset object of the new property values list.
pRSNewPropValuesList[Visual Basic]
A Variant used to return the Recordset object of 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 pointer to hold the reference to the returned Recordset object, which will contain 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.

Constant	Value	Description
E_POINTER	[C++] 0x80004003 [Visual Basic] &H80004003	The pointer is invalid.
E_CAT_INVALID_PARAMETER	[C++] 0x889800B6 [Visual Basic] &H889800B6	The input parameter <parameter number> is invalid.
E_CAT_INVALID_SPECSEARCH_HANDLE	[C++] 0x8898010D [Visual Basic] &H8898010D	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] &H80070057	One or more arguments are invalid
E_CAT_INVALID_RETURN_PROPS	[C++] 0x8898011D [Visual Basic] &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] &H88980049	The category you specified does not exists or is not marked as Specification searchable.

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

The PerformSpecificationSearch method runs a query using all of the constraints that have been added to the specified specification search handle.

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.

[C++] The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. It will always contain a CatalogName field. If the 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. It will always contain a CatalogName field. If the 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 will 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.

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

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