Lifecycle Applications

Document Management

Creating and Dealing with Document Objects

Programming basic methods in CATIEnovDDManager
Use Case

Abstract

This article shows how to use functionalities provided by the interface CATIEnovDDManager in ENOVInterfaces framework.

What You Will Learn With This Use Case

This use case is intended to show you how to use basic methods from CATIEnovDDManager defined in ENOVInterfaces framework. In this use case you will learn how to create document, create new revision, retrieving documents, set/get preferred revision, etc., step by step.

[Top]

The CAADDManagerFunctions Use Case

CAADDManagerFunctions is a use case of the CAAENOVInterfaces.edu framework that illustrates the usages of CATIEnovDDManager interface.

[Top]

What Does CAADDManagerFunctions Do

CAADDDManagerFunctions begins by creating a document master and document revision, then uses other functionalities provided by CATIEnovDDManager to create a second document Revision, an iteration, a format, and a document file. It also calls methods to retrieve and delete these objects created under the document structure.

[Top]

How to Launch CAADDManagerFunctions

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

Launch the use case by executing the following command: 

mkrun -c "CAADDManagerFunctions"

[Top]

Where to Find the CAADDManagerFunctions Code

The CAADDManagerFunctions use case is made of one class in a single file located in the CAADDManagerFunctions.m module of the CAAENOVInterfaces.edu framework:

Windows InstallRootDirectory\CAAENOVInterfaces.edu\CAADDManagerFunctions.m\
Unix InstallRootDirectory/CAAENOVInterfaces.edu/CAADDManagerFunctions.m/

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

[Top]

Step-by-Step

There are totally 19 steps in the CAADDManagerFunctions use case:

  1. Creating a Login Session
  2. Retrieving a CATIEnovDDManager Interface Handler
  3. Creating a Document
  4. Finding documents
  5. Retrieving the Last Document Revision under the Master
  6. Creating a New Revision
  7. Retrieving the Preferred Revision
  8. Deleting a Revision
  9. Creating an Iteration
  10. Retrieving the Iteration Count under a Revision
  11. Retrieving Preferred Iteration
  12. Creating a Format
  13. Creating Another Format with a Sub_mimetype
  14. Retrieving Format Count of an Iteration
  15. Retrieving All the Formats under an Iteration
  16. Creating a File
  17. Deleting a Format
  18. Deleting an Iteration
  19. Closing the Session

[Top]

Creating a Login Session

...
//--- Get Session
  CATIVpmLoginSession_var spSession = NULL_var;
  VPMSession* piSess_handle = VPMSession::OpenSession();
  if (piSess_handle!=NULL)
    rc =  piSess_handle->CreateLoginSession("", "", "", 0, spSession);
  if(rc != S_OK || spSession==NULL_var)
   return 1;

The first step is to create a login session as in the above codes.

[Top]

Retrieving a CATIEnovDDManager Interface Handler

//--- Get a DDManger
  CATIEnovDDManager_var spDDMgr = GetRootDesktop();
  if ( spDDMgr == NULL_var ) return 2;
  cout << "Got DDManager successfully." << endl;

The above code retrieves the CATIEnovDDManager.

[Top]

Creating a Document

1. First initialize some attributes before call the createDocument.

//--- Initialize class field and keywords before we create a document master
  CATListOfCATUnicodeString Doc_classfield;
  Doc_classfield.Append(CATUnicodeString("Name"));
  CATListOfCATUnicodeString Doc_keywords;
  Doc_keywords.Append(CATUnicodeString("ENOVIA"));

2. Secondly call CreateDocument.

//--- Create a DocumentMaster (It also creates a default Revision)
  CATIAVPMDocumentMaster  * piDocMaster = NULL;
  rc = spDDMgr->CreateDocument( "CAADDManager_DOC_ID",
                                "Doc_title",
                                "Doc_desc",
                                "Doc_type",
                                Doc_classfield,
                                Doc_keywords,
                                piDocMaster );
  if ( !SUCCEEDED(rc) || piDocMaster==NULL )
    return 3;
  cout << "Created Document successfully." << endl;

Calls CreateDocument() from the CATIEnovDDManager interface to create a document. In this method the input arguments are:

"CAADDManager_DOC_ID" Document ID
"Doc_title" Document name (title)
"Doc_desc" Document description
"Doc_type" Document type
Doc_classfield Document classification field
Doc_keywords Document keywords
piDocMaster Resulted document master

[Top]

Finding Documents

//--- Call FindDocument()
  CATLISTV(CATIAVPMDocumentMaster_var) aDocMasterlist = NULL;
  CATListOfCATUnicodeString searchKey;
  searchKey.Append(CATUnicodeString("ENOVIA"));
  rc = spDDMgr->FindDocument( "CAADDManager*",   // V_ID
                              "",                // Title
                              "",                // Description
                              "",                // Type
                              searchKey,         // KeyWords
                              "",                // User
                              "",                // Organization
                              aDocMasterlist );
  if ( !SUCCEEDED(rc) )
    return 4;
  cout << "Find Document successfully." << endl;

