3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

Using the CATIPrdObjectPublisher interface, the publications of a product and its components can be accessed and modified.

[Top]

The CAAPstPrdObjectPublisher Use Case

CAAPstPrdObjectPublisher is a use case of the CAAProductStructure.edu framework that illustrates the ProductStructure framework capabilities.

[Top]

What Does CAAPstPrdObjectPublisher Do

The goal of CAAPstPrdObjectPublisher is to demonstrate the CATIPrdObjectPublisher interface. It performs the following steps:

• Loads a Product document
• Displays the publications of the Root Product and its components
• Remove a publication and add new one
• Redisplay the modified publications
• Save the modified document in a new file

Below  is the Product document that will be loaded in the use case. It can be found in

InstallRoot/CAAProductStructure.edu/CNext/resources/graphic/CAAPstPrdObjectPublisher.CATProduct

The CAAPstPrdObjectPublisher product consists of a single part, CAAPstPrdObjectPublisher_Part.1 which publishes four of its faces:

• Green
• Yellow
• Red
• Orange

The product CAAPstPrdObjectPublisher has two publications:

• GreenPart (republication of CAAPstPrdObjectPublisher_Part.1 Green publication)
• BlueProd (direct publication of the Blue face of CAAPstPrdObjectPublisher_Part.1)

The code in the use case displays all the publications, modifies it and displays it again. It produces the output below with CAAPstPrdObjectPublisher.CATProduct as input. There are three distinct sections in the output:

1. The first section in green, lists the unmodified publications
2. The second section in red, details the modifications that have been carried out
3. The last section in blue, displays the modified publications

Publications of CAAPstPrdObjectPublisher:
  Publication 1: GreenPart
    is finally published as GreenPart
    is a subpublication of Green
  Publication 2: BlueProd
    is finally published as BlueProd
    is published as BlueProd

Publications of CAAPstPrdObjectPublisher_Part:
  Publication 1: Green
    is finally published as Green
    is published as Green
  Publication 2: Yellow
    is finally published as Yellow
    is published as Yellow
  Publication 3: Red
    is finally published as Red
    is published as Red
  Publication 4: Orange
    is finally published as Orange
    is published as Orange

>> deleted publication GreenPart
>> unvaluated publication Green
>> deleted publication Green

>> created new publication OrangeProd
>> valuated publication OrangeProd

Publications of CAAPstPrdObjectPublisher:
  Publication 1: BlueProd
    is finally published as BlueProd
    is published as BlueProd
  Publication 2: OrangeProd
    is finally published as OrangeProd
    is published as OrangeProd

Publications of CAAPstPrdObjectPublisher_Part:
  Publication 1: Yellow
    is finally published as Yellow
    is published as Yellow
  Publication 2: Red
    is finally published as Red
    is published as Red
  Publication 3: Orange
    is finally published as Orange
    is published as Orange

The modified product is also saved in a new document showing that:

• a publication has been removed both at the product level (GreenPart) and at the part level (Green)

• a new publication has been added at the product level (OrangeProd).

[Top]

How to Launch CAAPstPrdObjectPublisher

To launch CAAPstPrdObjectPublisher:

1. Set the current directory to InstallRoot/CAAProductStructure.edu
2. Set up  the build time environment and build the CAAPstPrdObjectPublisher.m module (see [2])
3. Execute the following command:
   
   mkrun -c "CAAPstPrdObjectPublisher input pubToDelete pubToPublish outputDir"

• input: path to the supplied document InstallRoot/CAAProductStructure.edu/CNext/resources/graphic/CAAPstPrdObjectPublisher.CATProduct
• pubToDelete: a publication to be deleted. It must exist at the product level and is a subpublication. The only valid choice for this argument is GreenPart.
• pubToPublish: a publication to be published at the product level. It must exist at the part level. The valid choices for this argument are: Yellow, Red and Orange.
• outpuDir: path of the output directory where the modified document will be stored. This document's name will be prepended with "New". Please note that the directory must be with a / on Unix or a \ on Windows.

[Top]

Where to Find the CAAPstPrdObjectPublisher Code

CAAPstPrdObjectPublisher code is located in the CAAPstPrdObjectPublisher.m module of the CAAProductStructure.edu framework.

[Top]

Step-by-Step

There are six logical steps in CAAPstPrdObjectPublisher:

1. Loading a Product Document
2. Retrieving the Document's Root Product
3. Retrieving the Root Product Components
4. Displaying the Publications of the Root Product and its Components
5. Displaying the Publications of a Product
6. Modifying a Product's Publications
7. Saving the Modified Document in a New File
8. Closing the Session

We will now detail each of those sections:

[Top]

Loading a Product Document

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 when the program exits. Once the session is created, a CATProduct document can be loaded with CATDocumentServices::Open.

	CATSession *pSession = NULL;
	rc = ::Create_Session("CAA_PrdObjectPub_Session", pSession);
