3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

This Use Case illustrates the CATIPrdHandleImpactsOnInstance and CATIPrdHandleImpactsOnReference APIs
The CATIPrdHandleImpactsOnInstance APIs rename a Product Instance and manage the impacts. The impacted elements are those which point to this instance are reconnected.

On renaming a Publication, the CATIPrdHandleImpactsOnReference APIs manage the impacts. The impacted elements are those which point to this publication are reconnected

[Top]

The CAAxPDMProductHandleImpactOn Use Case

CAAxPDMProductHandleImpactOn is a use case of the CAAxPDMInterfaces.edu framework that illustrates the ProductStructureInterfaces and CATxPDMInterfaces framework capabilities.

[Top]

What Does CAAxPDMProductHandleImpactOn Do

The input model consists of CAAxPDMProductHandleImpactOn_Root.CATProduct which has a root product "Product1", aggregating beneath it

• Part Instance (Part1.1) which has a Publication "Face"
• Part Instance (Part2.1) built with an External Reference "Surface.1 (Part1.1!Face)

Fig.1 Initial V5 document(s)

• Part1.1 is an instance of a Part stored inside CAAxPDMProductHandleImpactOn_Part1.CATPart file
• Part1.2 is an instance of a Part stored inside CAAxPDMProductHandleImpactOn_Part2.CATPart file

The first step consists in to rename the publication "Face" to "NewFace". Then the Part Instance (Part1.1) is renamed to NewInstance. These two renaming operations successively update the contextual link in the External Reference node within the Part Instance (Part2.1) to (NewInstance!NewFace). Fig.2 shows the final result:

Fig.2 Final V5 documents

In the final step the Use Case saves all documents in session, having renamed the three input V5 documents. The link consistency between all documents in session is maintained on rename. The new filename of the three input V5 documents is specified in the How to Launch section.

[Top]

How to Launch CAAxPDMProductHandleImpactOn

To launch CAAxPDMProductHandleImpactOn, you will need to set up the build time environment, then compile CAAxPDMProductHandleImpactOn along with its prerequisites, set up the run time environment, and then execute the sample. This is fully described in the referenced article [1]. To launch the use case, execute the following command:

mkrun -c "CAAxPDMProductHandleImpactOn InputPath OutputPath"

• InputPath - the path to the input CATProduct document namely.  CAAxPDMProductHandleImpactOn_Root.CATProduct. This CATProduct aggregates instances of CAAxPDMProductHandleImpactOn_Part1.CATPart and CAAxPDMProductHandleImpactOn_Part2.CATPart within it. These are found at the following location:

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

  where InstallRootDirectory is the root directory of your CAA V5 installation.

• OutputPath-  the path to the output documents

• CAAxPDMProductHandleImpactOn_Root.CATProduct is renamed to CAAxPDMProductHandleOnImpactNew.CATProduct
• CAAxPDMProductHandleImpactOn_Part1.CATPart is renamed to CAAxPDMPart1HandleOnImpactNew.CATPart
• CAAxPDMProductHandleImpactOn_Part1.CATPart is renamed to CAAxPDMPart2HandleOnImpactNew.CATPart

[Top]

Where to Find the CAAxPDMProductHandleImpactOn Code

CAAxPDMProductHandleImpactOn code is located in the CAAxPDMProductHandleImpactOn.m use case module of the CAAxPDMInterfaces.edu framework:

where InstallRootDirectory is the root directory of your CAA V5 installation. It is made of a unique source file named CAAxPDMProductHandleOnImpact.cpp.

[Top]

Step-by-Step

There are ten logical steps in CAAxPDMProductHandleImpactOn:

We will now comment each of these steps by looking at the code.

• Create a new session
• Retrieve the CATProduct Document
• Retrieve the Document's Root Product
• Retrieve the root product's children
• Rename a Publication which occurs under a Child Reference
• Rename a Child Instance
• Check Publication name is indeed renamed
• Check child Instance is indeed renamed
• Save the Session and Rename the input Documents
• Epilog

[Top]

Create a New Session

...
CATSession *pSession = NULL;
rc = ::Create_Session("CAAxPDMProductHandleImpactOn_Session", pSession );

Generally, the first thing that is necessary in a batch program is the creation of a new session. This is done using the Create_Session global function. It is important not to forget to delete the session at the end of your batch program.

[Top]

Retrieve the CATProduct Document

CATDocument *pDoc = NULL;
CATUnicodeString InputPath(iArgv[1]);
InputPath += Slash;
InputPath += CATUnicodeString("CAAPstProductRename.CATProduct");

rc = CATDocumentServices::OpenDocument(InputPath, pDoc);

Once the current session has been created, the CATProduct document can be loaded into the session using the OpenDocument method of CATDocumentServices. The input parameter representing the pathname of the document to be loaded is taken from the first argument passed to this program. As output, we receive a CATDocument pointer (pDoc) to the document loaded into the session.

[Top]

Retrieve the Document's Root Product

CATIDocRoots* piDocRootsOnDoc = NULL;
rc = pDoc->QueryInterface(IID_CATIDocRoots,
                         (void**) &piDocRootsOnDoc);