This call is to find all the documents whose ID match the pattern "CAADDManager*" from database. This method can also be used for searching for documents with any combinations of keys of document fields.

[Top]

Retrieving the Last Document Revision under the Master

//--- Get the default Revision as a ObjectVersion before creating a new one
  CATIAVPMObjectVersion *piOldRevision=NULL;
  rc = piDocMaster->get_LastVersion(piOldRevision);
  if ( !SUCCEEDED(rc) || piOldRevision==NULL )
    return 5;
  cout << "Get default revision successfully." << endl;

This call uses the master object to retrieve its latest revision.

[Top]

Creating a new Revision

//--- Create a new Revision
  CATIAVPMObjectVersion * piNewRev=NULL;
  rc = spDDMgr->CreateDocRev( piOldRevision, piNewRev );
  if ( !SUCCEEDED(rc) || piNewRev==NULL )
    return 6;
  cout << "Created a new Revision successfully." << endl;

Creating a new revision needs an old revision to clone from. In the above call, the last revision piOldRevision we retrieved in the last step is used to clone from.

[Top]

Retrieving the Preferred Revision

//--- Get Preferred Revision
  CATIVpmFactoryObject_var spMasterFactObj(piDocMaster);
  CATIAVPMObjectVersion * piPrefRev=NULL;
  if ( !!spMasterFactObj )
    rc = spDDMgr->get_PreferredRevision(spMasterFactObj, piPrefRev);
  if ( !SUCCEEDED(rc) || piPrefRev==NULL )
    return 7;
  cout << "Got preferred Revision successfully." << endl;

This call is to retrieve the preferred revision. Every time a new revision is created, it is set to be the preferred. User can also set any other revision to be preferred.

[Top]

Deleting a Revision

1. First must get the UUID of the revision that to be deleted.

//--- Get Revision UUID before deleting it
  CORBAAny iRevUuid;
  CATILinkableObject_var spRevlinkObject(piNewRev);
  SEQUENCE(octet) SeqOct = spRevlinkObject->GetName_B(CATSafestName);
  iRevUuid << SeqOct;

2. Call DeleteRevision() method.

//--- Delete a Revision
  rc = spDDMgr->DeleteRevision( iRevUuid );
  if ( !SUCCEEDED(rc) )
    return 8;
  cout << "Delete a Revision successfully." << endl;

This call deletes the second revision we created in the step 7.

[Top]

Creating an Iteration

1. First must get the UUID of the revision that iteration will be attached to.

//--- Get Revision UUID before creating an Iteration under it
  CORBAAny iOldRevUuid;
  CATILinkableObject_var spOldRevlinkObject(piOldRevision);
  SEQUENCE(octet) SeqOct1 = spOldRevlinkObject->GetName_B(CATSafestName);
  iOldRevUuid << SeqOct1;

2. Create the iteration

//--- Create an Iteration
  CATIVpmFactoryObject_var spIterationObj=NULL_var;
  rc = spDDMgr->CreateIteration(iOldRevUuid, spIterationObj);
  if ( !SUCCEEDED(rc) || spIterationObj==NULL_var )
    return 9;
  cout << "Created Iteration successfully." << endl;

[Top]

Retrieving the Iteration Count under a Revision

//--- Get Iteration count
  long nbIter=0;
  rc = spDDMgr->get_DocIterationCount(piOldRevision, nbIter);
  if ( !SUCCEEDED(rc) || nbIter==0 )
    return 10;
  cout << "Get Iteration count successfully." << endl;

This call will retrieve the number of iterations under the revision. Note, each revision has a dummy iteration.

[Top]

Retrieving Preferred Iteration

//--- Get Preferred Iteration
  CATIVpmFactoryObject_var spPrefIter=NULL_var;
  rc = spDDMgr->get_PreferredIteration(piOldRevision, spPrefIter);
  if ( !SUCCEEDED(rc) || spPrefIter==NULL_var )
    return 11;
  cout << "Get preferred Iteration successfully." << endl;

This call retrieve the preferred iteration of a revision.

[Top]

Creating a Format

1. First must get the UUID of the iteration that the format will be attached to.

//--- Get Iteration UUID before create formats under it
  CORBAAny oIterUuid;
  CATILinkableObject_var spIterlinkObject(spPrefIter);
  SEQUENCE(octet) IterSeqOct = spIterlinkObject->GetName_B(CATSafestName);
  oIterUuid << IterSeqOct;

2. Create the iteration

