Catalog Modeler

Browsing a Catalog

Understanding the internal catalog structure
Use Case

Abstract

This use case enables to understand the catalog document structure in displaying its contents. 

What You Will Learn With This Use Case

In reading the "What You Will learn With this Use case" section of the use case "Creating a Catalog" [1], you learn that a catalog is in the form of a tree structure made up of chapters, families (end chapters), components, descriptions and keywords. This use case is browsing a catalog to retrieve and display all the catalog is made off. 

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

[Top]

The CAACciCatalogVisualize Use Case

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

[Top]

What Does CAACciCatalogVisualize Do

The CAACciCatalogVisualize use case dumps a catalog. It means that it displays:

The output format (right shift at each sub-chapter) enables to understand the tree structure of the chapters. 

Here an illustration with the CAATool.catalog created in the use case CAACciCatalogToolCreation [1]. 

Fig.1: The Chapters list  
The CAACciCatalogVisualize main program begins ....

   The E:\users\egd\adele\egdmm10\CAAComponentsCatalogs.edu\InputData\CAATool.catalog is opened

   The catalog contains 5 chapter(s)
      Tools
      Nuts
      Nuts4SidesFamily
      NutsWithFixedSizeHole
      Nuts6SidesHole10Family
...
Fig.2: The Catalog Dump  
...
---Tools (Chapter)
      Keyword(s): 2
         ToolType; Default value= Unset
         Suppliers(*); Default value= Unset
      Description's name= Tools.2
         Chapter's keyword value 
            ToolType= Screws
            Suppliers= MySupplierA
---------Screws (External Chapter)
            Keyword(s): 1
               ToolType; Default value= Screw
            Description's name= Screws.2
               Chapter's keyword value 
                  ToolType= Screw
---------------ScrewsFamily (Family)
                  Keyword(s): 1
                     Material; Default value= Iron
                  Description's name= ScrewsFamily.2
                     Chapter's keyword value 
                        Material= Iron
                     Referenced Object's Type= Document
                     Referenced Object's Name= CAAScrew.CATPart
                     Part configuration
                  Description's name= ScrewsFamily.3
                     Chapter's keyword value 
                        Material= Iron
                     Referenced Object's Type= Document
                     Referenced Object's Name= CAAGroovedScrew.CATPart
                     Part configuration
      Description's name= Tools.3
         Chapter's keyword value 
            ToolType= Nuts
            Suppliers= MySupplierA
---------Nuts (Chapter)
            Keyword(s): 1
               SideNumber; Default value= Unset
            Description's name= Nuts.2
               Chapter's keyword value 
                  SideNumber= 6
---------------Nuts6SidesFamily (External Family)
                  Keyword(s): 3
                     PartNumber; Default value= Unset
                     PartBody\Pad.1\FirstLimit\Length; Default value= Unset
                     PartBody\Hole.1\Diameter; Default value= Unset
                  Description's name= Nut20x20
                     Chapter's keyword value 
                        PartNumber= Nut20x20
                        PartBody\Pad.1\FirstLimit\Length= 0.02 Meter
                        PartBody\Hole.1\Diameter= 0.02 Meter
                     Referenced Object's Type= Document
                     Referenced Object's Name= Nut20x20.CATPart
                     Resolved Part configuration
                  Description's name= Nut30x10
                     Chapter's keyword value 
                        PartNumber= Nut30x10
                        PartBody\Pad.1\FirstLimit\Length= 0.03 Meter
                        PartBody\Hole.1\Diameter= 0.01 Meter
                     Referenced Object's Type= Document
                     Referenced Object's Name= Nut30x10.CATPart
                     Resolved Part configuration
                  Description's name= Nut40x10
                     Chapter's keyword value 
                        PartNumber= Nut40x10
                        PartBody\Pad.1\FirstLimit\Length= 0.04 Meter
                        PartBody\Hole.1\Diameter= 0.01 Meter
                     Referenced Object's Type= Document
                     Referenced Object's Name= Nut40x10.CATPart
                     Resolved Part configuration
            Description's name= Nuts.3
               Chapter's keyword value 
                  SideNumber= 4
---------------Nuts4SidesFamily (Family)
                  Keyword(s): 3
                     PartNumber; Default value= Unset
                     PartBody\Pad.1\FirstLimit\Length; Default value= Unset
                     PartBody\Hole.1\Diameter; Default value= Unset
                  Description's name= Nut20x20
                     Chapter's keyword value 
                        PartNumber= Nut20x20
                        PartBody\Pad.1\FirstLimit\Length= 0.02 Meter
                        PartBody\Hole.1\Diameter= 0.02 Meter
                     Referenced Object's Type= Document
                     Referenced Object's Name= CAANuts4Sides.CATPart
                     Part configuration
                  Description's name= Nut20x10
                     Chapter's keyword value 
                        PartNumber= Nut20x10
                        PartBody\Pad.1\FirstLimit\Length= 0.02 Meter
                        PartBody\Hole.1\Diameter= 0.01 Meter
                     Referenced Object's Type= Document
                     Referenced Object's Name= CAANuts4Sides.CATPart
                     Part configuration
                  Description's name= Nut20x5
                     Chapter's keyword value 
                        PartNumber= Nut20x5
                        PartBody\Pad.1\FirstLimit\Length= 0.02 Meter
                        PartBody\Hole.1\Diameter= 0.005 Meter
                     Referenced Object's Type= Document
                     Referenced Object's Name= CAANuts4Sides.CATPart
                     Part configuration
      Description's name= Tools.4
         Chapter's keyword value 
            ToolType= Nuts
            Suppliers= MySupplierA
