Creating a Document from a Memory Area in the Vault Server

3D PLM Enterprise Architecture	Data Access - Database	Creating a Document from a Memory Area in the Vault Server Copying a memory area to a newly created vault document
Use Case

Abstract

This article shows how to create a document in the vault server, copy a memory area into it, and save it.

What You Will Learn With This Use Case
The CAAEvcCreateDocFromMem 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 create a document in the vault server, copy a memory area into the vault document, and save it. It also shows how to open a vault session and a user session, how to get an URL from the vault document, and shows the two-step save operation.

The CAAEvcCreateDocFromMem Use Case

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

What Does CAAEvcCreateDocFromMem Do

CAAEvcCreateDocFromMem begins by opening a vault session and a user session. Then it creates a vault document, copies the contents of a memory area into it, retrieves the vault document URL, and finally save it using a two-step prepare/commit transaction.

On the standard output, the URL of the document it just created is displayed. You can use that URL as an input for the CAAEvcExtractDocIntoMem use case [1] or the CAAEvcExtractDocIntoFile use case [2].

How to Launch CAAEvcCreateDocFromMem

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

mkrun -c "CAAEvcCreateDocFromMem -v VaultAliasName"

where:

VaultAliasName is the alias name of the vault server that will contain the document.

Where to Find the CAAEvcCreateDocFromMem Code

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

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

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

Step-by-Step

There are eleven logical steps in CAAEvcCreateDocFromMem:

Creating the Vault Session
Creating a User Session
Creating a Document
Retrieving the Document URL
Retrieving the Default Block Size
Opening the Document in Write Mode
Copying a Memory Area into the Document
Closing the Document
Preparing the Transaction
Committing the Transaction
Ending the Session

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.

Creating a User Session

...
   ENOVIVaultUserSession * pUserSession = NULL;

   RC = pSession->getUserSession(s_InputVault, &pUserSession, VErr);
...

Once the vault session has be created, a user session must be initialized. A user session corresponds to the connection of a particular client to a given vault server. A user session is initialized using the getUserSession method of the ENOVIVaultSession interface whose arguments are:

s_InputVault is the alias name of the vault server that will contain the document passed as a parameter of the command that launches the use case
pUserSession is the initialized user session as a pointer to the ENOVIVaultUserSession interface
VErr is an ENOVIVaultError class instance passed as the last argument used if the method fails to convey information about the failure.

If several vault servers were needed to be accessed, a user session per vault server should be created.

Creating a Document

...
   ENOVIVaultDocument      * pDoc = NULL;

   // The following parameters are hard coded in this use case 
   // They could have been taken as input
   CATUnicodeString DocName      = "MyDoc";
   CATUnicodeString Description  = "sample document";
   CATUnicodeString MimeType     = "txt";
   CATUnicodeString OriginalName = "";
   CATUnicodeString OriginalPath = "";
   CATUnicodeString OriginalHost = "";
  
   RC = pUserSession->createDocument(DocName,
                                     Description,
                                     MimeType,
                                     OriginalName,
                                     OriginalPath,
                                     OriginalHost,
                                     &pDoc,
                                     VErr);
...

Now a document can be created from the user session. Note that this is just an empty shell to which contents will be associated later on. The parameters to pass to createDocument to create a vault document are:

DocName is the document's name
Description is the document's description. This is a short text that gives information about the document
MimeType is the extension that corresponds to the document's MIME (or content type)
OriginalName is the document's original name
OriginalPath is the document's original path name
OriginalHost is the document's original host
pDoc is the pointer to the document to create as 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.

Retrieving the Document URL

...
   SEQUENCE_octet    Url;
   RC = pDoc->getURL(Url);
...

The document's URL is an external link to the document. It contains all the necessary information to retrieve the document without having to know in which vault it is stored, on which machine, and so on.

Retrieving the Default Block Size

...
   const CATUnicodeString Pty("VaultClient_BlockSize");
   CATUnicodeString sSize(""); 

   RC = pSession->getProperty(Pty, sSize); 
...
   int BSize = 0; 
   sSize.ConvertToNum(&BSize);

...

The default block size is stored as a property. It can then be retrieved using the generic getProperty method on the ENOVIVaultSession interface

Opening the Document in Write Mode

...
   unsigned long DocSize      = 0      ; // The size of the document is unknown
   CATBoolean    WriteFullDoc = CATTrue; // The whole document will be written
      
   RC = pDoc->openWrite(DocSize, WriteFullDoc, VErr);
...

Opening a document in write mode allows you to modify, or create in this case, its contents. This also sets a write lock on the document ensuring that nobody else is modifying it at the same time. That doesn't prevent other people from reading the document but they will only see the last committed image until the current modifications are committed. The parameters to pass to openWrite are:

DocSize is the document's expected size after being modified, expressed in bytes. Setting it to 0 means that the expected size is unknown and will be determined by further operations
WriteFullDoc is a flag to indicate whether the whole document or only a part of it is to be written. It enables the vault server to internally optimize the document management behavior according to the application intent
VErr is an ENOVIVaultError class instance passed as the last argument used if the method fails to convey information about the failure.

Copying a Memory Area into the Document

...
   int iCLength = BSize*3;
   
   unsigned char * cContent = new unsigned char[iCLength];
   memset(cContent, 'A', iCLength);

   SEQUENCE_octet Buffer(iCLength, iCLength, cContent, TRUE);

   int iOffset = 0; // Offset from the beginning of the buffer

   for (int i = 1; i <= 3; i++)
   {
     RC = pDoc->writeBlock(Buffer, iOffset, BSize, VErr); 
...
     iOffset += BSize; 
   }
...

A memory area is now copied to the vault server document. In this use case, we have chosen to use the writeBlock method. We could have used the write method as well. In fact, in our example, the write method would have been more appropriate since the whole data we want to write into the document is contained into a single memory area. The writeBlock method is useful when data is split among several memory areas.

The parameter to pass to writeBlock are:

Buffer is the data to write
iOffset is the position into Buffer where the data to write start
Bsize is the size of the data to write
VErr is an ENOVIVaultError class instance passed as the last argument used if the method fails to convey information about the failure.

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.

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.

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.

Ending the Session

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

This ends and closes all the opened user sessions and closes the vault session.

In Short

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

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 to create a user session thanks to the getUserSession method that returns a pointer to ENOVIVaultUserSession
This pointer is used in turn to create the vault document as an empty shell using the createDocument method of ENOVIVaultUserSession. This document is handled as a pointer to the ENOVIVaultDocument interface. Its URL, that is an external link that enables the document to be found without any additional information, can be retrieved thanks to the getURL method of ENOVIVaultDocument
Then the vault document is opened in write mode, a memory area is copied into it, and it is closed using the openWrite, writeBlock, and close methods of ENOVIVaultDocument respectively
The document is then saved in the vault using a two-step transaction thanks to the prepare and commit methods of the ENOVIVaultSession interface
Finally, the vault and user session are closed using the environment is ENOVIVaultSessionFactory::endVaultSession static method of the ENOVIVaultSession interface.

References

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

History

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

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