3D PLM PPR Hub Open Gateway

File XPDM (PX1)

Checking the Consistent Set of Files for V5 Documents

How to retrieve root files and all their associated files?

Use Case

Abstract

Most of scenarios to integrate CATIA V5 to an external PDM system require to know the root files, and to know the set of files pointed by each root. In this manner, you have the consistent set of files for a given document. This article explains and illustrates the methods of the CATxPDMInterface framework to retrieve the root files of a given directory, and to display their associated files.

What You Will Learn With This Use Case
The CAAxPDMRetrieveConsistentSet Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to show you how to use the CATxPDMInterface framework capabilities to retrieve the root files and all their associated files. Mainly through samples, you will learn the meaning and the limits of two methods of the CATxPDMFileServices class:

SearchRootItems: to retrieve, recursively or not, the root files in a given directory
GetConsistentSetOfItems: to retrieve all the files pointed by a root file according to the current activated locators (other folders, Search order). The method returns a list for the existing pointed files, and another one for the missing pointed files.

[Top]

The CAAxPDMRetrieveConsistentSet Use Case

CAAxPDMRetrieveConsistentSet is a use case of the CAAxPDMInterfaces.edu framework that illustrates CATxPDMInterfaces framework capabilities. Be careful, such as all use cases illustrating the CATxPDMInterfaces framework, the current one requires a PX1 license.

[Top]

What Does CAAxPDMRetrieveConsistentSet Do

CAAxPDMRetrieveConsistentSet begins by opening a session, then retrieves all the root items of a given directory, and for each root displays:

The complete file name of the root file
The complete file name of all its existing pointed files
The complete file name of all its missing pointed files

Finally, the session is closed.

Hereunter are given the output for some directories located in the following directory:

Windows	`InstallRootDirectory\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet`
Unix	`InstallRootDirectory/CAAxPDMInterfaces.edu/InputData/RetrieveConsistentSet`

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

But before, some explanations about the RetrieveConsistentSet directory contents are necessary.

Fig.1: The RetrieveConsistentSet directory Contents

Except the empty RetrieveConsistentSet00D directory, all the others contain either Product, Part, Text, Drawing or Exel files. The relationships between these files are detailed just below.

Fig.2: Ref/Ref link	Fig.3:Contextual Part

On Fig.2: outside the assembly context, an element of Part2 has been copied into Part1 using the Copy As Result with link option.
On Fig.3: there is a contextual Part. In assembly context, an element of Part3 has been copied into Part4 using the Copy As Result with link option.

Fig.4 Missing File	Fig.5 Assembly Drawing

On Fig.4: ProductMissingFile.Product had contained two Parts: Part5 and Missing. But the last one has been deleted.
On Fig.5: It is a assembly drawing. There is a kink between the Drawing and the Part.

Fig.6 Part with Design Table

Fig.6: there is a design table associated with the Part

Now we have explained the data, it is possible to understand the result of the code applied to the different directories.

RetrieveConsistentSet00A no recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A
Not Recursive way
There are 2 root(s) in this directory

1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithContLink.CATProduct
Number of items in consistent set:3
-Found items:3
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithContLink.CATProduct
2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet012\Part4.CATPart
3 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet012\Part3.CATPart

2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithoutContLink.CATProduct
Number of items in consistent set:3
-Found items:3
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithoutContLink.CATProduct
2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet011\Part2.CATPart
3 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet011\Part1.CATPart
...

On [Fig.1] you can see that the RetrieveConsistentSet00A directory contains two files: ProductWithContLink.CATProduct and ProductWithoutContLink.CATProduct. There are no links between them, so there are two roots in this directory. The associated files of ProductWithContLink.CATProduct are into theRetrieveConsistentSet012directory [Fig.3], and those of the ProductWithoutContLink.CATProduct are into theRetrieveConsistentSet011directory [Fig.2]. There are no missing files.

On this first output you can see that the list of found items, returned by the GetConsistentSetOfItems method, contains the root itself. It is consistent with the GetListOfDependantFile method of the SendToService idl interface.

RetrieveConsistentSet00B no recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00B
Not Recursive way
There are 2 root(s) in this directory

