Catalog Modeler

What You Will Learn With This Use Case

This use case shows how to create a catalog which contains a Part family. A Part family is a chapter whose all the descriptions are components created from a single Part which has several configurations referenced in a design table. This article describes in particularly the contents of such descriptions and remind you that the design table must necessarily contain a "Part Number" column. It tackles also the question of the description resolution. 

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]

The CAACciNuts6SidesCatalogCreation Use Case

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

[Top]

What Does CAACciNuts6SidesCatalogCreation Do

This use case creates the CAANuts6Sides.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. 

Fig.1: The CAANuts6Sides.catalog Document

The Nuts6Sides chapter is the root chapter which  contains the Nuts6SidesFamily chapter. 

The Nuts6SidesFamily chapter is a end chapter and more precisely a Part Family because the contents of this chapter will be created in associating it with a design table [Fig 4] of  the CAANuts6Sides Part document [Fig 3]. 

The Nuts6SidesFamily contains 3 descriptions, one for each line of the design table: 

Fig.2 The Descriptions of the Nuts6SidesFamily Part Family

The document which contains the design table is CAANuts6Sides.CATPart:

Fig.3: The CAANuts6Sides.CATPart Document

This design table consists in a file text (*) whose each line defines a configuration for the Part [Fig 4]. This file contains the following lines:

where: 

• PartNumber, is a mandatory field, it gives a name to the design table line
• PartBody\Pad.1\FirstLimit\Length, is the name of the parameter Length in the Pad Definition dialog box when the Dimension type is selected. [Fig 5]
• PartBody\Hole.1\Diameter, is the name of the parameter Diameter in the Hole Definition dialog box. [Fig 5]

(*)  xls file is not UNIX compliant

Fig.5 The Pad Definition and the Hole Definition Dialog Box

The last step of the use case is to resolve the Part configurations. It means that Part documents are created, one for each configuration defined by the design table. The location of the new Part documents is defined by the Tools/Options command in the Folder editor.

Fig.6 Tools Options- Catalogs Tab page

In the next image, [Fig 7], you can note that in the Reference tab page, the column "Type" is "Resolved part family configuration", and the "Object Name" column is the location of the resolved file.

Fig.7 The Resolution of the Nuts6SidesFamily Part Family

The interactive scenario to obtain the same CAANuts6Sides.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 Nuts6Sides in the Name field and click OK
• Launch the Add Part Family command
• In the Part Family Definition dialog box
  • Enter Nuts6SidesFamily in the Name field
  • Push Select Document
  • in the File Selection dialog box retrieve the CAANuts6Sides.CATPart (*) file and click Open
  • click OK
• Select Nuts6SidesFamily in the specification tree
• Contextual menu, select Nuts6SidesFamily object item and Resolve item 

(*) The file is 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 CAACciNuts6SidesCatalogCreation

To launch CAACciNuts6SidesCatalogCreation , 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 [2]. 

mkrun -c CAACciCatalogCreate InputPath [OutputPath]

Where:

1. InputPath : The path of some 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 [3] 
• CAANuts6Sides.catalog, explained in the current article
• CAATools.catalog, explained in the "Creating a Catalog" article [4]

After its execution, you can launch CATIA and open the created catalogs or execute the CAACciCatalogNavigation use case [5] for each. This use case displays the contents of a catalog.  

[Top]

Where to Find the CAACciNuts6SidesCatalogCreation Code

The CAACciNuts6SidesCatalogCreation 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 CAACciNuts6SidesCatalogCreation use case:

1. Creating a New Catalog Document
2. Creating the Root Chapter 
3. Creating the End Chapter 
4. Adding the Design Table to the End Chapter which Becomes a Part Family
5. Retrieving the Description List of the Part Family
6. Displaying the Keyword List of the Part Family
7. Displaying the Keyword's Value of the each Description of the Part Family
8. Resolving Part Configuration
9. Closing the Catalog

Some operations like create a document, save a document, retrieve the design table have been factorized in global functions. These functions are defined in the CAACciCatalogServices.cpp file. You retrieve theirs explanations in the "Creating a Catalog" article [4] .

