3D PLM PPR Hub Open Gateway

CATIA - ENOVIA VPM V4 Interoperability

CATProduct Black Box Creation and Update

Creating and Updating a CATProduct Black Box from a existing Structure Exploded assembly in batch
Use Case

Abstract

This article discusses the CAAPsnUseCase4 use case. This use case explains how to create a CATProduct Black Box (Publication Exposed) from a Structure Exposed assembly already existing in the ENOVIA VPM V4 database and how to attach the CATProduct Black Box to the Root part of the assembly. The Black Box creation is performed in batch from Windows platform. This use case makes reference to the CAAPsnUECreate use case which explains how implement the CATIPDMUECreate user exit required to set the attributes for the parts and documents that will be created in ENOVIA vpm V4. It also contains an implementation of the CATIPDMUECreate and CATIPDMUnixNTMapping interfaces that are not explained in detail in this use case.

What You Will Learn With This Use Case

This use case is an example of how to use the SetPDMProperties, CATOpenConfiguredAssemblyInVPM, CATCreateVPMSession, CATLoadChildrenFromVPM, CATCompleteSessionFromVPM, CATSaveInVPMFromCATIA, CATCloseAssemblyInVPM and SaveAsInVPM methods.

[Top]

The CAAPsnUseCase4 Use Case

CAAPsnUseCase4 is a use case of the CAAPSNInteroperability.edu framework that illustrates the PSNInteroperability framework capabilities.

[Top]

What Does CAAPsnUseCase4 Do

The goal of CAAPsnUseCase4  is to create a CATProduct Black Box reflecting the complete structure of an Exploded mode assembly existing in ENOVIA vpm V4. The CATProduct is attached on the Root part of this assembly. The Root part is identified by its COID. The COID can be retrieved by executing the following Select statement against the VPM database. If you have previously executed CAAPsnUseCase1 which imports a file base assembly in ENOVIA vpm, You can use "Root assembly" as the Root part: 
select "$COID", s_part_number from VPMENV.PART_LIST where s_part_number = 'Root assembly'
Fig.1:   Sample assembly structure in ENOVIA vpm V4 

As a result of the execution of the use case, the following product structure is created in ENOVIA vpm V4

Fig.2:   Assembly structure after CATProduct Black Box creation  

NoteRunning this use case creates new data in ENOVIA vpm V4. Prior to running it, we advise you to check if similar document already exist in ENOVIA vpm as shown in the following panel:

[Top]

How to Launch CAAPsnUseCase4

To launch CAAPsnUseCase4, you will need to set up the build time environment, then compile CAAPsnUseCase4 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 "CAAPsnUseCase4 Coid hostName user pwd role server "

where

[Top]

Where to Find the CAAPsnUseCase4 Code

CAAPsnUseCase4 code is located in the CAAPsnUseCase4.m use case module of the CAAPSNInteroperability.edu framework:

Windows InstallRootDirectory/CAAPSNInteroperability.edu/CAAPsnUseCase4.m
Unix InstallRootDirectory\CAAPSNInteroperability.edu\CAAPsnUseCase4.m

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

[Top]

Step-by-Step

There are ten logical steps in CAAPsnUseCase4:

  1. Prolog
  2. Initializing batch communication with ENOVIA vpm V4
  3. Connecting to ENOVIA vpm V4
  4. Opening the Structure Exploded assembly in session
  5. Setting PDM properties on documents
  6. Saving the CATProduct Black Box in ENOVIA vpm V4
  7. Closing the Structure Exploded assembly
  8. Updating the CATProduct Black Box in ENOVIA vpm V4
  9. Closing communication with ENOVIA vpm V4
  10. Epilog

We will now comment each of those sections by looking at the code.

[Top]

Retrieving arguments

  1. Retrieves arguments 
    ...

CATUnicodeString Coid  = argv[1] ;

CATUnicodeString hostName  = argv[2] ;

char * pHostName = argv[2] ;

CATUnicodeString user  = argv[3] ;

CATUnicodeString pwd  = argv[4] ;

CATUnicodeString role  = argv[5] ;

CATUnicodeString server  = argv[6] ;

...

    CAAPsnUseCase4 begins by retrieving the arguments from the command line. Arguments are extracted in sequence: the full path of the root assembly document, the name of the Unix host, the ENOVIA vpm user and password used for database authentication, the role of this user and the option settings server name.

  2. Check environment 
    ...

char* pCAAPathToShell; 

CATLibStatus result = ::CATGetEnvValue("CV5VpmStart", &pCAAPathToShell);

