Catalog Modeler |
Creating a Persistent QueryUsing CATICatalogPersistentQuery |
|
| Use Case | ||
AbstractThis use case illustrates how to create a persistent query. |
This use cases explains how to create a resolved persistent query. This functionality aims at storing in a permanent way a filtered view of a catalog.
Resolving the query is not a mandatory step. You do it in two cases:
It is important to notice, that it is recommended to associate only one persistent query to a chapter. To be exact, this chapter is a family (a end chapter).
Before getting to the use case itself, it is important to already be familiar with the basic notions of Catalog. See the referenced article [1] for a detailed overview.
[Top]
CAACciCatalogPersistentQuery is a use case of the CAAComponentsCatalogs.edu framework that illustrates ComponentsCatalogsInterfaces framework capabilities.
[Top]
The code of this use case is extracted from the code which creates the CAATool
catalog [Fig.1]. This catalog is detailed in the use case "Creating a
Catalog" [2].
|
|
This current use case explained the creation of the Nuts6SidesHole10Family
chapter and how a persistent query is associated to it.
The name of the chapter, Nuts6SidesHole10Family, gives an idea
of its desired contents: It is a chapter which will contain the six sides Nuts with a
central hole of 10mm diameter. The query will be done in the CAANuts6Sides
catalog [Fig 2]. This catalog is detailed in the use case "Creating a
Catalog With Part Family" [3].
|
In the next picture, you can see the named of the query, "QueryOn6Sides"
and its definition "(PartBody\Hole.1\Diameter==10mm)".
|
At last, the use case resolves the query, you can see that in the last column "Status". It means that the descriptions resulting of the query have been created:
|
This picture shows three things:
Nuts6SidesHole10Family) contains the keyword "Name". This
keyword is explicitly created on the
chapter. For each description the query values this keyword with the name of
the external descriptionThe interactive scenario to create a such persistent query is given in the "Creating a Catalog" use case [2]
[Top]
To launch CAACciCatalogPersistentQuery , you will need to set up the build time environment, then compile the CAACciCatalogCreate module along with its prerequisites, set up the run time environment, and then execute the use case [4].
mkrun -c CAACciCatalogCreate InputPath [OutputPath]
Where:
CAAComponentsCatalogs.edu/InputData
InstallRootDirectory/CAAComponentsCatalogs.edu/InputData
InstallRootDirectory\CAAComponentsCatalogs.edu\InputData where InstallRootDirectory is the directory where the CAA
CD-ROM is installed.
The use case creates three documents:
CAAScrew.catalog , explained in the "Creating a Catalog With Part
Documents"
article [5] CAANuts6Sides.catalog, explained in the "Creating a Catalog With Part
Family"
article [3] CAATools.catalog, explained here and in the "Creating a Catalog"
article [2] After its execution, you can launch CATIA and open the created catalogs or execute the CAACciCatalogNavigation use case [6] for each. This use case displays the contents of a catalog.
[Top]
The code of the CAACciCatalogPersistentQuery use case is extracted from the CAACciToolCatalogCreation.cpp file located in the CAACciCatalogCreate.m module of the CAAComponentsCatalogs.edu framework. This part of code uses a global function defined in the CAACciCatalogDocumentServices.cpp file located in the same module.
| Name of the source file | Function |
| CAACciToolCatalogCreation | Global function to create the CAATool.catalog document |
| CAACciCatalogDocumentServices | Global functions to factorize the code |
depending on operating system you find them :
Windows |
InstallRootDirectory\CAAComponentsCatalogs.edu\CAACciCatalogCreate.m\ |
Unix |
InstallRootDirectory/CAAComponentsCatalogs.edu/CAACciCatalogCreate.m/ |
where InstallRootDirectory is the directory where the CAA CD-ROM
is installed.
[Top]
There are nine logical steps in the CAACciCatalogPersistentQuery use case:
[
Top]
...
CATICatalogChapter * piNuts6SidesHole10Family = NULL ;
if ( SUCCEEDED(rc) )
{
CATUnicodeString ChapterName = "Nuts6SidesHole10Family" ;
CATBoolean IsEndChapter = TRUE ;
rc = pICatalogChapterFactory->CreateChapter(ChapterName,IsEndChapter,piNuts6SidesHole10Family);
...
}
...
if ( SUCCEEDED(rc) && (NULL !=piNuts6SidesHole10Family)
&& (NULL != piNutsWithFixedSizeHoleChapter) )
{
CATILinkableObject * pLinkOnFamily = NULL ;
rc = piNuts6SidesHole10Family->QueryInterface(IID_CATILinkableObject,
(void **) &pLinkOnFamily);
if ( SUCCEEDED(rc) )
{
CATICatalogDescription * piDescription = NULL ;
rc = piNutsWithFixedSizeHoleChapter->AddDescription(piDescription,pLinkOnFamily);
if (SUCCEEDED(rc) && (NULL != piDescription) )
{
piDescription->Release();
piDescription = NULL ;
}
pLinkOnFamily->Release();
pLinkOnFamily = NULL ;
}
}
...
|
The Nuts6SidesHole10Family chapter is
created thanks to the CATICatalogChapterFactory interface. pICatalogChapterFactory
is the CATICatalogChapterFactory interface pointer on the CAATool
root container. In the use case "Creating a Catalog" [2]
you have the detail about its recovery.
This chapter is a family, IsEndChapter the second argument of
the CreateChapter method is TRUE, because it will
contain descriptions referencing no chapters, but another descriptions.
The new chapter is linked with a parent chapter thanks a new description
created on its parent chapter. In this case the parent chapter is the NutsWithFixedSizeHole
chapter [Fig.1]. This chapter is handled by piNutsWithFixedSizeHoleChapter,
a CATICatalogChapter interface pointer. As pICatalogChapterFactory,
refer to the use case [2] to see its recovery.
Like any kind object to set in a description, the CATILinkableObject
interface on the Nuts6SidesHole10Family chapter, pLinkOnFamily, is
necessary. The AddDescription method applied to the NutsWithFixedSizeHole
chapter, the parent chapter pointed by piNutsWithFixedSizeHoleChapter, creates
a new description with the pLinkOnFamily interface
pointer on the Nuts6SidesHole10Family chapter.
...
CATUnicodeString KWName= "Name" ;
if ( SUCCEEDED(rc) && (NULL!= piNuts6SidesHole10Family) )
{
CATICatalogKeyword * piKeyword = NULL ;
CATUnicodeString TypeKW = "String" ;
rc = piNuts6SidesHole10Family->AddKeyword(KWName,TypeKW,piKeyword);
if ( SUCCEEDED(rc) )
{
piKeyword->Release();
piKeyword = NULL ;
}
}
...
|
The string "Name" keyword is created on the Nuts6SidesHole10Family
chapter. piNuts6SidesHole10Family is the CATICatalogChapter interface
pointer on the Nuts6SidesHole10Family chapter.
Often the keywords associated with the family with a persistent query are in
relationship with those of the filtered catalog (It is a sub-set of keywords).
But in opposite to the Name keyword, the family's keywords are not
valuated with values from the external descriptions. The valuation must be done
explicitly with the SetValue method as usual.
...
if ( SUCCEEDED(rc) && (NULL != piNuts6SidesHole10Family) )
{
CATUnicodeString QueryPersistentName ="QueryOn6Sides";
CATICatalogPersistentQuery * piPersistentQuery = NULL ;
rc = piNuts6SidesHole10Family->AddPersistentQuery(QueryPersistentName,piPersistentQuery);
...
|
The persistent query is created thanks to the AddPersistentQuery
method on the chapter. piNuts6SidesHole10Family is the CATICatalogChapter
interface pointer on the Nuts6SidesHole10Family chapter. The first
argument of this method is the name of the persistent query, QueryPersistentName,
and the second is the output pointer on the created query. This pointer must be
released as soon as it becomes useless, i.e. when all the informations (the
external chapter and the expression) to
resolve the query will be set on the persistent query. It is done in the next
steps.
...
if ( SUCCEEDED(rc) && ( NULL != piPersistentQuery) )
{
CATICatalogChapter * piChapter = NULL ;
CATUnicodeString ChapterName = "Nuts6Sides";
CATUnicodeString DocumentName ="CAANuts6Sides";
rc = ::CAAFindChapterInCatalog(DocumentName,iOutputPath,ChapterName,
IID_CATICatalogChapter, (void**) &piChapter);
...
|
The CAAFindChapterInCatalog
global function retrieves the Nuts6Sides chapter in the CAANuts6Sides
catalog. In the picture [Fig.2] describing this catalog,
you will note that the Nuts6Sides chapter is the root chapter. It
is necessary to set a root chapter for a persistent query.
Note: A root chapter can be retrieved thanks to
the GetRootChapter method of the CATICatalogChapterFactory
interface. Refer to the use case "Browsing a Catalog" [6]
for an example about this method.
...
if ( SUCCEEDED(rc) )
{
rc = piPersistentQuery->SetResolutionChapter(piChapter);
...
|
piPersistentQuery is the CATICatalogPersistentQuery
interface pointer created just above. piChapter is the CATICatalogChapter
on the external root chapter of the CAANuts6Sides catalog.
The last operation to complete the persistent query is to determine the expression.:
...
if ( SUCCEEDED(rc) )
{
CATUnicodeString KW = "\"PartBody\\Hole.1\\Diameter\"";
CATUnicodeString Expression ="(x." + KW + "==10mm)" ;
rc = piPersistentQuery->SetExpression(Expression) ;
...
|
...
if ( SUCCEEDED(rc) )
{
int ResolveMode = 1 ;
CATListValCATICatalogDescription_var * pListExternalDescription = NULL ;
rc = piPersistentQuery->ResolveQuery(ResolveMode,
pListExternalDescription);
...
|
The ResolveQuery method is applied on piPersistentQuery
the CATICatalogPersistentQuery interface pointer created just above. This
method retrieves the list of external descriptions, those of the CAANuts6Sides
catalog whose the value of theirs keywords satisfy to the expression. The first
argument of the method, ResolveMode, indicates if its a simulation
or not. In case of simulation, no descriptions are created on the chapter
concerned by the persistent query, here Nuts6SidesHole10Family,
only temporary descriptions are returned in the pListExternalDescription.
...
CATUnicodeString KWFirstLimit= "PartBody\\Pad.1\\FirstLimit\\Length" ;
CATUnicodeString KWDiameter= "PartBody\\Hole.1\\Diameter" ;
if ( SUCCEEDED(rc) && ( NULL != pListExternalDescription) )
{
int SizeList = pListExternalDescription->Size();
...
int i = 1 ;
while ( SUCCEEDED(rc) && (i <=SizeList) )
{
CATICatalogDescription_var spDesc = (*pListExternalDescription)[i] ;
if ( NULL_var != spDesc )
{
...
if ( SUCCEEDED(rc) )
{
...
CATUnicodeString KeywordValue ;
rc = spDesc->GetValue(KWFirstLimit,KeywordValue) ;
...
rc = spDesc->GetValue(KWDiameter,KeywordValue);
...
}
}else rc = E_FAIL ;
i++ ;
}
}
...
|
pListExternalDescription is a list of CATICatalogDescription
smart pointer previously obtain by the ResolveQuery method applied
on the persistent query. This list can be also obtain through the method GetListGeneratedDescriptions
on the same persistent query.
KWFirstLimit and KWDiameter are the keywords of the
Nuts6SidesFamily chapter, chapter whose the descriptions come from.
...
CATListValCATICatalogDescription_var * pListDescription = NULL;
rc = piNuts6SidesHole10Family->ListDescriptions (pListDescription) ;
if (SUCCEEDED(rc)|| (NULL != pListDescription) )
{
int NbDescriptions = pListDescription->Size() ;
int i=1 ;
while ( SUCCEEDED(rc) && ( i <= NbDescriptions) )
{
CATICatalogDescription_var spDesc = (*pListDescription)[i] ;
if ( NULL_var != spDesc )
{
CATUnicodeString KeywordValue;
...
rc = spDesc->GetString("Name", KeywordValue);
...
}else rc = E_FAIL ;
i++ ;
}
}
..
}
...
|
Since we have chosen the generation mode for the ResolveQuery
method and there are descriptions on the external chapter to satisfy the
expression, there is a list of description for the Nuts6SidesHole10Family
chapter. This chapter contains only one keyword,
the Name keyword. Its valuation for each description of the current
chapter is automatically done in using the name of its external description.
[Top]
This use case illustrates the creation of a persistent query on a chapter. Three main steps:
AddPersistentQuery
method which returns a CATICatalogPersistentQuery interface
pointer on the new query.ResolveQuery
method on the persistent query[Top]
| Version: 1 [Jul 2002] | Document created |
| [Top] | |
Copyright © 2002, Dassault Systèmes. All rights reserved.