Creating a Document from a File in the Vault Server

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

Abstract

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

What You Will Learn With This Use Case
The CAAEvcCreateDocFromFile 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 an existing file 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 CAAEvcCreateDocFromFile Use Case

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

What Does CAAEvcCreateDocFromFile Do

CAAEvcCreateDocFromFile begins by opening a vault session and a user session. Then it creates a vault document, copies the contents of a file 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 CAAEvcExtractDocIntoFile use case [1] or the CAAEvcExtractDocIntoMem use case [2].

How to Launch CAAEvcCreateDocFromFile

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

mkrun -c "CAAEvcCreateDocFromFile -f FileName -v VaultAliasName"

where:

FileName is the full path name of the file you want to import into the vault server
VaultAliasName is the alias name of the vault server that will contain the document.

Where to Find the CAAEvcCreateDocFromFile Code

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

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

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

Step-by-Step

There are ten logical steps in CAAEvcCreateDocFromFile:

Creating the Vault Session
Creating a User Session
Creating a Document
Retrieving the Document URL
Opening the Document in Write Mode
Copying a File 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.

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 File into the Document

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

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

The file contents is now copied to the vault server document. The parameter to pass to copyFromLocalFile are:

s_InputFile is the full path name of the file used to fill in the document. 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.

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 file 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 file is copied into it, and it is closed using the openWrite, copyFromLocalFile, 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 sessions are closed using the ENOVIVaultSessionFactory::endVaultSession static method of the ENOVIVaultSession interface.

References

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

History

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

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