Catalog Modeler

What You Will Learn With This Use Case

Users often need a way of storing and classifying the many objects they have at their disposal, whether they be screws, ball bearings or computer parts. These objects may number tens of thousands, each with its own specific characteristics such as shape, color, size, diameter, length, etc. To facilitate fast and easy retrieval of such objects thus objects avoiding time-wasting redesign Version 5 offers the possibility of creating catalogs. 

A catalog is in the form of a tree structure made up of: 

• Chapters: a chapter references others chapters or families thanks descriptions. It is a way of classifying the elements it refers to 
• Families (end chapters):  a family is a set of components  
• Components: an object integrated into the catalog such as as feature (e.g. Power copy, User feature) or V5 documents (e.g. CATPart, CATProduct, etc) 
• Descriptions:

  a description links a chapter with 

  • an another chapter 
  • a component 

  and is described with keyword values

• Keywords: a keyword is an attribute describing the chapter and family content. Each description may be assigned its own attribute value. You can associate keywords to chapters and families and thus, perform searches by attribute value to filter their content.

The purpose of this use case is to create a catalog composed of: 

• Chapters (external and not external),  
• Families (external and not external), 
• Keywords with or without default value.

 For components, the following articles described them more in depth:

• "Creating a Catalog With Part Documents" [1]
• "Creating a Catalog With Part Family" [2] - A Part family is a family whose all the components are parts generated from configurations of design table.
• "Creating a Persistent Query" [3]

Before getting to the use case itself, it is important to already be familiar with the basic notions of Catalog. See the referenced article [4] for a detailed overview.

[Top]

The CAACciToolCatalogCreation Use Case

CAACciToolCatalogCreation is a use case of the CAAComponentsCatalogs.edu framework that illustrates ComponentsCatalogsInterfaces framework capabilities.

[Top]

What Does CAACciToolCatalogCreation Do

This use case creates the CAATool.catalog document [Fig.1]. The scenario of its creation is explained through images created in editing the catalog thanks to the Catalog Editor workbench. At last, the interactive scenario to obtain the same result, is given. 

The goal of this catalog is to create a classification of Part documents which contain the design of Screws and Nuts.

Fig.1 The CAATool.catalog Document

The Tools chapter is the root chapter. It contains two keywords [Fig.2]:

• ToolType visible keyword with no default value (Unset in the column Value)- This keyword will separate the chapters concerning the screws, the nuts and you can imagine other kind of tools.
• Suppliers an invisible keyword with "MySupplierA" as default value. This keyword is available for all the catalog and must not appear in the Catalog Browser, it is a private information, so it is set  invisible. 

Fig.2: The Tools's Keywords  

The Tools chapter contains three sub-chapters:

• Screws,  an external chapter
• Nuts
• NutsWithFixedSizeHole

The next picture [Fig 3] shows the three lines in the Reference tab page when the Tools chapter is current in the specification tree:

Fig.3: The Tools's Reference Tab Page

For each sub-chapter the "ToolType" keyword is valuated with the following values:

Fig.4: The Tools's Keyword Tab Page

The Screws chapter is an external chapter see the column Type [Fig 3]. In fact it is the root chapter of the CAAScrew catalog created in the use case CAACciScrewCatalogCreation and detailed in the "Creating a Catalog With Part Documents" article [1]

The Nuts chapter is not an external chapter, see the column Type [Fig 3], and contains the "SideNumber" keyword. This keyword is an integer without default value (Unset in the column Value). The goal of this keyword is to separate the nuts with their number of sides. 

Fig.5: The Nuts's Keywords

This Nuts chapter contains two sub-chapters: each a Part Family [2]

• Nuts6SidesFamily, an external family
• NutsSidesFamily, an internal family

The next picture [Fig 6] shows the two lines in the Reference tab page when the Nuts chapter is current in the specification tree:

Fig.6: The Nuts's Reference Tab Page

For each sub-chapter, a value for the "SideNumber" keyword is given:

Fig.7: The Nuts's  Keyword Tab Page