1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00B\MyText.txt
Number of items in consistent set:1
-Found items:1
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00B\MyText.txt

2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00B\Part6.CATPart
Number of items in consistent set:2
-Found items:2
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00B\Part6.CATPart
2 E:\CAAxPDMInterfaces.tst\FunctionTests\InputData\RetrieveConsistentSet00B\DesignTable1.xls
...

On [Fig.1] you can see that the RetrieveConsistentSet00B directory contains three files: MyText.txt, Part6.CATPart and DesignTable1.xls. But on [Fig.6] you can see that DesignTable1.xls is pointed by Part6.CATPart: So, there are only two roots: MyText.txt and Part6.CATPart. Both are not pointed by another file in the RetrieveConsistentSet00B directory.

RetrieveConsistentSet00C no recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00C
Not Recursive way
ERROR: Impossible to open directory E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00C.
...

The RetrieveConsistentSet00C directory does not exist, so the SearchRootItems method returns an error. The error message contains the not found directory.

RetrieveConsistentSet00D no recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00D
Not Recursive way
There are 0 root(s) in this directory

...

On [Fig.1] you can see that the RetrieveConsistentSet00D directory contains no file. In this case the SearchRootItems method returns 0 root, and not an error.

RetrieveConsistentSet00E no recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00E
Not Recursive way
There are 1 root(s) in this directory

1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00E\Drawing1.CATDrawing
Number of items in consistent set:3
-Found items:3
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00E\Drawing1.CATDrawing
2 E:\CAAxPDMInterfaces.tst\FunctionTests\InputData\RetrieveConsistentSet00E\ProductForDraftingAss.CATProduct
3 E:\CAAxPDMInterfaces.tst\FunctionTests\InputData\RetrieveConsistentSet00E\Part7.CATPart
...

On [Fig.1] you can see that the RetrieveConsistentSet00E directory contains three files: Drawing 1.CATDrawing, Part7.CATPart and ProductForDraftingAss.CATProduct. On [Fig.5] you can see that only Drawing1 .CATDrawing is without links, so it is the only one root of this directory. On the same figure, you can see that Drawing1 .CATDrawing has two links: one toPart7.CATPart and one to the Product. So there are three items in the found items list: the root itself, Part7.CATPart and ProductForDraftingAss.CATProduct There is no missing item.

RetrieveConsistentSet00A/RetrieveConsistentSet011 no recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet011
Not Recursive way
There are 1 root(s) in this directory

1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet011\Part1.CATPart
Number of items in consistent set:2
-Found items:2
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet011\Part1.CATPart
2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet011\Part2.CATPart
...

On [Fig.1] you can see that the RetrieveConsistentSet011 directory contains two files: Part1.CATPart and Part2.CATPart. On [Fig.2] you can see that only Part1.CATPart is without links, so it is the only one root. On the same figure, you can see that Part1.CATPart has only one link to Part2.CATPart. So there are two items in the found items list: the root itself and Part2.CATPart. There is no missing item.

RetrieveConsistentSet00A/RetrieveConsistentSet012 no recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet012
Not Recursive way
There are 1 root(s) in this directory

1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet012\Part4.CATPart
Number of items in consistent set:3
-Found items:3
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet012\Part4.CATPart
2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithContLink.CATProduct
3 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet012\Part3.CATPart
...

On [Fig.1] you can see that the RetrieveConsistentSet012 directory contains two files: Part3.CATPart and Part4.CATPart. On [Fig.3] you can see that only Part4.CATPart is without links, so it is the only one root. On the same figure, you can see that Part4.CATPart has two links: on to Part2.CATPart and one to the Product. So there are three items in the found item list: the root itself, Part3.CATPart and ProductWithContLink.CATProduct There is no missing item.

RetrieveConsistentSet00A/RetrieveConsistentSet013 no recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet013
Not Recursive way
There are 1 root(s) in this directory

1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet013\ProductMissingFile.CATProduct
Number of items in consistent set:3
-Found items:2
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet013\ProductMissingFile.CATProduct
2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet013\Part5.CATPart
-Missing items:1
1 E:\CAAxPDMInterfaces.tst\FunctionTests\InputData\RetrieveConsistentSet001\RetrieveConsistentSet013\Missing.CATPart
...