if ( (CATLibError == result) || ( NULL == pCAAPathToShell) )

{

	cout << "CV5VpmStart environment variable is not set" << endl << flush;

	return 1;

}

cout << " The unix shell script is " << pCAAPathToShell << " on host " << hostName.ConvertToChar() << endl;

...

    Then the CV5VpmStart environment variable is checked. It contains the name of the Unix directory where the StartVPMBatchFromV5Batch.sh shell script is located.

  3. Creates the session 
    ...

char *sessionName = "CAA2_Sample_Session";

CATSession *pSession = NULL;

HRESULT rc = ::Create_Session(sessionName,

                              pSession);

if ((FAILED(rc)) || (NULL == pSession))

{

   cout << "ERROR in creating session" << endl << flush;

   return 1;

}

...

    Since this is a batch program, it is first necessary to open a new session before beginning to work with documents. Do not forget that this session needs to be deleted at the end of the program. To open a new session, use the Create_Session global function.

[Top]

Initializing batch communication with ENOVIA vpm V4

  1. Initializes communication with ENOVIA vpm V4 
    ...

rc = ::CATInitBatchOnHost( pHostName );

if (SUCCEEDED(rc)) cout << "Communication with ENOVIA vpm is set" << endl << flush;

else

{

   cout << "ERROR establishing communication with ENOVIA vpm" << endl << flush;

   //Always deleting session before exiting

   ::Delete_Session(pSessionName);

   return 1;

}

...

    Now that the session is opened, you can establish the communication channel with ENOVIA vpm using the CATInitBatchOnHost global method. This method establishes the connection with ENOVIA VPM V4 running on indicated Unix host. If there is no server running to which the application can connect to, a new ENOVIA VPM V4 server is launched on the dedicated Unix host.

[Top]

Connecting to ENOVIA vpm V4

  1. Connects to ENOVIA vpm V4 
    rc = ::CATConnectToVPM(server, user, pwd, role );

if (FAILED(rc))

{

   cout << "ERROR in server authentication" << endl << flush;

   //Always deleting session before exiting

   ::Delete_Session(pSessionName);

   return 1;

}

    Now that the connection to ENOVIA vpm is established, you can connect to the database using the CATConnectToVPM global method. This method establishes the database connection using user and password for authentication.

[Top]

Opening the Structure Exploded assembly in session

  1. Open the Root part in the ENOVIA vpm server memory 
    ...

//You are using the default VPM environment

CATUnicodeString CompId = "3030303030303030";

CATUnicodeString Env = "VPMENV  "; 

CATUnicodeString Table = "PART_LIST         ";

CATLISTV(CATUnicodeString)*  lvConfiguration  =  NULL; 

CATDocument *  pDocRoot  =  NULL;



//First, you must perform the assembly expand in VPM server memory

rc = ::CATOpenConfiguredAssemblyInVPM ( lvConfiguration,

                                       Coid,

                                       CompId,

                                       Env,

                                       Table,

                                       server);



if (SUCCEEDED(rc)) 

