3D PLM Enterprise Architecture

User Interface - Frame

Search Overview

How to search objects in V5 documents
Technical Article

Abstract

This article shows how to search objects in a V5 document using the Search API.

Principles

The Edit/Search interactive command enables you to look for objects in the current V5 document. This command uses an API detailed in this article and which is located in the InteractiveInterfaces framework. It is significant to say that this API offers more possibilities than the command itself.

The aim is to look for elements inside a document that match a criterion or a combination of criteria. The process is as follows: a criterion and a scope of search (called the context) are defined and fed into the search engine.

For the criteria, detailed in the Criteria Definition section, two cases can be distinguished:

In fact there is a third category of criterion, the combination criterion. It enables to compose criteria through logical operations to create only one criterion to set as parameter of the search engine. 

The architecture of the API is based on the components [1]. A criterion is a component, the context is a component and a component will be created to launch a query. This is explained in the Mechanism Based on Components and Interfaces section.

At the end of this article, there is a section about the Knowledge. The Workbench, Package, Type and Attribute section defines briefly the notions of workbenches, package, type and attribute, and details how to retrieve these objects.

To be complete, it should be specified that there is a use case entitled "Creating Search Queries"  [2]. Through some examples, it shows how to create and launch queries, and it gives you some tips not detailed here.

Criterion  Definition

In this section, all the criteria will be described. In fact, the following questions will be answered each time:

General Criteria

This picture shows the General tag page of the Search command.

Fig.1: The General Tab Page

The criteria are:

The other criteria imply only objects implementing the CATIVisProperties interface [3].

Advanced Criteria

This second picture shows the Advanced tab page of the Search command.

Fig.2: The Advanced Tab Page

The queries available in advanced mode are based on the knowledge infrastructure. An advanced criterion is a logical combination between a type based criterion and eventually an attribute based criterion whose attribute is linked to the designed type. The Package, Type and Attribute section gives you more details about knowledge parameters. 

The Type Criterion

This criterion enables you to carry out a search based on a knowledge type (CATIType). The comparison operator between the value of the criterion and those associated with objects can only be a difference on an equality. 

The Attribute Criteria

These criteria are based on the knowledge attribute. They are the following: 

This criterion has to be used to look for objects that have a user-defined type attribute. The authorized comparison operators sign values depend on the attribute's type (boolean, dimensioned, integer, listing, real or string).

Combination Criteria

A query is composed of one criterion and one context. But a criterion can be a combination of elementary criteria. There are three kind of combination:

These three logical combinations are consequently a criterion. This criterion has two criteria as parameters for the logical operation. 

About the criteria order

If the And and Or logical operations are commutative operations, the order for the parameter is important:

[Top]

Query Definition

A search query enables you to look for objects in a V5 document. Several aspects of a query are explained here under.

Context

A query is composed of a criterion and a context. The context defines the limits to look for objects.This is important: useful to decrease the research time and to define the scope of the research.The search into the document is based on the specification tree representation. There exist six types of scope:

NLS versus Transformat Format

In an interactive session you can create queries through the dialog objects (such as combo boxes) of the Search command. But in the Advanced tab page, see Fig.2, you can also enter a string to formulate a criterion. Imagine you enter the "Couleur='Base 25' & Trait=plein" text as follows:

If you are in a French session, this query will be successfully analyzed and processed. But the same query in a none English session is not valid. This is why it is important to use the transformat format, a session language independent format. If you now enter the following text, Color='(255,0,0)' & dashed=1), the query will be valid whatever the language session.

To interactively translate a query from the NLS format to the transformat format, you record a macro command on a Search command based scenario with the appropriate query.

  1. On the Tools Menu, select Macro and Start Recording
  2. Click Start in the Record Macro dialog box.
  3. On the Edit Menu, click Search
  4. Create interactively the query
  5. Click Search
  6. On the Tools Menu, select Macro and Stop Recording
  7. On the Tools Menu, select Macro and Macros
  8. Edit the macro

Here is the macro file:

Language="VBSCRIPT"

Sub CATMain()

Set partDocument1 = CATIA.ActiveDocument

Set selection1 = partDocument1.Selection

selection1.Search "(Color='(255,0,0)' & Dashed=1),all"

End Sub

where :

This macro file gives you also the internal name for knowledge types and attributes. These pieces of information are mandatory to create any advanced criterion.

Here is an example of scenario:

  1. On the Tools Menu, select Macro and Start Recording
  2. Click Start in the Record Macro dialog box
  3. On the Edit Menu, click Search
  4. Choose the Advanced tab page
  5. Select Generative Shape Design in the Workbench combo
  6. Select Scaling in the Type combo
  7. Select IsDatum in the Attribute combo
  8. Enter a value for the attribute
  9. Click Search
  10. On the Tools Menu, select Macro and Stop Recording
  11. Edit the macro
Language="VBSCRIPT"

Sub CATMain()

Dim partDocument1 As Document
Set partDocument1 = CATIA.ActiveDocument

Dim selection1 As Selection
Set selection1 = partDocument1.Selection

selection1.Search "CATGmoSearch.GSMScaling.NameInGraph=CAAName,all"

End Sub

Where :

Create a Query from a String

From a string (NLS or Transformat) it is possible to (re-)create a query. Thus you can store  queries in a setting file using the transformat format and then fully reuse this information in an other session whatever the language used.

[Top]

Mechanism Based on Components and Interfaces

Criteria, context and search engine are components [1]. A component is identifiable through a CLSID and instantiable thanks to the CATCreateInstance global function [5].

...
   #include "CATIniSearchEngineComponent.h"
   ...
   CATIIniSearchEngine* pISearchEngine=NULL;
   HRESULT rc = ::CATCreateInstance(CLSID_CATIniSearchEngineComponent, NULL, 0, 
                                     IID_CATIIniSearchEngine,
                                     (void**)&pISearchEngine);
...

The CATIniSearchEngineComponent header file contains the definition of the CLSID associated with the Search Engine component. This CLSID is CLSID_CATIniSearchEngineComponent. 

For each object of the Search mechanism, the CLSID of the component and its specific interface will be given in the following array. All the useful CLSID and interfaces are located in the InteractiveInterfaces framework

Criteria

At first the General criteria:

General Criterion Component CLSID Dedicated Interface
Color CLSID_CATIniSearchColorCriterion CATIIniSearchColorCriterion
Name CLSID_CATIniSearchNameCriterion CATIIniSearchNameCriterion
GraphName CLSID_CATIniSearchGraphNameCriterion CATIIniSearchGraphNameCriterion
Line type CLSID_CATIniSearchDashedCriterion CATIIniSearchDashedCriterion
Line thickness CLSID_CATIniSearchWeightCriterion CATIIniSearchWeightCriterion
Layer CLSID_CATIniSearchLayerCriterion CATIIniSearchLayerCriterion
Visibility CLSID_CATIniSearchVisibilityCriterion CATIIniSearchVisibilityCriterion
V4 Model CLSID_CATIniSearchV4ModelCriterion CATIIniSearchV4ModelCriterion

Then, the advanced criteria. 

Advanced Criterion Component CLSID Dedicated Interface
Boolean CLSID_CATIniSearchBooleanCriterion CATIIniSearchBooleanCriterion
Integer CLSID_CATIniSearchIntegerCriterion CATIIniSearchIntegerCriterion
Real CLSID_CATIniSearchRealCriterion CATIIniSearchRealCriterion
Listing CLSID_CATIniSearchListingCriterion CATIIniSearchListingCriterion
Dimension CLSID_CATIniSearchDimensionCriterion CATIIniSearchDimensionCriterion
String CLSID_CATIniSearchStringCriterion CATIIniSearchStringCriterion
User  CLSID_CATIniSearchUserCriterion CATIIniSearchUserCriterion
Type CLSID_CATIniSearchTypeCriterion CATIIniSearchTypeCriterion