The Nuts6SidesFamily chapter is an external Part Family -see the column Type [Fig 6]. In fact it is a end chapter (Part family) of the CAANuts6Sides catalog created in the use case CAACciNuts6SidesCatalogCreation and explained in the "Creating a Catalog With Part Family" article [2]

The Nuts4SidesFamily chapter is a Part Family whose the Part document, with a design table, is CAANuts4Sides. Its construction is the same as the Nuts6SidesFamily Part family [2], so this article doesn't detail its creation. Nevertheless, the following picture [Fig.8] shows the descriptions for each configuration of its design table. In this same picture, notice that the Part configurations are not resolved: the value in the Type column is "Part family configuration" and not "Resolved part family configuration" and the value in the Object Name column is always CAANuts4Sides, the original Part.

Fig.8: The Nuts4SidesFamily's Reference Tab Page

The last chapter under the Tools chapter is NutsWithFixedSizeHole. This chapter contains only one chapter the Nuts6SidesHole10Family chapter [Fig 1]. This chapter is a end chapter (family) whose components will be defined by a persistent query inside the CAANuts6Sides catalog. Refer to the "Creating a Persistent Query" article [3] to have a complete explanation of this family.

The interactive scenario to obtain the same CAATool.catalog document is the following:

Launch CATIA. When the application is ready: 

• On the File menu click New
• In the File New  Dialog box select CatalogDocument  and click OK
• Select Chapter.1 in the specification tree 
• Contextual menu, select Chapter.1 object item and Definition item 
• In the dialog box, enter Tools in the Name field and click OK
• Launch the Add Keyword command
• In the  Keyword  Definition dialog box
  • enter ToolType in the Name field
  • select String in the Type selectot list
  • click OK
• Launch the Add Keyword command
• In the  Keyword  Definition dialog box
• enter Suppliers in the Name field
• select String in the Type selectot list
• unselect visibility 
• enter MySupplierA in the Default value field 
• click OK
• On the File menu click Open
• In the File Selection Dialog box select CAAScrew.catalog (*) and click Open
• Reselect the Tool catalog 
• Launch the Add link to other catalog command
• Select the Screws chapter in the specification tree in the CAAScrew catalog
• Select the Screws line in the Keyword tab Page
• In the Description Definition Tab Page 
  • Select the Keyword values tab page
  • select the ToolType line
  • enter Screws in the Value field
  • click OK
• Launch the Add chapter  command
• In the Chapter Definition Dialog box
  • enter Nuts in the Name field
  • click OK
• Select the Nuts line in the Keyword tab Page
• In the Description Definition Tab Page 
• Select the Keyword values tab page
• select the ToolType line
• enter Nuts in the Value field
• click OK
• Select Nuts  in the specification tree 
• Launch the Add Keyword command
• In the  Keyword  Definition dialog box
• enter SideNumber in the Name field
• select Integer in the Type selector list
• click OK
• On the File menu click Open
• In the File Selection Dialog box select CAANus6Sides.catalog (*) and click Open
• Reselect the Tool catalog 
• Launch the Add link to other catalog command
• select the Nuts6Sidesfamily chapter in the CAANus6Sides catalog
• Launch the Add Part Family command
• In the Part Family Definition dialog box
  • Enter Nuts4SidesFamily in the Name field
  • Push Select Document
  • in the File Selection dialog box retrieve the CAANuts4Sides.CATPart (*) file and click Open
  • click OK
• Select Tools in the specification tree 
• Launch the Add chapter  command
• In the Chapter Definition Dialog box
  • enter NutsWithFixedSizeHole in the Name field
  • click OK
• Select the NutsWithFixedSizeHole line in the Keyword tab Page
• In the Description Definition Tab Page 
• Select the Keyword values tab page
• select the Tooltype line
• enter NutsWithFixedSizeHole in the Value field
• click OK
• Select NutsWithFixedSizeHole in the specification tree
• In the Component Family Definition dialog box
  • Enter Nuts6SidesHole10Family in the Name field
  • click OK