//--- Create first Format with no SubMimeType
  CATIVpmFactoryObject_var spFormatObj1=NULL_var;
  rc = spDDMgr->CreateFormat(oIterUuid,     // Iteration UUID
                             1,             // Control code (1, or 2)
                             "MimeType",    // MIMEType
                             FALSE,         // isURL
                             spFormatObj1);
  if (  !SUCCEEDED(rc) || spFormatObj1==NULL_var )
    return 13;
  cout << "Created first Format successfully." << endl;

The call to create a format has following argument list:

oIterUuid Iteration UUID
1 Control code (1 for system controlled document, 2 for user controlled)
"MimeType" Format Mimetype
FALSE Whether it is URL link or not
spFormatObj The resulted format

[Top]

Creating Another Format with a Sub_mimetype

//--- Create second Format with SubMimeType
  CATIVpmFactoryObject_var spFormatObj2=NULL_var;
  rc = spDDMgr->CreateFormat(oIterUuid,     // Iteration UUID
                             1,             // Control code (1, or 2)
                             "MimeType",    // MIMEType
                             "SubMimeType", // SubMIMEType
                             FALSE,         // isURL
                             spFormatObj2);
  if (  !SUCCEEDED(rc) || spFormatObj2==NULL_var )
    return 14;
  cout << "Created second Format successfully." << endl;

This call creates a format with sub_mimetype. The argument list is:

oIterUuid Iteration UUID
1 Control code (1 for system controlled document, 2 for user controlled)
"MimeType" Format Mime Type
"SubMimeType" Sub MimeType
FALSE Whether it is URL link or not
spFormatObj the resulted format

[Top]

Retrieving Format Count of an Iteration

//--- Get Format count
  long nbFormat=0;
  rc = spDDMgr->get_DocFormatCount(spPrefIter, nbFormat);
  if ( !SUCCEEDED(rc) || nbFormat==0 )
    return 15;
  cout << "Got format count successfully." << endl;

[Top]

Retrieving All the Formats under an Iteration

//--- Get all Formats
  CATLISTV(CATIVpmFactoryObject_var) aFormatList=NULL;
  rc = spDDMgr->get_DocFormats(spPrefIter, aFormatList);
  if ( !SUCCEEDED(rc) )
    return 16;
cout << "Got all the formats successfully." << endl;

[Top]

Creating a File

1. First must get the UUID of the format that the file will be attached to.

//--- Get Format UUID before creating a File under it
  CORBAAny oFormatUuid;
  CATILinkableObject_var spFormatlinkObject(spFormatObj1);
  SEQUENCE(octet) FormatSeqOct=spFormatlinkObject->GetName_B(CATSafestName);
  oFormatUuid << FormatSeqOct;

2. Create the file

//--- Create a File
  CATIVpmFactoryObject_var spFileObj=NULL_var;
  CORBAAny oVaultUuid;
  rc = spDDMgr->CreateFile(oFormatUuid,     // Format UUID
                           1,               // Control Code
                           oVaultUuid,      // VaultDocument UUID
                           "TestVault",     // Vault Name
                           "TestHost",      // File Host Name
                           "TestPath",      // File Path Name
                           "TestFileName",  // File Name
                           1,               // File Number (never used.)
                           spFileObj);
  if ( !SUCCEEDED(rc) || spFileObj==NULL_var )
    return 17;
cout << "Created a File successfully." << endl;

The call to create a file has following argument list:

oFormatUuid Format UUID
1 Control code (as in the format)
oVaultUuid Vault document UUID
"TestVault" Vault Name
"TestHost" Vault Host name
"TestPath" Vault path name
"TestFileName" File name
1 File number (never used)
spFileObj Resulted file object.

[Top]

Deleting a Format

//--- Delete a Format
  rc = spDDMgr->DeleteDocFormat(spFormatObj1);
  if ( !SUCCEEDED(rc) )
    return 18;
  cout << "Deleted a Format successfully." << endl;

This call deletes a format.

[Top]

Deleting an Iteration

//--- Delete an Iteration
  rc = spDDMgr->DeleteIteration(oIterUuid);
  if ( !SUCCEEDED(rc) )
    return 19;
  cout << "Deleted an Iteration successfully." << endl;

This call deletes an iteration.

[Top]

Closing the Session

//-----------------------------------------------------------------------------
// Close the VPM Session
//-----------------------------------------------------------------------------
  VPMSession::CloseSession();

Close the session using the CloseSession method of VPMSession. Then return a 0 value for a successful completion.

[Top]

In Short

This use case has illustrated how to create, retrieve, and delete document objects using methods in CATIEnovDDManager. Document is consisted of document master, revision, iteration, format, and file objects. The CATIEnovDDManager provides many useful methods to manipulate these objects.

[Top]

References

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

History

Version: 1 [Dec 2001] Document created
[Top]

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