...
CATListValCATBaseUnknown_var* pRootProducts = piDocRootsOnDoc->GiveDocRoots();
CATIProduct_var spRootProduct = NULL_var;
...
spRootProduct = (*pRootProducts)[1];
...
CATIProduct *piProductOnRoot = NULL;
rc = spRootProduct->QueryInterface(IID_CATIProduct,(void**) &piProductOnRoot);

In order to access a product structure within the CATProduct document, it is now necessary to access the root product. The CATIDocRoots implementation of the CATProduct document provides us with services to access the root product. The GiveDocRoots method of CATIDocRoots returns a list of all of the roots within the document, the first one being the root product we are looking for.

We retrieve a CATIProduct handle on the root product, which lets us access its children.

[Top]

Retrieve the Root Product's Children

The CATIProduct::GetChildren call returns the children beneath root. Each child is retrieved as CATIProduct_var type.

[Top]

Rename a Publication which occurs under a Child Reference

CATIProduct_var spRefOnChild1 = spChild1->GetReferenceProduct();

The call to CATIProduct::GetReferenceProduct retrieves the Child Reference from its Instance. It is retrieved as a CATIProduct_var type.

CATIPrdHandleImpactsOnReference * pIPrdHandleImpactsOnReferenceOnFirstRef = NULL;
rc = spRefOnChild1->QueryInterface(IID_CATIPrdHandleImpactsOnReference,
				  (void **) &pIPrdHandleImpactsOnReferenceOnFirstRef);
rc = pIPrdHandleImpactsOnReferenceOnFirstRef->RenamePublication(CATUnicodeString("Face"),
                                                                CATUnicodeString("NewFace"));

The CATIPrdHandleImpactOnReference::RenamePublication implementation on the Child Reference renames the Publication, and manages all the entities pointing this publication.

[Top]

Rename a Child Instance

The CATIPrdHandleImpactOnInstance::RenameInstance implementation on the Child Instance renames it, and manages all the entities pointing this publication.

[Top]

Check Publication is Renamed

The CATIPrdObjectPublisher::ListPublications implementation on the Child Reference returns a list of Publication Names (CATUnicodeString types) for verification. We then confirm if the Publication is indeed renamed.

[Top]

Check Child Instance is Renamed

The CATIProduct::GetPrdInstanceName implementation on the Child Instance returns the Instance Name for verification. We then confirm if the Instance is indeed renamed.

[Top]

Save the Session and Rename the input Documents

Before to call the save API, the first step is to retrieve the V5 document corresponding to each Child Reference.

CATIProduct::GetReferenceProduct returns the PLM Reference associated with the Child Instance. Next we retrieve the CATILinkableObject* type on the Child Reference. A call to CATILinkableObject::GetDocument returns the document associated with the Child reference, as a CATDocument* type (pPartDocument1, pPartDocument2)

The next step is to retrieve the V5 item corresponding to each document. This will be useful for the Save API.

...		
CATListValCATIxPDMItem_var iListItemToRename;
CATIxPDMItem_var spItemPart1;
rc = CATxPDMSessionServices::GetItemFromDocument(pPartDocument1,spItemPart1);
...
CATIxPDMItem_var spItemPart2;
rc = CATxPDMSessionServices::GetItemFromDocument(pPartDocument2,spItemPart2);
...

CATIxPDMItem_var spItemProduct;
rc = CATxPDMSessionServices::GetItemFromDocument(pDoc,spItemProduct);
...
		
iListItemToRename.Append(spItemPart1);
iListItemToRename.Append(spItemPart2);
iListItemToRename.Append(spItemProduct);
...

iListItemToRename will be one argument of the save api.

Then, we build the list of the new name for each V5 document to rename:

...
CATListOfCATUnicodeString iListOfNewNames;
iListOfNewNames.Append("CAAxPDMPart1HandleOnImpactNew.CATPart");
iListOfNewNames.Append("CAAxPDMPart2HandleOnImpactNew.CATPart");
iListOfNewNames.Append("CAAxPDMProductHandleOnImpactNew.CATProduct");
...

iListOfNewNames will be also one argument of the save api.

and finally we save the session in specifying those to rename:

... 
CATUnicodeString oErrorMessage;
rc = CATxPDMSessionServices::SaveSessionToDirectory(OutputPath11, 
		oErrorMessage,
		&iListItemToRename,&iListOfNewNames);
... 

CATxPDMSessionServices::SaveSessionToDirectory saves a session to a specified directory while keeping link consistency between all documents if some are renamed. The argument it takes are

• OutputPath11, the target directory for save
• oErrorMessage, detailed error message if the result is E_FAIL
• iListItemToRename, A list of CATIxPDMItem handler type on a V5 Item stored in the document. It is retrieved by CATxPDMSessionServices::GetItemFromDocument call
• iListOfNewNames, A list of CATUnicodeString representing the new names

[Top]

Epilog

The final step is to unload the original documents from the current session. Finally the session is deleted.

[Top]

In Short

This Use Case illustrates the CATIPrdHandleImpactsOnInstance and CATIPrdHandleImpactsOnReference APIs
The CATIPrdHandleImpactsOnInstance APIs rename a Product Instance and manage the impacts. The impacted elements are those which point to this instance are reconnected.

On renaming a Publication, the CATIPrdHandleImpactsOnReference APIs manage the impacts. The impacted elements are those which point to this publication are reconnected

[Top]

References

History

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