• Select Nuts6SidesHole10Family in the specification tree
• Launch the Add Catalog resolved filter components command
• In the Resolved Filter Definition dialog box
  • enter QueryOn6Sides in the Name field
  • click the Browse button, and in the File Selection dialog box retrieve the CAANuts6Sides.CATPart (*) file and click Open
  • click the Filter Smart Definition button 
    • on the PartBody\Hole.1\Diameter line select == and enter 10mm 
    • click OK
  • click OK
• contextual menu, select Resolve Query

(*) The file are located in the directory CAAComponentsCatalogs.edu/InputData

• Unix : InstallRootDirectory/CAAComponentsCatalogs.edu/InputData
• Windows : InstallRootDirectory\CAAComponentsCatalogs.edu\InputData

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

[Top]

How to Launch CAACciCatalogToolsCreation

To launch CAACciToolCatalogCreation , 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 [5]. 

mkrun -c CAACciCatalogCreate InputPath [OutputPath]

Where:

1. InputPath : The path of files included in the directory CAAComponentsCatalogs.edu/InputData
   • Unix : InstallRootDirectory/CAAComponentsCatalogs.edu/InputData
   • Windows : InstallRootDirectory\CAAComponentsCatalogs.edu\InputData

   where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

2. OutputPath: The path to write the created catalogs. If this path is empty, the output files are created in the current directory.

The use case creates three documents:

• CAAScrew.catalog, explained in  the "Creating a Catalog With Part Documents" article [1] 
• CAANuts6Sides.catalog, explained in the "Creating a Catalog With Part Family" article [2] 
• CAATools.catalog,  explained in the current article

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]

Where to Find the CAACciToolCatalogCreation Code

The CAACciToolCatalogCreation use case is made of several source files located in the CAACciCatalogCreate.m module of the CAAComponentsCatalogs.edu framework:

depending on operating system you find them :

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

[Top]

Step-by-Step

There are nine logical steps in the CAACciToolCatalogCreation use case:

1. Creating a New Catalog Document
2. Creating the Root Chapter
3. Creating Keywords for the Root Chapter
4. Pointing an External Chapter
5. Creating a Chapter to Group Together the Part Family
6. Creating  Keyword for the New Chapter
7. Pointing an External Family
8. Creating a Chapter to Group Together Sub-Chapters with Persistent Query
9. Closing the New Catalog

Some operations like create a document, save a document, retrieve a chapter,..., have been factorized in global functions described in the "Global Functions" section.

[Top]

Creating a New Catalog Document

 ...
    CATDocument * pDocument = NULL ;
    CATICatalogChapterFactory * pICatalogChapterFactory = NULL ;

    rc = ::CAACreateCatalogDocument(&pDocument,&pICatalogChapterFactory);
 ...

The CAACreateCatalogDocument global function creates a "catalog" document and returns pICatalogChapterFactory the CATICatalogChapterFactory interface pointer on its root container. This interface is necessary to create chapters.

Creating the Root Chapter 

 ...
       CATICatalogChapter * piToolChapter = NULL ;

       CATUnicodeString ChapterName = "Tools" ;
       CATBoolean IsEndChapter = FALSE ;
       rc = pICatalogChapterFactory->CreateChapter(ChapterName,IsEndChapter,piToolChapter);
       ...
 ...

The Tools chapter is created thanks to the CreateChapter method of the CATICatalogChapterFactory interface. The second parameter, IsEndChapter, specifies that the chapter is a not a family. The returned pointer, piToolsChapter, must be released as soon as it will be useless.

The Tools chapter is the first chapter created in the document, so it is the root chapter. It means that you can retrieve it thanks to the GetRootChapter method of the same interface CATICatalogChapterFactory . 

Creating Keywords for the Root Chapter

Creation 

 ...
       if ( SUCCEEDED(rc) && (NULL != piToolChapter))
       {
          CATICatalogKeyword * piKeyword = NULL ;
          rc = piToolChapter->AddKeyword("ToolType","String",piKeyword);
          if ( SUCCEEDED(rc) )
          {
             piKeyword->Release();
             piKeyword = NULL ;
          }   
          if ( SUCCEEDED(rc) )
          {
             rc = piToolChapter->AddKeyword("Suppliers","String",piKeyword);
             if ( SUCCEEDED(rc) )
             {
                // Suppliers keyword will be invisible in the 
                // catalog browser
                piKeyword->SetHidden(TRUE);  
                piKeyword->Release();
                piKeyword = NULL ;
             }
          }
       }
 ...