On [Fig.1] you can see that the RetrieveConsistentSet013 directory contains two files: ProductMissing .CATProduct and Part5.CATPart. On [Fig.4] you can see that only ProductMissing.CATProduct is without links, so it is the only one root. On the same figure, you can see that ProductMissing.CATProduct points to two files Part5.CATPart and Missing.CATPart. The first one is into the found items list, and the second one is into the missing items list: the Missing.CATPart has been deleted.

RetrieveConsistentSet00A recursively

...
Identifying roots in directory : E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A
Recursive way
There are 3 root(s) in this directory

1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithContLink.CATProduct
Number of items in consistent set:3
-Found items:3
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithContLink.CATProduct
2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet012\Part4.CATPart
3 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet012\Part3.CATPart

2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithoutContLink.CATProduct
Number of items in consistent set:3
-Found items:3
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\ProductWithoutContLink.CATProduct
2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet011\Part2.CATPart
3 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet011\Part1.CATPart

3 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet013\ProductMissingFile.CATProduct
Number of items in consistent set:3
-Found items:2
1 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet013\ProductMissingFile.CATProduct
2 E:\CAAxPDMInterfaces.edu\InputData\RetrieveConsistentSet\RetrieveConsistentSet00A\RetrieveConsistentSet013\Part5.CATPart
-Missing items:1
1 E:\CAAxPDMInterfaces.tst\FunctionTests\InputData\RetrieveConsistentSet001\RetrieveConsistentSet013\Missing.CATPart
...

In this last case, the roots are looking for into the RetrieveConsistentSet00Adirectory and into all its sub directories: RetrieveConsistentSet011, RetrieveConsistentSet012 and RetrieveConsistentSet013. If you consider the two figures: Fig.2 and Fig.4 you can see that there is no problem to consider ProductMissingFile and ProductWithoutContLink like roots because they are pointed by nobody. But if you look at Fig.3 there is an ambiguite: ProductWithContLink points Part4 and Part4 points ProductWithContLink. In this case, the SearchRootItems method chooses the product as root: it is the first file opened by the end user in assembly context.

[Top]

How to Launch CAAxPDMRetrieveConsistentSet

To launch CAAxPDMRetrieveConsistentSet, you will need to set up the build time environment, then compile CAAxPDMRetrieveConsistentSet along with its prerequisites, set up the run time environment, and then execute the use case [1]. To launch it, execute the following command:

mkrun -c "CAAxPDMRetrieveConsistentSet DirectoryPath [-r]"

where

DirectoryPath is the complete path of a file directory. You can use those specified in the What Does CAAxPDMRetrieveConsistentSet Do section
The last option [-r] is optional. If you specify it, the root are searched recursively in the specified directory

[Top]

Where to Find the CAAxPDMRetrieveConsistentSet Code

The CAAxPDMRetrieveConsistentSet use case is made of one single file, the CAAxPDMRetrieveConsistentSetMain.cpp file, located in the CAAxPDMRetrieveConsistentSet.m module of the CAAxPDMInterfaces.edu framework:

Windows	`InstallRootDirectory\CAAxPDMInterfaces.edu\CAAxPDMRetrieveConsistentSet.m\`
Unix	`InstallRootDirectory/CAAxPDMInterfaces.edu/CAAxPDMRetrieveConsistentSet.m/`

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

[Top]

Step-by-Step

There are forth logical steps in CAAxPDMRetrieveConsistentSet:

Prolog
Retrieving the Root Files
Retrieving the Existing and Missing Pointed Files
Epilog

[Top]

Prolog

...
HRESULT rc=S_OK ;
CATUnicodeString directory  ;
CATBoolean RecursiveScan = FALSE ;
char * pSessionName = "CAA_Sample_Session";
CATSession *pSession = NULL;
rc = ::Create_Session(pSessionName,pSession);
...

CAAxPDMRetrieveConsistentSet begins by creating a session. From the command line is extracted the directory to analyze, and the recursiveness option. Refer to the code to see how directory and RecursiveScan are initialized.

[Top]

Retrieving the Root Files

...
   CATListOfCATUnicodeString iListOfDirectory;
   CATListValCATIxPDMItem_var oListOfRootItem;
   iListOfDirectory.Append(directory);
   HRESULT hr = CATxPDMFileServices::SearchRootItems(iListOfDirectory,
                                                 RecursiveScan,oListOfRootItem);
..

SearchRootItems is a static method of the CATxPDMFileServices class. Its argument are the following:

iListOfDirectory, the list of directories to scan. This list contains only one element, directory, the input directory initialized in the Prolog step.
RecursiveScan is a boolean. TRUE, the roots are recursively searched in the input directory, and its sub-directories, otherwise only in the input directory.
oListOfRootItem is the output list of roots, each one handled by a CATIxPDMItem pointer

Then, such as all methods of the CATxPDMFileServices class, the SearchRootItems method returns a CATError class instance in case of failure. You retrieve this error thanks to CATGetLastError, a global function [2]. Refer to the RetrieveConsistentSet00C case in the What Does CAAxPDMCheckDocType Do section for an illustration

...
   if (FAILED(hr))
   {
      CATError * pError = CATError::CATGetLastError(hr);
      if ( NULL != pError )
      {
         CATUnicodeString ErrorMessage = pError->GetNLSMessage() ;
      }
...

Finally, there is a loop on each root item to analyze its pointed files. The GetDocFileName method enables us to display the complete file path of the current root file.

...
   int size = oListOfRootItem.Size();
   CATUnicodeString FileName;
   for (int i=1;i<=size;i++)
   {
      CATIxPDMItem_var spCurrentRootItem = oListOfRootItem[i];
      if (!!spCurrentRootItem )
      {
         spCurrentRootItem ->GetDocFileName(FileName);
         
...

[Top]

Retrieving its existing and Missing Pointed Files

You retrieve the files pointed by a root thanks to GetConsistentSetOfItems a static method of the CATxPDMFileServices class.

...
 CATListValCATIxPDMItem_var oListOfPointedItem;
 CATListValCATIxPDMItem_var oListOfMissingItem;
 if (SUCCEEDED(CATxPDMFileServices::GetConsistentSetOfItems(spCurrentRootItem,
                                             oListOfPointedItem,oListOfMissingItem)))
 {
    int sizeListOfPointedItem=oListOfPointedItem.Size();
    int sizeListOfMissingItem=oListOfMissingItem.Size();

    if (sizeListOfPointedItem)
    {
       for (int j=1;j<=sizeListOfPointedItem ;j++)
       {
          CATIxPDMItem_var spCurrentPointedItem = oListOfPointedItem[j];
          if (!!spCurrentPointedItem)
          {
             spCurrentPointedItem->GetDocFileName(FileName);
       ...
    }
    if (sizeListOfMissingItem)
    {
       for (int j=1;j<=sizeListOfMissingItem ;j++)
       {
          CATIxPDMItem_var spCurrentMissingItem= oListOfMissingItem[j];
          if (!!spCurrentMissingItem)
          {

The GetConsistentSetOfItems method returns two lists of smart pointers on the CATIxPDMItem interface pointer:

oListOfPointedItem : The existing files pointed by the root
oListOfMissingItem : The missing files pointed by the root

The two lists form the consistent set of files for a root. This API can be useful before using the SendTo API. If there is at least one missing file, the SendTo applied to the root file will be not consistent.

[Top]

Epilog

The session is closed using the global function named Delete_Session.

...
rc = ::Delete_Session(pSessionName);
...

pSessionName is the name of the session declared and used in the Prolog section.

[Top]

In Short

You have learned that using function of the CATxPDMFileServices class you can:

Retrieve all the root of a directory and its contained directories
Retrieve the existing and missing files pointed by a root document. The result of these two lists is dependent of the current locators.

[Top]

References

[1]	Building and Launching a CAA V5 Use Case
[2]	Managing Errors Using HRESULT
[Top]

History

Version: 1 [Feb 2005]	Document created
[Top]