{                                

...

    Now that the session is opened, you can open the root part of the Structure Exploded assembly using the CATOpenConfiguredAssemblyInVPM global method. This method requires, as a first parameter, a list of Configuration Handler. In this use case, we do not use a configured assembly so the list is a NULL pointer. The second parameter is the Coid of the root part passed in argument of the use case. The Compid is set to "3030303030303030" which is the expected hexadecimal value for PART_LIST table rows.

  2. Create a CATProduct document to receive the assembly structure 
    ...

// New CATProduct Document to receive Root part

rc  =  ::CATCreateVPMSession ( pDocRoot, Coid, CompId, Env, Table, server );  

	

if (SUCCEEDED(rc) &&  (NULL  !=  pDocRoot)) 

{                                

...

    Now that the Structure Exploded is opened in the VPM server memory, you use the CATCreateVPMSession global method to attach this Structure Exploded to a new CATProduct type document. You reuse the same Coid, CompId, Env, Table.

  3. Load all the assembly children in the CATProduct document 
    ...

int nbLevel = 0;

rc = ::CATLoadChildrenFromVPM ( pDocRoot, nbLevel );

			

if (SUCCEEDED(rc)) 

{                               

...

    You then request to create in this new CATProduct document all the product structure children of the Structure Exploded assembly by using the CATLoadChildrenFromVPM global method. You set the nbLevel argument to zero to retrieve all the children.

  4. Load applicative data 
    ...

rc = ::CATCompleteSessionFromVPM  ( pDocRoot );

			

if (SUCCEEDED(rc)) 

{                               

...

    Finaly, you complete the CATProduct structure with all applicative data associated to the whole product struture by using the CATCompleteSessionFromVPM global method.

[Top]

Setting PDM properties on documents

  1. Reset of PDM properties on the CATProduct document 
    ...

CATLISTP(CATDocument)*  ToResetDocuments  =  NULL;  

CATLISTP(CATDocument)*  ResetDocuments  =  NULL;  

 

ToResetDocuments  =  new  CATLISTP(CATDocument);  

ToResetDocuments->Append( pDocRoot );  

	

rc  =  CATPDMServices::ResetPDMDocuments ( ToResetDocuments,  ResetDocuments );  

  

...

    You use the ResetPDMDocuments statis method of CATPDMServices to reset PDM properties of the CATProduct prior to set new properties.

  2. Setting new PDM properties on the CATProduct document 
    ...

rc = CATVPMServices::SetPDMProperties ( pDocRoot, 

			CATVPMServices::VPM1,

			CATVPMServices::PermanentBlackBox );

	

...

    The CATProduct document must be stored in Publication Exposed mode to become a CATProduct Black Box. You use the SetPDMProperties static method of CATVPMServices to set the CATVPMServices::PermanentBlackBox mode.

[Top]

Saving the CATProduct Black Box in ENOVIA vpm V4

  1. Save the CATProduct Black box document 
    ...

CATBoolean UnloadAfterSave = FALSE;

rc = ::CATSaveInVPMFromCATIA( pDocRoot, UnloadAfterSave );

if (FAILED(rc))

{

   cout << "ERROR in Saving document in Enovia vpm" << endl << flush;

}



rc = ::CATCommitVPM();

...

    You use the CATSaveInVPMFromCATIA global method to save the CATProduct Black Box document. You use the CATCommitVPM global method to commit the Save transaction in ENOVIA vpm.

[Top]

Closing the Structure Exploded assembly

  1. Closing the Structure Exploded assembly 
    ...

rc = ::CATCloseAssemblyInVPM();

...

    You use the CATCloseAssemblyInVPM global method to close the Structure Exploded assembly opened previously by using CATOpenConfiguredAssemblyInVPM .

[Top]

Updating the CATProduct Black Box in ENOVIA vpm V4

  1. Retrieving the Identification of the CATProduct Black box to update 
    ...

CATUnicodeString printableId;

CATBaseUnknown *  pDocUnknown = pDocRoot ;



rc = CATPDMServices::GetPrintableId ( pDocUnknown, printableId );



CATUnicodeString UpdateCoid = printableId.SubString(0,16);

CATUnicodeString UpdateCompid = printableId.SubString(16,16);

CATUnicodeString UpdateEnv = printableId.SubString(32,8);

CATUnicodeString UpdateTable = printableId.SubString(40,18);

...

    You use the GetPrintableId static method of CATPDMServices to retrieve the PDM identifier of the document comming from ENOVIA vpm V4.

  2. Updating the CATProduct Black box 
    ...

CATVPMServices::SaveAsMode iMod = CATVPMServices::KeepModified;

rc= CATVPMServices::SaveAsInVPM (  pDocRoot,

				UpdateCoid,

				UpdateCompid,

				UpdateEnv,

				UpdateTable,

				server,

				iMod); 



if (SUCCEEDED(rc))

{

	cout << "Commit transaction in ENOVIA vpm" << endl << flush;

	rc = ::CATCommitVPM();

	if (FAILED(rc))

	{

...

    The CATProduct Black Box initialy created in ENOVIA VPM V4 is updated by using the SaveAsInVPM static method of CATVPMServices. You use the CATCommitVPM global method to commit the Save transaction in ENOVIA vpm.

[Top]

Closing communication with ENOVIA vpm V4

  1. Disconnect from ENOVIA vpm V4 
    ...

rc = ::CATDisconnectFromVPM();

...

    You use the CATDisconnectFromVPM global method to disconnect from ENOVIA VPM V4 .

  2. Terminate the V5 session 
    rc = ::CATTerminateBatch();

    You use the CATTerminateBatch global method to terminate the V5 session.

[Top]

Deleting the session

  1. Deletes the session 
    rc = ::Delete_Session(sessionName);

    Do not forget to delete the session at the end of the program using the Delete_Session global function!

[Top]

In Short

This use case has demonstrated how to create a CATProduct Black Box in ENOVIA vpm V4.

[Top]

References

[1] Building and Launching a CAA V5 Use Case
[Top]

History

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

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