---------NutsWithFixedSizeHole (Chapter)

            Description's name= NutsWithFixedSizeHole.2
               Chapter's keyword value 
---------------Nuts6SidesHole10Family (Family)
                  Keyword(s): 1
                     Name; Default value= Unset
                  Nb Pesistent Query=1
                  Description's name= Nut30x10
                     Chapter's keyword value 
                        Name= Nut30x10
                     Referenced Object's Type= Description
                     Referenced Object's Name= Nut30x10
                     Name of its external chapter:Nuts6SidesFamily
                  Description's name= Nut40x10
                     Chapter's keyword value 
                        Name= Nut40x10
                     Referenced Object's Type= Description
                     Referenced Object's Name= Nut40x10
                     Name of its external chapter:Nuts6SidesFamily


The CAACciCatalogVisualize main program is ended.

[Top]

How to Launch CAACciCatalogVisualize

To launch CAACciCatalogVisualize , you will need to set up the build time environment, then compile the CAACciCatalogVisualize module along with its prerequisites, set up the run time environment, and then execute the use case [3]. 

mkrun -c CAACciCatalogVisualize InputPath 

Where:

InputPath : The path of the catalog to visualize. 

You can use catalogs located in CAAComponentsCatalogs.edu/InputData

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

[Top]

Where to Find the CAACciCatalogVisualize Code

The CAACciCatalogVisualize use case is made of two source files located in the CAACciCatalogVisualize.m module of the CAAComponentsCatalogs.edu framework:

Name of the source file Function
CAACciCatalogVisualizeMain Main source file 
CAACciChapterBrowser Global function to browse a chapter

depending on operating system you find them :

Windows InstallRootDirectory\CAAComponentsCatalogs.edu\CAACciCatalogVisualize.m\
Unix InstallRootDirectory/CAAComponentsCatalogs.edu/CAACciCatalogVisualize.m/

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

[Top]

Step-by-Step

In the CAACciCatalogVisualizeMain.cpp file you have four mains steps

  1. Retrieving the CATICatalogChapterFactory Interface Pointer
  2. Retrieving the Catalog's Chapters
  3. Retrieving the Root Chapter
  4. Browsing the Catalog

In the CAACciCatalogChapterBrowser.cpp file,  which contains the CAABrowsingChapter recursive global function to browse a chapter , there is two main steps:

  1. Displaying Chapter's Data
  2. Browsing the Chapter's Descriptions

[Top]

Retrieving the CATICatalogChapterFactory Interface Pointer

 ...
  CATDocument * pDocument = NULL ;
  rc = CATDocumentServices::Open(CatalogPath.CastToCharPtr(), pDocument);
  ...
  CATInit *pInitOnDoc = NULL ;
  rc = pDocument->QueryInterface(IID_CATInit,(void **) &pInitOnDoc);
  ...
  CATIContainer *pIRootCont = NULL ;
  pIRootCont = (CATIContainer*)pInitOnDoc->GetRootContainer("CATIContainer");
  ...
  CATICatalogChapterFactory * pICatalogChapterFactory = NULL ;        
  rc = pIRootCont->QueryInterface(IID_CATICatalogChapterFactory,
                                              (void **) &pICatalogChapterFactory);
 ...

CatalogPath is a CATUnicodeString initialized with the first argument of the CAACciCatalogVisualize main, so the complete name of the catalog to dump.

The root container of a catalog document implements the CATICatalogChapterFactory interface. As usual you retrieve the root container of a document thanks to the CATInit interface.

Retrieving Catalog's Chapters 

Before to dump the catalog, it is interesting to list the chapters of the catalog. 

 ...
  CATListValCATICatalogChapter_var * ListOfChapter = NULL ;
  rc = pICatalogChapterFactory->ListChapters(ListOfChapter);
 ...

pICatalogChapterFactory is the CATICatalogChapterFactory interface pointer previously retrieved. The ListChapters method retrieves the list of the chapters of the CURRENT catalog. It means that this method doesn't retrieve the eventually external chapters pointed by a description [Fig.1].

Retrieving the Root Chapter

 ...
  CATICatalogChapter * pICatalogChapter = NULL ;
  rc = pICatalogChapterFactory->GetRootChapter(pICatalogChapter) ;
  ...
  CATUnicodeString TypeChapter = "Chapter" ;
  if ( TRUE == pICatalogChapter->KindIsEndChapter() )
  {
      TypeChapter = "Family" ;
  }
 ...

The root chapter is the first chapter created in the catalog. This chapter, retrieved by the GetRootChapter, can be a end chapter, but it is not recommended. 

