Creating a New Document

3D PLM Enterprise Architecture	Data Access - File	Creating a New Document Working with standard-type documents
Use Case

Abstract

This article accompanies the CAAOmbNewDoc use case. This use case explains how to create and save a new document of a standard type.

What You Will Learn With This Use Case
Some Important Concepts about Documents
The CAAOmbNewDoc Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to help you make your first steps in working with documents. Its main intent is to show how to create a new document of a standard type and how to save it. In interactive mode, this is equivalent to creating a new document by selecting File/New. Through this use case, you will also learn some important concepts about the underlying operations involved in creating a new document. Basically, you will learn how to:

Create a new standard-type document
Retrieve its root container
Save and remove the document from the session

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 CATIA Version 5 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.

In batch code, there are some limitations:

Only use CATDocumentServices::SaveAs API
No thumbnail are generated or updated

[Top]

The CAAOmbNewDoc Use Case

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

[Top]

What Does CAAOmbNewDoc Do

The goal of CAAOmbNewDoc is to create a new document of a standard type, retrieve its root container and save and remove it from the session.

[Top]

How to Launch CAAOmbNewDoc

To launch CAAOmbNewDoc, you will need to set up the build time environment, then compile CAAOmbNewDoc 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:

Output.CATPart - entire pathname of the directory in which the document is to be stored. The document can be of any standard type, not necessarily CATPart.

[Top]

Where to Find the CAAOmbNewDoc Code

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

Windows	`InstallRootDirectory/CAAObjectModelerBase.edu/CAAOmbNewDoc.m`
Unix	`InstallRootDirectory\CAAObjectModelerBase.edu\CAAOmbNewDoc.m`

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

[Top]

Step-by-Step

There are three logical steps in CAAOmbNewDoc:

Creating a New Document
Retrieving the Document Root Container
Saving and Removing the Document

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

[Top]

Creating a New Document

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.

Create the new document

CATDocument* pDoc = NULL;
rc = CATDocumentServices::New("Part",
                              pDoc);
if (NULL != pDoc) cout << "New document created OK" << endl << flush;
else
{
   cout << "ERROR in creating New document" << endl << flush;
   return 2;
}

Now that the session is opened, you can create a new document using the Newstatic method of CATDocumentServices. This method creates a document and initializes it, allowing it to be loaded and stored and making it editable. In this use case, a pre-defined document type, "Part", is used as a document type. In interactive mode, this is the name that appears when performing a File/New operation. It is not the file extension, which, in this case, is "CATPart".

[Top]

Retrieving the Document Root Container

CATInit *piInitOnDoc = NULL;
rc = pDoc -> QueryInterface (IID_CATInit,
                             (void**) &piInitOnDoc);
if (FAILED(rc))
{
   cout << "ERROR in QueryInterface on CATInit for doc" << endl << flush;
   return 3;
}

const CATIdent idCATIContainer = "CATIContainer";
CATIContainer *piRootContainer = NULL;
piRootContainer = (CATIContainer*)
      piInitOnDoc -> GetRootContainer(idCATIContainer);
if (NULL == piRootContainer)
{
   cout << "ERROR in GetRootContainer" << endl << flush;
   return 4;
}

The document root container is retrieved using the CATInit::GetRootContainer method. The CATIContainer handle retrieved through GetRootContainer will be necessary whenever you want to create or manipulate objects in the document.

[Top]

Save and Removing the Document

Save the document

rc = CATDocumentServices::SaveAs (*pDoc, 
		                  argv[1]);
if (SUCCEEDED(rc)) cout << "Document saved OK" << endl << flush;
else
{
   cout << "ERROR in saving document" << endl << flush;
   return 5;
}

To save the new document, use the SaveAs static method of CATDocumentServices. This method takes the pointer to the document created by New as a first parameter, and the storage path name and document name under which the document is to be stored as a second parameter. In this use case, we pass the storage path name and document name as an argument to the program.

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 6;
}

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.

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 7;
}

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:

Create a standard-type document using the New static method of CATDocumentServices
Retrieve its root container using the GetRootContainer method of CATInit
Save and remove the document from the session using the SaveAs and Remove static methods of CATDocumentServices.

[Top]

References

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

History

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

3D PLM Enterprise Architecture

Data Access - File