3D PLM Enterprise Architecture

Data Access - File

Loading a Document

Working with existing documents
Use Case

Abstract

This article accompanies the CAAOmbLoadDoc use case. This use case explains how to load and save an existing document.

What You Will Learn With This Use Case

This use case is intended to help you make your first steps in working with documents. Basically, you will learn how to:

Before getting to the use case itself, it is important to get an understanding of what documents are. This is the goal of the next section. You can skip it and get directly to the use case if you are already familiar with these concepts.

[Top]

Some Important Concepts about Documents

The document concept allows users to gather objects which have something in common, to display them in a document window when in interactive mode, and to save them in a storage unit under a unique storage name for future retrieval.

Objects that are created and manipulated in similar ways are grouped in the same type of document. In CAA V5 interactive mode, to create and manipulate objects, you are provided with workshops. A document type is associated with one or more workshops. For example, when you create a Part document, you are provided with the Sketcher and PartDesign workshops by which you can create and manipulate objects named "parts". All these parts are then regrouped within one or more graphic windows (when in interactive mode) which symbolize a Part document.

CATIA documents are not only the places where related objects reside, they are also persistency units which can be exchanged between users.

[Top]

The CAAOmbLoadDoc Use Case

CAAOmbLoadDoc is a use case of the CAAObjectModelerBase.edu framework that illustrates ObjectModelerBase framework capabilities.

[Top]

What Does CAAOmbLoadDoc Do

The goal of CAAOmbLoadDoc is to load an existing document and to save and remove it from the session.

[Top]

How to Launch CAAOmbLoadDoc

To launch CAAOmbLoadDoc, you will need to set up the build time environment, then compile CAAOmbLoadDoc along with its prerequisites, set up the run time environment, and then execute the sample. This is fully described in the referenced article [1]. When launching the use case, you must pass the following arguments:

[Top]

Where to Find the CAAOmbLoadDoc Code

CAAOmbLoadDoc code is located in the CAAOmbLoadDoc.m use case module of the CAAObjectModelerBase.edu framework:

Windows InstallRootDirectory\CAAObjectModelerBase.edu\CAAOmbLoadDoc.m
Unix InstallRootDirectory/CAAObjectModelerBase.edu/CAAOmbLoadDoc.m

where InstallRootDirectory is the root directory of your CAA V5 installation. It is made of a unique source file named CAAOmbLoadDoc.cpp.

[Top]

Step-by-Step

There are two logical steps in CAAOmbLoadDoc:

  1. Loading an Existing Document
  2. Saving and Removing the Document

We will now comment each of those sections by looking at the code.

[Top]

Loading an Existing Document

  1. Create the session 
    char *sessionName = "CAA2_Sample_Session";
CATSession *pSession = NULL;
HRESULT rc = ::Create_Session(sessionName,
                              pSession);
if ((FAILED(rc)) || (NULL == pSession))
{
   cout << "ERROR in creating session" << endl << flush;
   return 1;
}

    Since this is a batch program, it is first necessary to open a new session before beginning to work with documents. Do not forget that this session needs to be deleted at the end of the program. Never open more than one session for any given batch program! To open a new session, use the Create_Session global function.

  2. Load the document 
    CATDocument *pDoc = NULL;
rc = CATDocumentServices::OpenDocument(argv[1], 
                               pDoc);
if (SUCCEEDED(rc) && (NULL != pDoc)) cout << "Document opened OK" << endl << flush;
else
{
   cout << "ERROR in opening an existing document" << endl << flush;
   return 2;
}

    Now that the session is opened, you can load an existing document using the OpenDocument static method of CATDocumentServices. This method requires, as a first parameter, the entire storage path name and document name of the existing document that we want to load into the session. In this use case, we enter this information as an argument to the program. The second parameter of the Open method returns a CATDocument pointer to the document it has loaded.

    Once the document exists in the session, you can work with objects within it, using specific interfaces external to the ObjectModelerBase framework.

[Top]

Saving and Removing the Document

  1. Save the document 
    rc = CATDocumentServices::Save (*pDoc);
if (SUCCEEDED(rc)) cout << "Document saved OK" << endl << flush;
else
{
   cout << "ERROR in saving document" << endl << flush;
   return 3;
}

    To save the new document under the same name, use the Save static method of CATDocumentServices. This method takes the CATDocument pointer to the document as the only parameter.

  2. Remove the document 
    rc = CATDocumentServices::Remove (*pDoc);
if (SUCCEEDED(rc)) cout << "Document removed OK" << endl << flush;
else
{
   cout << "ERROR in removing document" << endl << flush;
   return 4;
}

    <>If you ever needed to re-open the document during this same session, it would then be necessary to also remove it from the session after having saved it. Otherwise, you need not worry about it since deleting the session will automatically remove the document as well. To remove the document, you should use the Remove static method of CATDocumentServices.

  3. Delete the session 
    rc = ::Delete_Session(sessionName);
if (SUCCEEDED(rc)) cout << "Session deleted OK" << endl << flush;
else
{
   cout << "ERROR in deleting session" << endl << flush;
   return 5;
}

    Do not forget to delete the session at the end of the program using the Delete_Session global function!

[Top]

In Short

This use case has demonstrated how to:

[Top]

References

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

History

Version: 1 [Feb 2000] Document created
[Top]

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