The "ToolType" string keyword  is created thanks to the AddKeyword method of the CATICatalogChapter interface applied to piToolChapter the pointer on the Tools chapter. 

Same thing for the "Suppliers" keyword. Notice that this keyword is hidden from a Catalog Browser, in applying the SetHidden method on piKeyword the CATICatalogKeyword interface pointer of the keyword.

Default valuation

The default value for the "Suppliers" keyword is set thanks to the SetDefaultValue method of the CATICatalogChapter interface pointer on the Tools chapter, piToolChapter. 

 ...
       if ( SUCCEEDED(rc) && (NULL != piToolChapter))
       {
          CATUnicodeString Value = "MySupplierA" ;
          rc = piToolChapter->SetDefaultValue("Suppliers",Value);
       }
 ...

For the "ToolType" keyword there is not default value. On each description of the Tools chapter, a value will be set thanks to the SetValue method on a CATICatalogDescription interface pointer. Notice that if a keyword has a default value, its value can be nevertheless changed on each description. 

Pointing an External Chapter

 ...
       if ( SUCCEEDED(rc) && (NULL !=piToolChapter) )
       {
          CATILinkableObject * piLinkOnChapter = NULL ;
          CATUnicodeString ChapterName = "Screws";
          CATUnicodeString DocumentName = "CAAScrew" ;
          rc = ::CAAFindChapterInCatalog(DocumentName,iOutputPath,ChapterName,IID_CATILinkableObject,
                                              (void**)&piLinkOnChapter);

          if ( SUCCEEDED(rc) )
          {
             CATICatalogDescription * piDescription = NULL ;
             rc = piToolChapter->AddDescription(piDescription,piLinkOnChapter);
             if ( SUCCEEDED(rc) && ( NULL != piDescription) )
             {
                rc = piDescription->SetValue("ToolType","Screws");

                piDescription->Release();
                piDescription = NULL ;
             } 
             piLinkOnChapter->Release();
             piLinkOnChapter = NULL ;                    
           }
       }
 ...

The CAAFindChapterInCatalog global function retrieves inside the CAAScrew.catalog, the Screws chapter. The output of this function is, in this case, the CATILinkableObject interface pointer on this external chapter. This pointer is the input of the AddDescription method applied to piToolChapter , the CATICatalogChapter interface pointer of the Tools chapter. It means that the piToolChapter chapter has a new description which contains a link towards the external Screws chapter. 

At last, the value of the "ToolType" keyword is set to "Screws" on the new description, piDescription, the description dedicated to the Screws chapter.

Creating a Chapter to Group Together the Part Families

 ...
       if ( SUCCEEDED(rc) )
       {
          CATUnicodeString ChapterName = "Nuts" ;
          CATBoolean IsEndChapter = FALSE ;

          rc = pICatalogChapterFactory->CreateChapter(ChapterName,IsEndChapter,piNutsChapter);
          ...
       }

 ...

The Nuts chapter is created thanks to the CATICatalogChapterFactory interface. 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 Tools Chapter. 

 ...
       if (SUCCEEDED(rc) && (NULL != piNutsChapter) && (NULL != piToolChapter) )
       {                  
          CATILinkableObject * pLinkOnChapter = NULL ;
          rc = piNutsChapter->QueryInterface(IID_CATILinkableObject,
                                              (void **) &pLinkOnChapter);     
          if ( SUCCEEDED(rc) )
          {
             CATICatalogDescription * piDescription = NULL ;
             rc = piToolChapter->AddDescription(piDescription,pLinkOnChapter);
             if ( SUCCEEDED(rc) && (NULL != piDescription) )
             {
                rc = piDescription->SetValue("ToolType","Nuts");

                piDescription->Release();
                piDescription = NULL ;
             }

             pLinkOnChapter->Release();
             pLinkOnChapter = NULL ;
          }
       }