Finally, the combination criteria.

Combination Criterion Component CLSID Dedicated Interface
And CLSID_CATIniSearchAndCriterion CATIIniSearchAndCriterion
Or CLSID_CATIniSearchOrCriterion CATIIniSearchOrCriterion
Except CLSID_CATIniSearchExceptCriterion CATIIniSearchExceptCriterion

Interfaces Architecture

In this diagram you can note that:

Context And Search Engine and Services

The last three components are the following:

Type Componant CLSID Dedicated Interface
Context CLSID_CATIniSearchContext CATIIniSearchContext
Search Engine CLSID_CATIniSearchSearchEngine CATIIniSearchEngine
Services CLSID_CATIniSearchServices CATIIniSearchServices
 

Workbench, Package, Type and Attribute

In the advanced queries, you should be familiar with some knowledge  objects: workbench, packages, type and attribute. To sum up a workbench is a group of packages, which is itself a group of types, and a type is a group of attributes. The section begins to explain the package notion, and ends by explanation about workbench. 

A package defines a set of types. All the types are "stored" in a dictionary. To retrieve a smart pointer on the unique type dictionary, you can use the static GetTypeDictionary method of the CATGlobalFunction class.

...
   CATITypeDictionary_var pITypeDictionary;
   pITypeDictionary = CATGlobalFunctions::GetTypeDictionary();
...

A type is handled through a CATIType interface. To retrieve a pointer on a type, you can use the FindTypeInPackage method on the CATITypeDictionary interface pointer.

...
  CATIType_var spITypeToFind;
  CATUnicodeString InternalTypeName ="Hole";
  CATUnicodeString PackageName = "PartDesign" ;
  
  rc = pITypeDictionary ->FindTypeInPackage(InternalTypeName,
                                            PackageName ,
                                            spITypeToFind);
...

The first two arguments of this method respectively are the internal name of a type and its package . The following scenario gives you the means to know the list of packages and for each of them the list of types and their associated attributes. 

  1. On the Tools Menu, click Options
  2. Select the Language tab page of General/Parameters and Measure
  3. Select all the packages or only the necessary
  4. On the Start Menu, click Knowledge Expert
  5. Launch Expert Check 
  6. Click Ok in the dialog box
  7. In the Check Editor dialog box click

The following dialog box appears:

The first column displays the list of packages, the second column displays the type contained by the selected package, and the last column displays the list of attributes for the selected type. All the names are internal name, in other words language independent. 

Internal name versus NLS name

A workbench, knowledge sense, groups together packages. It is without relationship with the workbench of a V5 document [4]. 

The workbench is only used for the Search Mechanism. The following picture shows some of them in the Search command.

In the Search command, you must choose a workbench to launch a query. The workbench enables us to provide a limited list of types (second combo). The first combo could have been a package name, but the notion of package is too short. A workbench groups together a "logical" set of types.

The workbench entity is optional for the Search API. To create a type criterion, only a CATIType interface pointer is mandatory. Lets us see the SetParameters method of the CATIIniSearchTypeCriterion interface.

...
  virtual HRESULT SetParameters (const CATIType* iSearchedType, 
                                 CATIniSearchEnumeration::Comparison iOperatingSign,
                                 CATUnicodeString iWorkbenchInternalName="") = 0;                                                                                                              
...

iWorkbenchInternalName is optional, you can set an empty string. Specifying the name of the workbench can be useful if you want display the query and inform your end users that the type provide from such or such workbench.

iWorkbenchInternalName is an internal name, it is not the NLS name displayed by the Search command. To retrieve the internal name from the NLS name, follow the scenario which uses a VB macro.

In Short

This article give you an overview of the Search API. It describes :

[Top]

References

[1] Using Components
[2] Creating Search Queries
[3] Graphical Properties
[4] Application Frame Overview
[5] Instantiating a Component Using its CLSID
[Top]

History

Version: 1 [May 2003] Document created
[Top]

Copyright © 2003, Dassault Systèmes. All rights reserved.