Extracting a Document from the Vault Server to a File

3D PLM Enterprise Architecture	Data Access - Database	Extracting a Document from the Vault Server to a File Copying an existing vault document to a file
Use Case

Abstract

This article shows how to open a document in the vault server, and copy its contents into into a file.

What You Will Learn With This Use Case
The CAAEvcExtractDocIntoFile Use Case
Step-by-Step
In Short
References

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 using its URL, and copy it to a file. It also shows how to open a vault session.

[Top]

The CAAEvcExtractDocIntoFile Use Case

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

[Top]

What Does CAAEvcExtractDocIntoFile Do

CAAEvcExtractDocIntoFile 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 file.

[Top]

How to Launch CAAEvcExtractDocIntoFile

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

mkrun -c "CAAEvcExtractDocIntoFile -f FileName -u DocumentURL"

where:

FileName is the full path name of the file you want to copy the vault document to
DocumentURL is the Document URL

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

[Top]

Where to Find the CAAEvcExtractDocIntoFile Code

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

Windows	`InstallRootDirectory\CAAENOVaultClientCPP.edu\CAAEvcExtractDocIntoFile.m\`
Unix	`InstallRootDirectory/CAAENOVaultClientCPP.edu/CAAEvcExtractDocIntoFile.m/`

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

[Top]

Step-by-Step

There are eight logical steps in CAAEvcExtractDocIntoFile:

Creating the Vault Session
Retrieving the Document
Opening the Document in Read Mode
Copying the Document into a File
Closing the Document
Preparing the Transaction
Committing the Transaction
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 method of the ENOVIVaultSession interface connects to the vault server containing the required document and builds a vault document passed as an ENOVIVaultDocument interface pointer.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]

Copying the Document into a File

...
   CATBoolean DeleteAtClose = CATFalse; // We don't want the file to be deleted at close  

   RC = pDoc->copyToLocalFile(s_InputFile, DeleteAtClose, VErr);
...

The document contents is now copied to the file. The parameter to pass to copyToLocalFile are:

s_InputFile is the full path name of the file the document will be copied to. It is passed as the first argument when launching the use case
DeleteAtClose is a flag to indicate whether the vault server should delete the file when the document is closed. That can be useful when using temporary files
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 file.

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 to which the document URL is passed. This document is handled as a pointer to the ENOVIVaultDocument interface.
Then the vault document is opened in read mode, its contents is copied to a file, and it is closed using the openRead, copyToLocalFile, 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

[1]	Creating a Document from a File in the Vault Server
[2]	Creating a Document from a Memory Area in the Vault Server
[3]	Building and Launching a CAA V5 Use Case
[Top]

History

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

3D PLM Enterprise Architecture

Data Access - Database