3D PLM Enterprise Architecture

What You Will Learn With This Use Case

This use case is intended to show you how to retrieve a document from a vault server and copy it to a memory area. It also shows how to open a vault session.

[Top]

The CAAEvcExtractDocIntoMem Use Case

CAAEvcExtractDocIntoMem is a use case of the CAAENOVaultClientCPP.edu framework that illustrates ENOVaultClientCPP framework capabilities.

[Top]

What Does CAAEvcExtractDocIntoMem Do

CAAEvcExtractDocIntoMem begins by opening a vault session. Then it retrieves a vault document from an URL taken as input and copies the contents of the document to a memory area.

[Top]

How to Launch CAAEvcExtractDocIntoMem 

To launch CAAEvcExtractDocIntoMem, you will need to set up the build time environment, then compile CAAEvcExtractDocIntoMem along with its prerequisites, set up the run time environment, and then execute the use case as follows: [3].

mkrun -c "CAAEvcExtractDocIntoMem -u DocumentURL"

where:

• DocumentURL is the Document URL

You can use as input the document URL generated by the CAAEvcCreateDocFromMem use case [1] or the CAAEvcCreateDocFromFile use case [2].

[Top]

Where to Find the CAAEvcExtractDocIntoMem Code

The CAAEvcExtractDocIntoMem use case is made of the single file CAAEvcExtractDocIntoMem.cpp located in the CAAEvcExtractDocIntoMem.m module of the CAAENOVaultClientCPP.edu framework:

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

[Top]

Step-by-Step

There are nine logical steps in CAAEvcExtractDocIntoMem:

1. Creating the Vault Session
2. Retrieving the Document
3. Opening the Document in Read Mode
4. Retrieving the Document Size
5. Copying the Document into a Memory Area
6. Closing the Document
7. Preparing the Transaction
8. Committing the Transaction
9. Ending the Session

[Top]

Creating the Vault Session

...
   ENOVIVaultError     VErr;
   CATBoolean          Master  = TRUE;

   // As the Vault session is opened as master, the following arguments are 
   // not taken into account
   CATUnicodeString    Marker("");
   CATUnicodeString    Host("");
   int                 Port    = 0;

   ENOVIVaultSession * pSession = NULL;

   RC = ENOVIVaultSessionFactory::getVaultSession(Marker, Host, Port, Master, &pSession, VErr);
...

The first thing to do is to create a vault session, thanks to the static getVaultSession method of the ENOVIVaultSessionFactory class. The vault component supports distributed transactions (i.e. several processes working in the context of the same transaction) but in this case only one of the sessions is a master one and is able to commit or rollback the transaction. As this use case is a stand alone program, the session must necessarily be opened as master. The useful arguments are:

• Master is set to TRUE to indicate a master session
• pSession is the initialized vault session as a pointer to the ENOVIVaultSession interface
• VErr is an ENOVIVaultError class instance passed as the last argument used if the method fails to convey information about the failure.

[Top]

Retrieving the Document

...
   ENOVIVaultDocument * pDoc = NULL;
   pSession->bindDocument(s_InputUrl, &pDoc, VErr); 
...

An URL contains all the necessary information enabling to retrieve a document. The bindDocument from the ENOVIVaultSession interface connects to the Vault server containing the required document and build an ENOVIVaultDocument object. The parameters to pass to bindDocument are:

• s_InputUrl is the URL of the document passed as a parameter of the command that launches the use case
• pDoc is the initialized document as a pointer to the ENOVIVaultDocument interface
• VErr is an ENOVIVaultError class instance passed as the last argument used if the method fails to convey information about the failure.

[Top]

Opening the Document in Read Mode

...
   RC = pDoc->openRead(VErr);
...

Before any read operation, the document must be opened in read mode.

[Top]

Retrieving the Document Size

...
   unsigned long iSize = 0; 

   RC = pDoc->getSize(iSize, VErr); 
...

The getSize methods will enable the memory area to be dimensioned.

[Top]

Copying the Document into a Memory Area

...
   SEQUENCE_octet Buffer;
   Buffer.length(iSize); 

   RC = pDoc->read(iSize, Buffer, VErr);
...

The document contents is now copied to Buffer variable. We could have used the readBlock method as well. This method would have been specially appropriate if the data were spread among several memory areas.

The parameter to pass to read are:

• iSize is the amount, in bytes, of data to read
• Buffer contains the data to read
• VErr is an ENOVIVaultError class instance passed as the last argument used if the method fails to convey information about the failure.

[Top]

Closing the Document

...
   RC = pDoc->close(VErr);
...

The document must always be closed. Pay a special attention to the error management. If any kind of error occurs after a document has been opened, make sure it is closed before exiting the method in which you handle the document.

[Top]

Preparing the Transaction

...
   RC = pSession->prepare(VErr);
...

The vault is designed to cooperate with other data servers. So it supports a two-phase commit. That means that the save operation has been split into two steps: prepare and commit. This applies to all the vault documents currently managed by all the user sessions of the vault session. When preparing and committing the transaction, a check is performed to determine whether documents are opened. If an opened document exists, it is considered as "in work" and to ensure that no document is saved in an inconsistent state, the whole save operation is aborted. 

When preparing the transaction, all the necessary checks and most of the save operations are performed, the objective being to make sure that nothing will prevent from committing.

[Top]

Committing the Transaction

...
   RC = pSession->commit(VErr);
...

Committing the transaction is a very light operation validating what has been done when preparing the transaction. Once committed, all the modifications done since the previous commit are saved and become visible to the other users.

As no document has been modified or created in this use case, it would be equivalent to use the rollback or abort methods of the ENOVIVaultSession interface.

[Top]

Ending the Session

...
   RC = ENOVIVaultSessionFactory::endVaultSession(pSession, VErr);
...

This ends and closes the vault session.

[Top]

In Short

This use case has demonstrated how to initialize the vault environment, retrieve a vault document and copy it into a memory area.

• The vault environment is initialized by creating a vault session using the ENOVIVaultSessionFactory::getVaultSession static method that returns a pointer to the ENOVIVaultSession interface
• This pointer is used in turn to retrieve a vault document using the bindDocument method of ENOVIVaultSession. This document is handled as a pointer to the ENOVIVaultDocument interface.
• Then the vault document is opened in read mode, its size is retrieved, its content is copied to a memory area, and it is closed using the openRead, getSize, read, and close methods of ENOVIVaultDocument respectively
• The transaction is then closed thanks to the prepare and commit methods of the ENOVIVaultSession interface
• Finally, the vault session is closed using the ENOVIVaultSessionFactory::endVaultSession static method of the ENOVIVaultSession interface.

[Top]

References

History

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