[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 a CATICatalogChapterFactory interface pointer on its root container. This interface is necessary to create chapters. 

Creating the Root Chapter 

 ...
    if ( SUCCEEDED(rc) && ( NULL != pICatalogChapterFactory) )
    {
       CATICatalogChapter * piNuts6SidesChapter = NULL ;

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

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

The Nuts6Sides chapter is the first chapter created in the new document, so it is the root chapter. It means that you can retrieve it thanks to the GetRootChapter method of the same interface CATICatalogChapterFactory . Refer to the use case "Browsing a Catalog" [5] for an example about this method.

Creating the End Chapter 

 ...
       CATICatalogChapter * piNuts6SidesFamily = NULL ;

       if ( SUCCEEDED(rc) )
       {
          CATUnicodeString     ChapterName = "Nuts6SidesFamily" ;
          CATBoolean           IsEndChapter = TRUE ;
          rc = pICatalogChapterFactory->CreateChapter(ChapterName,IsEndChapter,piNuts6SidesFamily);
          ...
       }
 ...

As the Nuts6Sides chapter, the Nuts6SidesFamily chapter is created thanks to the CATICatalogChapterFactory interface. But contrary to the Nuts6Sides chapter, the second argument of this method is TRUE: it means that the Nuts6SidesFamily chapter is a end chapter, in other words, it could contains only descriptions referencing components and not chapters.

 ...
       if ( SUCCEEDED(rc) && (NULL != piNuts6SidesFamily) && (NULL != piNuts6SidesChapter) )
       {                    
          CATILinkableObject * pLinkOnFamily = NULL ;
          rc = piNuts6SidesFamily->QueryInterface(IID_CATILinkableObject,
                                              (void **) &pLinkOnFamily);     
          if ( SUCCEEDED(rc) )
          {
             CATICatalogDescription * piDescription = NULL ;
             rc = piNuts6SidesChapter->AddDescription(piDescription, pLinkOnFamily);
             if ( SUCCEEDED(rc) && (NULL != piDescription) )
             {
                piDescription->Release();
                piDescription = NULL ;
             }

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

Like any kind object to set in a description, the CATILinkableObject interface on the Nuts6SidesFamily chapter, pLinkOnFamily, is necessary.  The AddDescription method applied  to the Nuts6Sides chapter, the parent chapter pointed by piNuts6SidesChapter, creates a new description with the pLinkOnFamily interface pointer on the Nuts6SidesFamily chapter.

Adding the Design Table to the End Chapter which Becomes a Part Family

 ...
          CATDocument * pCAANuts6SidesDocument = NULL ;
          CATUnicodeString ModelDocName = "CAANuts6Sides.CATPart" ;
          ModelDocName = iInputPath + Slash + "CAANuts6Sides.CATPart" ;

          CATIDesignTable * pDesignTable = NULL ;
          if ( SUCCEEDED(rc) )
          {
             rc = ::CAARetrieveDTInPartDocument(ModelDocName,pDesignTable);
          }
          if ( SUCCEEDED(rc) && ( NULL!=pDesignTable) )
          {
             rc = piNuts6SidesFamily->AddFamilyDescriptionsFromDesignTable(pDesignTable);
             ...
             pDesignTable->Release();
             pDesignTable = NULL ;
          } 
...

The CAARetrieveDTInPartDocument global function retrieves the design table from the CAANuts6Sides Part document. The design table is associated with a Part Family thanks to the AddFamilyDescriptionsFromDesignTable method. This method is applied on piNuts6SidesFamily, the CATICatalogChapter interface pointer on the Nuts6SidesFamily chapter. 

It is important to notice that the design table must contain the PartNumber column. The CAARetrieveDTInPartDocument doesn't check that but it is a mandatory pre-requisite for the design table. The PartNumber  value represents the name of the description. The GetName method of the CATICatalogDescription returns this value (In fact, you will see in the "Displaying the Keyword List of the Part Family" section, the value of the PartNumber  keyword)

On a Part family you can associate several design table from the same Part, but it is not recommended to associate design tables from several Part document.

Retrieving the Descriptions of the Part Family

 ...
          CATListValCATICatalogDescription_var * pListDesc = NULL ;
          int NbDesc = 0 ;
          if ( SUCCEEDED(rc) )
          {
             rc = piNuts6SidesFamily->ListDescriptions(pListDesc);
             NbDesc = pListDesc->Size() ;
             ...
          }
...

The list of descriptions of the Nuts6SidesFamily chapter, the Part Family, is retrieved thanks to the ListDescriptions method. This method is applied on piNuts6SidesFamily, the CATICatalogChapter interface pointer on the Nuts6SidesFamily chapter. 

Displaying the Keyword List of the Part Family

 ...
          int NbKeyword = 0 ;
          if ( SUCCEEDED(rc) )
          {
             rc = piNuts6SidesFamily->ListKeywords(pListKeyword);
             if ( SUCCEEDED(rc) && (NULL != pListKeyword) )
             {
                NbKeyword = pListKeyword->Size() ;
                ...
                for ( int i= 1 ; i<= NbKeyword; i++)
                {
                   CATICatalogKeyword_var spKeyword = (*pListKeyword)[i];
                   if ( NULL_var != spKeyword )
                   {              
                      cout <<"         " << spKeyword->GetKeywordName().CastToCharPtr() << endl;               
                   } 
                }
                cout << endl;
             }else rc = E_FAIL ;
          }
...

After the association of the design table on the chapter, a keyword for each column of the design table has been automatically created on the chapter. There is at least the PartNumber keyword since the design table contains necessarily a column with this name. 

The list of keywords of the Nuts6SidesFamily chapter, the Part Family, is retrieved thanks to the ListKeywords method. This method is applied on piNuts6SidesFamily, the CATICatalogChapter interface pointer on the Nuts6SidesFamily chapter. 

Displaying the Keyword's Value of each Description of the Part Family

 ...
          if ( SUCCEEDED(rc) && ( NULL != pListKeyword) && ( NULL !=pListDesc))
          {
                 int i = 1 ;
                 while ( SUCCEEDED(rc) && (i <= NbDesc ))
                 {
                     CATUnicodeString KWName, KWValue;
                     CATICatalogDescription_var spDesc = (*pListDesc)[i] ;
    
                     if ( NULL_var != spDesc )
                     {
                        for ( int j= 1 ; j <= NbKeyword ; j++ )
                        {
                             if ( NULL_var !=  (*pListKeyword)[j] )
                             {
                                CATUnicodeString KWName = (*pListKeyword)[j]->GetKeywordName();
                                rc = spDesc->GetValue(KWName, KWValue) ;
                                ...
                             }
                        }
                     }
                     ...
                     i++ ;
                 }
          }
...

The value of each keyword is defined in using the values in the design table. 

Resolving the Part Configuration

 ...
          if ( SUCCEEDED(rc) && ( NULL!= pListDesc) )
          {
                 int i = 1 ;
                 while ( SUCCEEDED(rc) && (i <= NbDesc ))
                 {
                     CATICatalogDescription_var spDesc = (*pListDesc)[i] ;
                      
                     if ( NULL_var != spDesc )
                     {
                        rc = spDesc->ResolvedDocumentFromDesignTable();
                        ...
                     }
                     i++ ;
                 }
          }
...

pListDesc is the list of CATICatalogDescription smart pointers for the Nuts6SidesFamily chapter. Before the resolution, all these descriptions contain a pointer to the CAANuts6Sides Part document, the document which contains the design table. In applying the ResolvedDocumentFromDesignTable method on a description, a  Part is created in taken account of the configuration of the design table. 

Notice, that if the use case resolves all the descriptions, it is not mandatory. 

Closing the New Catalog

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

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

[Top

In Short

This use cases illustrates how to associate a design table to a chapter. This chapter, a end chapter, is also called a Part family. Four things to retain:

• The design table must contain the Part Number column
• The keywords of the Part family are automatically created from the design table keywords
• The value of each keyword for each description comes from the design table
• A description can be resolved to create a Part in taken account of the configuration referenced by the design table. The location of the resolved Part document is defined in Tools/Options Catalogs tab page.

[Top]

References

History

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