...
	//----------------------------------------------------------------------
	// Opening an existing document with full path specified 
	//----------------------------------------------------------------------
	CATDocument *pDoc = NULL;
	rc = CATDocumentServices::Open(inputDoc, pDoc);

[Top]

Retrieving the Document's Root Product

In order to work with a product structure within the Product document, it is necessary to access the root product. This is done using the GiveDocRoots method of CATIDocRoots which returns a list of all of the roots within the document, the first one being the root product we are looking for.

        //----------------------------------------------------------------------
        // Search for 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;

        if (NULL != pRootProducts && pRootProducts->Size() > 0) { 
                spRootProduct = (*pRootProducts)[1];
...
        } else {
                cout << "Failed to get Root Product" << endl;
                return 5;
        }

[Top]

Retrieving the Root Product's Components

Now that we have the root product, it is necessary to get its CATIProduct handle in order to access to its components.

        //----------------------------------------------------------------------
        // Get CATIProduct handle on the root product.
        //----------------------------------------------------------------------
        CATIProduct *piProductOnRoot = NULL;
        if (NULL_var != spRootProduct)
                rc = spRootProduct->QueryInterface(IID_CATIProduct,
                                                   (void**) &piProductOnRoot);
...

        //----------------------------------------------------------------------
        // Get the root product's children
        //----------------------------------------------------------------------
        CATListValCATBaseUnknown_var *pChildren = NULL;
        pChildren = piProductOnRoot->GetAllChildren();
        int childCount = (pChildren == NULL ? 0 : pChildren->Size());

[Top]

Displaying the Publications of the Root Product and its Components

Now that we have the CATIProduct handle on the root product and its components, we can display all the publications

        //----------------------------------------------------------------------
        // Displaying the publications of the root product and its components
        //----------------------------------------------------------------------
        rc = PrintPublications(piProductOnRoot);
        if (0 != rc) return rc;
        for (int i = 1; i <= childCount; i++) {
                rc = PrintPublications((CATIProduct_var) (*pChildren)[i]);
                if (0 != rc) return rc;
        }

Displaying the Publications of a Product

The goal of the PrintPublications function is to display a product's publications. Using the CATIPrdObjectPublisher interface, it does the following tasks:

• retrieve the list of all the publications with ListPublications

  static int PrintPublications(CATIProduct *ipiProduct) { int rc; CATIPrdObjectPublisher *piPublisher = NULL; if (NULL == ipiProduct) return 0; rc = ipiProduct->QueryInterface(IID_CATIPrdObjectPublisher, (void **) &piPublisher); ... CATUnicodeString productName = ipiProduct->GetPartNumber(); cout << endl << "Publications of " << productName << ":" << endl; // // Retrieve the list of the publications of the current product. // CATListValCATUnicodeString *pPubList = NULL; int pubCount = piPublisher->ListPublications(pPubList); if (0 == pubCount || NULL == pPubList) { pubCount = 0; cout << " none" << endl; } ...

• get the final publication object with GetFinalObject

  ... for (int i = 1; i <= pubCount; i++) { // // Print the publication name // CATUnicodeString& pubName = (*pPubList)[i]; cout << " Publication " << i << ": " << pubName.ConvertToChar() << endl; // // Retrieve the final publication object pointed to by // this publication name. // CATBaseUnknown *pPubObject = piPublisher->GetFinalObject(pubName); if (NULL == pPubObject) { cout << "Failed to get publication object of " << pubName << endl; return 10; } ...

• retrieve the list of publications referencing a given publication with IsFinallyPublished

  ... // // List publications pointing to other sub publications // CATListValCATBaseUnknown_var *pSubPubrList = NULL; CATListValCATUnicodeString *pSubPubNameList = NULL; rc = piPublisher->IsFinallyPublished(pPubObject, pSubPubrList, pSubPubNameList); if (rc && NULL != pSubPubrList && NULL != pSubPubNameList && pSubPubrList->Size() > 0 && pSubPubNameList->Size() > 0) { cout << " is finally published as"; for (int i = 1; i <= pSubPubNameList->Size(); i++) cout << " " << (*pSubPubNameList)[i]; cout << endl; } ...

• retrieve the list of an object's publications with IsPublished

  ... // // List publications directly on the geometry // CATListValCATUnicodeString *pNameList = NULL; rc = piPublisher->IsPublished(pPubObject, pNameList); if (rc && NULL != pNameList && pNameList->Size() > 0) { cout << " is published as"; for (int i = 1; i <= pNameList->Size(); i++) cout << " " << (*pNameList)[i]; cout << endl; } ...

• get the direct publication object with GetDirectObject

  ... // // Get the direct publication object // CATBaseUnknown *pSubPubr = NULL; CATUnicodeString subPubName; rc = piPublisher->GetDirectObject(pubName, pSubPubr, subPubName); if (2 == rc && NULL != pSubPubr) { cout << " is a subpublication of " << subPubName.ConvertToChar() << endl; } ...

[Top]

Modifying a Product's Publications

The CATIPrdObjectPublisher interface also provides means to modify a product's publications as demonstrated by the ModifyPublication function.

This function takes three inputs:

1. The product whose publications are to be modified
2. A publication name to be removed. This publication must however be a subpublication.
3. A publication name to be published

and executes the following steps:

• retrieves the CATIPrdObjectPublisher interface

  static int ModifyPublications(CATIProduct *ipiProduct, const char *ipubToDelete, const char *isubPubToPublish) { int rc; CATBaseUnknown *pSubPubr = NULL; CATUnicodeString subPubName; CATIPrdObjectPublisher *piPublisher = NULL; if (NULL == ipiProduct || NULL == ipubToDelete || NULL == isubPubToPublish) return 0; // // Get CATIPrdObjectPublisher on product and subpublisher // rc = ipiProduct->QueryInterface(IID_CATIPrdObjectPublisher, (void **) &piPublisher); ...

• verifies that the publication to be deleted is a subpublication with GetDirectObject

  ... rc = piPublisher->GetDirectObject(ipubToDelete, pSubPubr, subPubName); if (2 != rc || NULL == pSubPubr) { cout << ipubToDelete << " is not a subpublication" << endl; return 0; } ...

• retrieves the CATIPrdObjectPublisher interface of the subpublisher

  ... CATIPrdObjectPublisher *piSubPublisher = NULL; rc = pSubPubr->QueryInterface(IID_CATIPrdObjectPublisher, (void **) &piSubPublisher); ...

• removes the publication at the product level with Unpublish

  ... // // Unpublish product publicattion // also unvaluate and unpublish corresponding subpublication // cout << endl; rc = piPublisher->Unpublish(ipubToDelete); cout << (rc ? ">> unpublished" : ">> failed to unpublish") << " publication "<< ipubToDelete << endl; ...

• also unvaluates and unpublishes it at the subpublication level with Unvaluate and Unpublish

  ... rc = piSubPublisher->Unvaluate(subPubName); cout << (rc ? ">> unvaluated" : ">> failed to unvaluate") << " subpublication " << subPubName << endl; rc = piSubPublisher->Unpublish(subPubName); cout << (rc ? ">> unpublished" : ">> failed to unpublish") << " subpublication " << subPubName << endl; ...

• fetches the subpublication of given name with GetFinalObject

  ... // // Create a new publication at the root product level and valuate it // cout << endl; CATBaseUnknown *pPubObject = NULL; pPubObject = piSubPublisher->GetFinalObject(isubPubToPublish); ...

• creates a new publication with the same name appended with "Prod" and using Publish

  ... CATUnicodeString newPubName(isubPubToPublish); newPubName += "Prod"; rc = piPublisher->Publish(newPubName); cout << (rc ? ">> created" : ">> failed to create") << " new publication " << newPubName << endl; ...

• valuates it with the subpublication object and using Valuate

  ... rc = piPublisher->Valuate(newPubName, pPubObject); cout << (rc ? ">> valuated" : ">> failed to valuate") << " publication " << newPubName << endl; ...

[Top]

Saving the Modified Document in a New File

...
        //----------------------------------------------------------------------
        // Save modified document
        //----------------------------------------------------------------------
        char docDir[CATMaxPathSize];
        char docName[CATMaxPathSize];
        CATSplitPath(inputDoc, docDir, docName);
        CATUnicodeString newDoc = CATUnicodeString(outputDir) + "New" + docName;
        rc = CATDocumentServices::SaveAs(*pDoc, newDoc);
...

[Top]

Closing the Session

Before terminating the use case, we need to remove the document from the session before closing it.

...
        //----------------------------------------------------------------------
        // Remove opened document from session
        //----------------------------------------------------------------------
        rc = CATDocumentServices::Remove (*pDoc);
...
        //----------------------------------------------------------------------
        //Delete the session 
        //----------------------------------------------------------------------
        rc = ::Delete_Session("CAA_PrdProp_Session");

[Top]

In Short

This use case has demonstrated how to retrieve a product publications and how to modify it:

• Load a Product document with CATDocumentServices::Open
• Retrieve the root product of the document with CATIDocRoots::GiveDocRoots
• Retrieve the components of the root product with CATIProduct::GetAllChildrenList
• Access to a component's publications with CATIPrdObjectPublisher::ListPublications, GetFinalObject, GetDirectObject, IsPublished and IsFinallyPublished
• Modify a component's publications with CATIPrdObjectPublisher::Publish, Valuate, Unpublish and Unvaluate
• Save a document in a new file with CATDocumentServices::SaveAs

[Top]

References

History

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