InteractiveInterfaces Interface CATIIniSearchServices

Usage: an implementation of this interface is supplied and you must use it as is. You should not reimplement it.

interface CATIIniSearchServices

Class providing general services for analysing a query (string format of a criterion).
Role: This class offers different services to generate a criterion from a query.
A query is a string format of a criterion. There exist two kinds of queries:

  • NLS queries are dependant on the session's language
    • ,
  • TransFormat queries are independant on this parameters.


    • NLS queries are useful in a user interface, whether TransFormat queries are useful for a stable and language independant view. TransFormat queries can be used in .CATSettings files, in a code definition of a query for instance.

    Method Index


    o ConvertFromNLSToTransFormat(CATUnicodeString&,CATUnicodeString&)
    Converts an NLS query into a Transformat query.
    o ConvertFromTransFormatToNLS(CATUnicodeString&,CATUnicodeString&)
    Converts a TransFormat query into an NLS query.
    o CorrectString(CATUnicodeString&,CATUnicodeString&)
    Corrects a string before feeding it into a query.
    o DecodeStringToCriterion(CATUnicodeString&,CATBoolean,CATIIniSearchCriterion*&)
    Decodes a query into a criterion.
    o GetQueryAndContextFromString(CATUnicodeString&,CATUnicodeString&,CATIIniSearchContext*&,CATBoolean)
    Decomposes a complete query (i.
    o GetWildCardCharacter(CATUnicodeChar&)
    Retrieves the wild characters.
    o TestNumValidity(CATUnicodeString&,CATBoolean)
    Tests the validity of a string as a digital value.
    o TestNumValidity(CATUnicodeString&,CATBoolean,CATUnicodeString&,CATUnicodeString&)
    Tests the validity of a string as a digital value with a unit.

    Methods


    o ConvertFromNLSToTransFormat
    public virtual ConvertFromNLSToTransFormat( const iNLSQuery,
    oTransformatQuery)
    Converts an NLS query into a Transformat query.
    Role: This service enables you to convert an NLS query into a Transformat query without tinkering with a CATIIniSearchCriterion pointer.
    Parameters:
    iNLSQuery
    The NLS query
    oTransformatQuery
    The equivalent Transformat query
    Returns:
    • S_OK if iNLSQuery corresponds to a correct query.
    • E_FAIL otherwise.
    o ConvertFromTransFormatToNLS
    public virtual ConvertFromTransFormatToNLS( const iTransformatQuery,
    oNLSQuery)
    Converts a TransFormat query into an NLS query.
    Role: This service enables you to convert a TransFormat query into an NLS query without tinkering with a CATIIniSearchCriterion pointer.
    Parameters:
    iTransFormatQuery
    The TransFormat query
    oNLSQuery
    The equivalent NLS query
    Returns:
    • S_OK if iTransFormatQuery corresponds to a correct query
    • E_FAIL otherwise
    o CorrectString
    public virtual CorrectString( const iStringToCorrect,
    oCorrectedString)
    Corrects a string before feeding it into a query.
    Role: Sometimes input strings can contain symbols that could be analyzed as special caracters in a Search query. It is then necessary to enclose those symbols within special exclusive caracters, so that they could be recognized.

    Let us consider the following query string: Name=little, johnny
    The GetQueryAndContextFromString method would return E_FAIL, for the string would be decomposed as Name=little, and an unknown context johnny would have been found.
    The solution is to call this method so that the little, johnny string is corrected into a String1 CATUnicodeString instance, which in turned could be correctly analyzed.

    Let us consider the following query string: NAME=Lonely*
    This looks for every object whose name starts with Lonely (case sensitivity respected). But what if we are looking for every object named Lonely* (star being part of the name) ?
    The Lonely* string should be fed into the CorrectString method, and the returned CATUnicodeString instance could be then correctly used.

    Parameters:
    iStringToCorrect
    The string to be corrected.
    oCorrectedString
    The string once corrected.
    Returns:
    S_OK always
    o DecodeStringToCriterion
    public virtual DecodeStringToCriterion( const iQueryString,
    iDisplayMessage,
    oCriterion)
    Decodes a query into a criterion.
    Role: This service enables the conversion of a query without context into a Search criterion. In addition, there is the possibility to display a pop-up window on the screen in case the query is incorrect: the message would indicate where the errors lay.

    Example:
    Let us consider the following NLS query: Name=*1.
    This service would decompose it as a CATIIniSearchNameCriterion pointer, and return S_OK.

    Let us consider the following TransFormat query: CATPrtSearch.Pad.
    This service would decompose it as a CATIIniSearchTypeCriterion pointer, and return S_OK.

    Let us consider the following incorrect NLS query: NameWithTypo=*1.
    It is impossible to decompose this query. Hence, a pop-up window would show up (if iDisplayMessage==TRUE), and E_FAIL would be returned.
    Parameters:
    iQueryString
    The NLS or TransFormat query corresponding to the criterion.
    iDisplayMessage
    A CATBoolean to indicate if a pop-up window should be displayed in case the query is incorrect.
    oCriterion
    The Search criterion generated from the NLS or TransFormat query.
    Returns:
    • S_OK if the conversion is successful.
    • E_FAIL otherwise. The pointer to CATIIniSearchCriterion is then NULL.
    o GetQueryAndContextFromString
    public virtual GetQueryAndContextFromString( const iCompleteQuery,
    oQuery,
    oContext,
    iTransFormat)
    Decomposes a complete query (i.e. a query and the string-format context) into a query and a context.
    Role: This service enables the decomposition of an NLS or TransFormat complete query string (i.e. a string containing both the query and the context), into an NLS or TransFormat query (which will be used to generate a criterion) and a context.
    The validity of the query part of the complete string is not analyzed.

    Example:
    Let us consider the following complete complete query: Name=*1,all.
    This service would decompose it as a query Name=*1, and a CATIIniSearchContext pointer. S_OK is returned.

    Let us consider the following complete query: CATPrtSearch.Pad,in.
    This service would decompose it as a query CATPrtSearch.Pad, and a CATIIniSearchContext pointer. S_OK is returned.

    Let us consider the following incorrect complete query: NameWithTypo=*1.
    This service would decompose it as a query NameWithTypo=*1 and a CATIIniSearchContext pointer. S_OK is returned.
    When nothing is specified at the end of the string, the default context is taken into account (refer to InUIActiveObject in ).

    Parameters:
    iCompleteQuery
    The complete NLS or TransFormat query to be decomposed.
    oQuery
    The corresponding NLS or TransFormat query, that can be fed into the
    method to generate a criterion.
    oContext
    The corresponding context.
    iTransFormat
    A CATBoolean to specify if the query is a TransFormat query.
    • TRUE, if the query is a TransFormat query.
    • FALSE, if the query is an NLS query.
    Returns:
    • S_OK, if the complete query has successfully been decomposed into a query and a context part.
    • E_FAIL, if the context (when found) is incorrect.
    o GetWildCardCharacter
    public virtual GetWildCardCharacter( oWildCardChar)
    Retrieves the wild characters.
    Role: This service enables you to retrieve the wild card character used to replace from 0 to n characters.
    Parameters:
    oWildCardChar
    The wild card character.
    Returns:
    • S_OK on success.
    • E_FAIL otherwise.
    o TestNumValidity
    public virtual TestNumValidity( const iValue,
    iWithDecimal)
    Tests the validity of a string as a digital value.
    Role: This service checks if an input string is a valid digital value.

    Parameters:
    iValue
    a CATUnicodeString format of a possible digital value (1.2 for instance).
    iWithDecimal
    TRUE if the string can contain a decimal symbol. FALSE if the string must not contain any decimal symbol.
    Returns:
    • S_OK if the CATUnicodeString is a valid digital value. E_FAIL if the CATUnicodeString is not a valid digital value (for instance 1.2.3)
    o TestNumValidity
    public virtual TestNumValidity( const iValueUnit,
    iWithDecimal,
    oValue,
    oUnit)
    Tests the validity of a string as a digital value with a unit.
    Role: This service checks if an input string is a valid digital value with a unit.

    Parameters:
    iValueUnit
    a CATUnicodeString format of a possible digital value with unit (1.2kg for instance)
    iWithDecimal
    TRUE if the digital value can contain a decimal symbol. FALSE if the digital value must not contain any decimal symbol.
    oValue
    The digital value as a CATUnicodeString. Then use the appropriate
    method to convert it into the desired format.
    A CATUnicodeString containing 1.2 is returned in our example.
    oUnit
    The unit found in the input string.
    A CATUnicodeString containing kg is returned in our example.
    Returns:
    • S_OK if the CATUnicodeString is a valid digital value.
    • S_FALSE if no unit has been found.
    • E_FAIL if the CATUnicodeString is not a valid digital value (for instance 1.2.3)
    This object is included in the file: CATIIniSearchServices.h
    If needed, your Imakefile.mk should include the module: CATInteractiveInterfaces

    Copyright © 1999-2014, Dassault Systèmes. All rights reserved.