...

Like any kind object to set in a description, the CATILinkableObject interface on the Nuts chapter, pLinkOnChapter, is necessary.  The AddDescription method applied  to the Tools chapter, the parent chapter pointed by piToolChapter, creates a new description with the pLinkOnChapter interface pointer on the Nuts chapter.

At last, the value of the "ToolType" keyword is set to "Nuts" on the new description, piDescription, the description dedicated to the Nuts chapter.

Creating  Keyword for the New Chapter

 ...
       if ( SUCCEEDED(rc) && (NULL != piNutsChapter) )
       {                  
          CATICatalogKeyword * piKeyword = NULL ;
          rc = piNutsChapter->AddKeyword("SideNumber","Integer",piKeyword);
          if ( SUCCEEDED(rc) )
          {
             piKeyword->Release();
             piKeyword = NULL ;
          }
       }
...

The integer "SideNumber" keyword is created on the Nuts chapter. piNutsChapter is the CATICatalogChapter interface pointer on the Nuts chapter.

Pointing an External Family

 ...
        if ( SUCCEEDED(rc) && (NULL != piNutsChapter))
        {
           CATILinkableObject * piLinkOnChapter = NULL ;
           CATUnicodeString ChapterName = "Nuts6SidesFamily";
           CATUnicodeString DocumentName = "CAANuts6Sides";
           rc = ::CAAFindChapterInCatalog(DocumentName,iOutputPath,
                                       ChapterName,IID_CATILinkableObject, 
                                           (void**) &piLinkOnChapter);
        
           if ( SUCCEEDED(rc) )
           {
              CATICatalogDescription * piDescription = NULL ;
              rc = piNutsChapter->AddDescription(piDescription,piLinkOnChapter);
              if ( SUCCEEDED(rc) && (NULL != piDescription) )
              {
                 ...
                 rc = piDescription->SetValue("SideNumber","6");
                 piDescription->Release();
                 piDescription = NULL ;
              }

              piLinkOnChapter->Release();
              piLinkOnChapter = NULL ;
           }
        }
...

The CAAFindChapterInCatalog global function retrieves inside the CAANuts6Sides.catalog, the Nuts6SidesFamily chapter. The output of this function is, in this case, the CATILinkableObject interface pointer on this chapter. This pointer is the input of the AddDescription method applied to piNutsChapter , the CATICatalogChapter interface pointer on the Nuts chapter. It means that the piNutsChapter chapter has a new description which contains a links towards the external Nuts6SidesFamily chapter.

At last, the value of the "SideNumber" keyword is set to "6" on the new description, piDescription, the description dedicated to the Nuts6SidesFamily chapter. 

Creating a Chapter to Group Together Sub-Chapters with Persistent Query

 ...
       CATICatalogChapter * piNutsWithFixedSizeHoleChapter = NULL ;

       if ( SUCCEEDED(rc) )
       { 
          CATUnicodeString ChapterName = "NutsWithFixedSizeHole" ;
          CATBoolean IsEndChapter = FALSE ;
          rc = pICatalogChapterFactory->CreateChapter(ChapterName,IsEndChapter,piNutsWithFixedSizeHoleChapter);
          ...
       }
       if ( SUCCEEDED(rc) && ( NULL != piToolChapter) )
       {
          CATILinkableObject * pLinkOnChapter = NULL ;
          rc = piNutsWithFixedSizeHoleChapter->QueryInterface(IID_CATILinkableObject,
                                              (void **) &pLinkOnChapter);     
          if ( SUCCEEDED(rc) )
          {
             CATICatalogDescription * piDescription = NULL ;
             rc = piToolChapter->AddDescription(piDescription,pLinkOnChapter);
             if ( SUCCEEDED(rc) && (NULL != piDescription) )
             {  
                // 2-6-3 Associating a value to the ToolType keyword
                rc = piDescription->SetValue("ToolType","Nuts");

                piDescription->Release();
                piDescription = NULL ;
             }

             pLinkOnChapter->Release();
             pLinkOnChapter = NULL ;
          }
       }