Browsing the Catalog

 ...
  rc = ::CAABrowsingChapter(pICatalogChapter,TypeChapter, 3); 
 ...

The catalog will be recursively browsed from the root chapter. pICatalogChapter is the CATICatalogChapter interface pointer on the root chapter. The last argument indicates the space's number to display the chapters tree. [Fig. 2]

Displaying Chapter's Data

We are inside the CAABrowsingChapter global function. pICatalogChapter is the CATICatalogChapter interface pointer on the chapter to dump, the first argument of this function.

  1. The Name of the Chapter
    2.  ...
 CATUnicodeString ChapterName ;
 ChapterName = pICatalogChapter->GetChapterName();
 ...
  2. The keywords of the Chapter
    3.  ...
    CATListValCATICatalogKeyword_var * pListKeyword = NULL ;
    rc = pICatalogChapter->ListKeywords(pListKeyword);
    int SizeKWList = 0 ;
    if ( SUCCEEDED(rc) && (NULL != pListKeyword) )
    {
        SizeKWList = pListKeyword->Size();
        ...
        for ( int i=1 ; i<= SizeKWList; i++)
        {
            CATICatalogKeyword_var CurrentKeyword ((*pListKeyword)[i]);
            if ( NULL_var != CurrentKeyword )
            {
               CATUnicodeString KWName = CurrentKeyword->GetKeywordName();
        
               if  ( TRUE == CurrentKeyword->GetHidden() )
               {
                   KWName += "(*)";
               }
               CATUnicodeString DefaultValue ;
               CATBoolean IsDefaultValue = pICatalogChapter->GetDefaultValue(KWName,DefaultValue);
 
               if ( FALSE == IsDefaultValue  ) DefaultValue = "Unset" ;

               ...
            }
        }
    }
 ...

    The list of keyword of the chapter is retrieved thanks to the ListKeywords method applied to pICatalogChapter the CATICatalogChapter interface pointer on the chapter. 

    The name of the keyword is given by the GetKeywordName method applied to the CATICatalogKeyword interface pointer on the keyword.

    The default value of a keyword is given by the chapter thanks to the GetDefaultValue method applied to pICatalogChapter the CATICatalogChapter interface pointer on the chapter. If this method returns false, there is no default value, otherwise the value is returned by the second argument  of the method. 

  3. The Persistent Queries of the Chapter
    4.  ...
    CATListValCATICatalogPersistentQuery_var * pListPersistentQuery = NULL ;
    rc = pICatalogChapter->ListPersistentQuery(pListPersistentQuery);

    if ( SUCCEEDED(rc) && (NULL !=pListPersistentQuery) )
    {
       int NbPQ = pListPersistentQuery->Size();
    }
 ...

    Each chapter can contain persistent queries even if it is strongly recommended to set a persistent query to a end chapter and only one for each end chapter. Refer to the "Creating a Persistent Query" article [4] for more details about persistent queries.

Browsing Chapter's Descriptions

  1. Retrieving Descriptions
    2.  ...
    CATListValCATICatalogDescription_var * pListDescription = NULL ;
    rc = pICatalogChapter->ListDescriptions(pListDescription);
    if ( SUCCEEDED(rc) && (NULL != pListDescription) )
    {
        int SizeDescList = pListDescription->Size();
        ...
        CATICatalogDescription_var CurrentDescription ((*pListDescription)[i]);
 ...

    Each chapter contains a list of descriptions. For each element of the list, pListDescription, an analyze of its contents is done in the following sections.  

  2. Displaying Description Name
    3.  ...
    rc = CurrentDescription->GetName(DescriptionName) ;
 ...
  3. Displaying Keywords Value
     ...
                for ( int j= 1 ; j <= SizeKWList ; j++ )
                {
                  CATICatalogKeyword_var CurrentKeyword ((*pListKeyword)[j]);
                  CATUnicodeString value ;
                   
                  CATUnicodeString KWName = CurrentKeyword->GetKeywordName();
 
                  rc = CurrentDescription->GetValue(KWName,value); 
                  ...
                  if ( SUCCEEDED(rc) )
                  {
                     cout << "= " << value.CastToCharPtr() << endl;
                  }else cout << "= Unset" << endl;
                }
 ...

    4. The keywords of a description are the keywords defined on its chapter. pListKeyword  is the list of keywords of the current chapter retrieving at the "The Keywords of the Chapters" step. 

    On each description you retrieve the value of a keyword thanks to the GetValue method. The first argument of the method, KWName, is the name of the keyword. Notice that when there is no value on the keyword (Unset), the GetValue method returns E_FAIL.

  4. Analysing the Referenced object 

[Top]

In Short

This use case enables to understand the catalog structure in analyzing the description's content and in detailing the data (keyword) linked to the chapter.

[Top]

References

[1] Creating a Catalog
[2] Catalog Overview
[3] Building and Launching a CAA V5 Use Case
[4] Creating a Persistent Query
[5] Creating a Catalog with Part Documents
[6] Creating a Catalog with Part Family
[Top]

History

Version: 1 [Jul 2002] Document created
[Top]

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