...

The same code as for the Nuts chapter. The  NutsWithFixedSizeHole chapter is created thanks to the CATICatalogChapterFactory interface.  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 Tools Chapter. 

Like any kind object to set in a description, the CATILinkableObject interface on the NutsWithFixedSizeHole chapter, pLinkOnChapter, is necessary.  The AddDescription method applied  to the Tools chapter, the parent chapter pointed by piToolChapter, creates a new description with the pLinkOnChapter interface pointer on the NutsWithFixedSizeHole chapter.

At last, the value of the "ToolType" keyword is set to "Nuts" on the new description, piDescription, the description dedicated to the NutsWithFixedSizeHole chapter.

Closing the New Catalog

 ...
    if ( SUCCEEDED(rc) && (NULL != pDocument) )
    {
        CATUnicodeString DocumentName = "CAATool" ;
        rc = ::CAACloseCatalogDocument(DocumentName,*pDocument,iOutputPath);
        pDocument = NULL ;
    }
...

The CAACloseCatalogDocument global function saves the new catalog  under the name CAATool

Global Functions

In the CAACciCatalogServices.cpp you will find the global functions used in this use case, but also in the CAACciScrewCatalogCreation [1], the  CAACciNuts6SidesCatalogCreation [2] and the CAACciCatalogPersistentQuery [3] use cases.

• The necessary includes are:

// ObjectModelerBase Framework #include "CATDocumentServices.h" // Open/remove/new document #include "CATDocument.h" // to handle the CATDocument #include "CATInit.h" // To retrieve the root container // ObjectSpecsBase Framework #include "CATLISTV_CATISpecObject.h" // To retrieve the list of design table #include "CATIContainer.h" // for the root container of the document // ComponentsCatalogsInterfaces Framework #include "CATICatalogChapterFactory.h" #include "CATICatalogChapter.h" //MecModInterfaces Framework #include "CATIPrtContainer.h" // The Part root container //LiteralFeatures #include "CATIParmPublisher.h" #include "CATIDesignTable.h" // Standard C++ library #include <iostream.h> // System Framework #include "CATUnicodeString.h"

• CAACreateCatalogDocument

This method creates a new catalog document and retrieves  the CATICatalogChapterFactory interface implemented on the root container of the new document. 

HRESULT CAACreateCatalogDocument(CATDocument ** opDocument, CATICatalogChapterFactory ** opCatalogChapterFactory) { HRESULT rc = E_FAIL ; if ( NULL == opDocument ) return rc ; *opDocument = NULL ; if ( NULL == opCatalogChapterFactory ) return rc ; * opCatalogChapterFactory = NULL ; // 1- Creating a new document rc = CATDocumentServices::New("catalog",*opDocument); if ( SUCCEEDED(rc) ) { CATInit *pInitOnDoc = NULL ; rc = (*opDocument)->QueryInterface(IID_CATInit,(void **) &pInitOnDoc); if ( FAILED(rc) ) { cout << "Error in retrieving the CATInit interface"<< endl; }else { // 2- Retrieving the root container CATIContainer *pIRootCont = NULL ; pIRootCont = (CATIContainer*)pInitOnDoc->GetRootContainer("CATIContainer"); if ( NULL == pIRootCont ) { cout << "The root container is NULL"<< endl; rc = E_FAIL ; }else { // 3- Retrieving the CATICatalogChapterFactory pointer on the root container rc = pIRootCont->QueryInterface(IID_CATICatalogChapterFactory, (void **) opCatalogChapterFactory); if ( FAILED(rc) ) { cout << "Error in retrieving the CATICatalogChapterFactory interface"<< endl; } pIRootCont->Release(); pIRootCont = NULL ; } pInitOnDoc->Release(); pInitOnDoc = NULL ; } } return rc ; }

As usual, the document is created by the New static function of the CATDocumentServices class and a CATInit interface pointer is retrieved. Thanks to this interface, the root container is retrieved with the GetRootContainer method. The root container of a catalog document implements the CATICatalogChapterFactory interface to create chapters.

• CAACloseCatalogDocument

This method closes the document, handled by the iDocument pointed, and saves it under the name iDocumentName in the directory given by the last argument iOutputPath.

HRESULT CAACloseCatalogDocument(CATUnicodeString & iDocumentName, CATDocument & iDocument, CATUnicodeString & iOutputPath) { HRESULT rc = E_FAIL ; //1- Saving the document // ---------------------- CATUnicodeString DocumentSaveAsName = iDocumentName + ".catalog"; CATUnicodeString EmptyString ="" ; if ( EmptyString != iOutputPath ) { DocumentSaveAsName = iOutputPath + Slash + DocumentSaveAsName ; } rc = CATDocumentServices::SaveAs (iDocument,DocumentSaveAsName.CastToCharPtr()); if (FAILED(rc)) { cout << "Error in saving document "<< DocumentSaveAsName.CastToCharPtr() << endl; } //2- Removing the document from the session // ------------------------------------------ rc = CATDocumentServices::Remove(iDocument); if (FAILED(rc) ) { cout << "Error in closing document "<< DocumentSaveAsName.CastToCharPtr() << endl; } return rc ; }

The name of the catalog document is given by the caller. As usual, the SaveAs static function of the CATDocumentServices class is used to save the document in a directory.  

The second action consists in calling the Remove static function of the CATDocumentServices class. It results that the current catalog is closed and removed from the current session. The closure of a catalog implies that all documents pointed by this document are released (in fact unlocked). As usual, if the count of links on a pointed document becomes zero, the pointed document is also closed.

• CAAFindChapterInCatalog

This function enables to find a chapter by its name, ChapterName, in a given catalog, DocumentName, located in a given directory path, DocumentPath. 

HRESULT CAAFindChapterInCatalog(CATUnicodeString & iDocumentName, CATUnicodeString & iDocumentPath, CATUnicodeString & iChapterName, const IID & iInterfaceIdentifier, void ** opInterface) { HRESULT rc = E_FAIL ; if (NULL == opInterface) return rc ; *opInterface = NULL ; // 1-Building the storage name of the document // ------------------------------------------- CATDocument * pDocument = NULL ; CATUnicodeString EmptyString ="" ; CATUnicodeString ModelDocName = iDocumentName + ".catalog" ; if ( EmptyString != iDocumentPath ) { ModelDocName = iDocumentPath + Slash + ModelDocName ; } // 2-Opening the document // ---------------------- CATDocumentServices::Open(ModelDocName.CastToCharPtr(), pDocument); if ( NULL == pDocument ) { return rc ; } // 3-Retrieving the root container // -------------------------------- CATInit *pInitOnDoc = NULL ; rc = pDocument->QueryInterface(IID_CATInit,(void **) &pInitOnDoc); if ( FAILED(rc) ) { cout << "Error in retrieving the CATInit interface"<< endl; }else { CATIContainer *pIRootCont = NULL ; pIRootCont = (CATIContainer*)pInitOnDoc->GetRootContainer("CATIContainer"); if ( NULL == pIRootCont ) { cout << "The root container is NULL"<< endl; rc = E_FAIL ; }else { // 4-Retrieving its CATICatalogChapterFactory interface pointer // ----------------------------------------------------------- CATICatalogChapterFactory * pICatalogChapterFactory = NULL ; rc = pIRootCont->QueryInterface(IID_CATICatalogChapterFactory, (void **) &pICatalogChapterFactory); if ( FAILED(rc) ) { cout << "Error in retrieving the CATICatalogChapterFactory interface"<< endl; }else { // 5- Researching the chapter // --------------------------- CATICatalogChapter *pICatalogChapter = NULL ; rc = pICatalogChapterFactory->FindChapter(iChapterName,pICatalogChapter); if ( SUCCEEDED(rc) ) { rc = pICatalogChapter->QueryInterface(iInterfaceIdentifier, (void **) opInterface); pICatalogChapter->Release(); pICatalogChapter = NULL ; } pICatalogChapterFactory->Release() ; pICatalogChapterFactory = NULL ; } pIRootCont->Release(); pIRootCont = NULL ; } pInitOnDoc->Release(); pInitOnDoc = NULL ; } if ( (NULL != pDocument) && ( NULL == piInterface ) ) { rc = CATDocumentServices::Remove(pDocument); if (FAILED(rc) ) { cout << "Error in closing document "<< DocumentSaveAsName.CastToCharPtr() << endl; } } return rc ; }

To retrieve a chapter by its name into a catalog, the FindChapter method of the CATICatalogChapterFactory interface is used. Refer to the use case "Browsing a Catalog" [6] for details about this method. 

In this function the pDocument document is opened, two cases can append:

• The chapter is not found: the opened document must be closed here
• The chapter has been found: The returned chapter will be used for two reasons: 
  • to create an external chapter in the CAATool catalog
  • to associate a chapter  to a persistent query in the CAATool catalog  [3]

  In these two cases, the closure of the CAATool catalog will close the document pointed by pDocument. You can always use the CATLockDocument global function to keep a pointer on the document. When the pointer will be useless, you will call the opposite global function CATUnLockDocument. 

• CAARetrieveDTInPartDocument

This method enables to retrieve the first design table of a Part document given by its complete name iDocumentName. 

HRESULT CAARetrieveDTInPartDocument(CATUnicodeString & iDocumentName, CATIDesignTable ** opDesignTable) { HRESULT rc = E_FAIL ; if ( NULL == opDesignTable ) return rc ; *opDesignTable = NULL ; // 1- Opening the document CATDocument * pDocument = NULL ; rc = CATDocumentServices::Open(iDocumentName.CastToCharPtr(),pDocument); if ( SUCCEEDED(rc) ) { CATInit *pInitOnDoc = NULL ; rc = pDocument->QueryInterface(IID_CATInit,(void **) &pInitOnDoc); if ( FAILED(rc) ) { cout << "Error in retrieving the CATInit interface"<< endl; }else { // 2- Retrieving the root container CATIPrtContainer *pIPrtCont = NULL ; pIPrtCont = (CATIPrtContainer*)pInitOnDoc->GetRootContainer("CATIPrtContainer"); if ( NULL == pIPrtCont ) { cout << "The root container is NULL"<< endl; rc = E_FAIL ; }else { // 3- Retrieving the MechanicalPart feature CATISpecObject_var spSpecObjectPart = pIPrtCont->GetPart(); if ( NULL_var == spSpecObjectPart ) { cout << "The MechanicalPart is NULL"<< endl; rc = E_FAIL ; }else { // 4-Retrieving the list of design table CATIParmPublisher * pIParmPublisher = NULL ; rc = spSpecObjectPart->QueryInterface(IID_CATIParmPublisher,(void **) &pIParmPublisher); if ( SUCCEEDED(rc) ) { CATLISTV (CATISpecObject_var) DesignTableList ; pIParmPublisher->GetAllChildren("CATIDesignTable",DesignTableList); int NbDesignTable = DesignTableList.Size(); if ( NbDesignTable >= 1 ) { CATISpecObject_var specObj = DesignTableList[1] ; rc = specObj->QueryInterface(IID_CATIDesignTable,(void**) opDesignTable); } pIParmPublisher->Release(); pIParmPublisher = NULL ; } } pIPrtCont->Release(); pIPrtCont = NULL ; } pInitOnDoc->Release(); pInitOnDoc = NULL ; } } return rc ; }

The design table are retrieved thanks to the GetAllChildren method of the CATIParmPublisher. In this case, it is the MechanicalPart feature, those returned by the GetPart method on the root container, pIPrtCont, which implements this interface. 

The design table must contain a column named PartNumber . A test to control its presence should be added in this method. 

[Top]

In Short

This use case illustrates how to create a catalog document in using the following interfaces:

• CATICatalogChapterFactory, to create chapters
• CATICatalogChapter, to handle a chapter
  • Create keywords
  • Set default value to keywords
  • Create descriptions
• CATILinkableObject, to associate an chapter to a description
• CATICatalogKeyword, to handle a keyword
• CATICatalogDescription to handle the description
  • Set value the keyword 

[Top]

References

History

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