All Frameworks Class Hierarchy This Framework Previous Next Indexes
ObjectModelerBase Class CATDocumentServices
CATDocumentServices
Usage: you must use this class as is. You should never derive it.
public class CATDocumentServices
Services to create, open and close documents.
Role:All methods of this class must be used to create, open or close a document when no
visualization is necessary. This is always the case in batch mode, but it is also possible
in interactive mode.
If you want to visualize the document, use the CATIIniInteractiveSession
interface. This last interface is defined in the InteractiveInterfaces Framework.
There are three methods for creating a (or several) new document(s) in the current session:
There are three methods for saving a document:
There is one method for closing a document:
There is one method for retrieving a document by its filename:
Life cycle of the document:
The AddRef/Release mechanism is not used:
All methods which return a CATDocument pointer have not performed an Addref on the pointer. So
there is no need to release it.
A CATDocument object created by New, Open(*), or NewFrom must
be removed from the session by the Remove method.
(*)Note that if the "open" is actually a "reopen", only one call to Remove must be done.
The Lock/Unlock mechanism is used
Look at this example:
1)Open a CATProduct which contains a CATPart
2)Open independently the same CATPart too
You should Remove the 2 documents, but when the CATProduct document will be closed,
the CATPart will be also. So a specific call to Remove for the independent CATPart
will end in an error.
So a multi-reference mechanism is necessary:
CATLockDocument and
CATUnLockDocument.
When do you lock a document ?
In batch mode, if you are not sure of the relation between each model opened,
lock the model after each open, and unlock it to remove it.
In interactive mode, if your class keeps a pointer on a document, lock it and
unlock it when the pointer is no longer needed.
- See also:
- CATDocument
Method Index
- o
GetDocumentInSession(CATUnicodeString&,CATDocument*&)
- Retrieves a document in session by its complete access name.
- o
GetDocumentLastSaveVersion(CATIDocId*,CATUnicodeString&)
- Retrieves the last save version of a document by its identifier.
- o
GetMinimalVersionToOpenDocument(CATIDocId*,CATUnicodeString&)
- Retrieves the minimal version to open a document by its identifier.
- o
HasDocumentEducationalFlag(CATIDocId*,int&)
- Check if a document has been saved with an educational licence.
- o
IsKnownAsAPersistentType(CATUnicodeString&)
- Test if a given document type is meant to be CATIA loadable.
- o
IsKnownAsAnAliasType(CATUnicodeString&)
- Test if a given document alias is meant to be CATIA creatable.
- o
New(CATUnicodeString&,CATDocument*&)
- Creates a document of a given type.
- o
NewFrom(CATLISTP(CATDocument)*,CATLISTV(CATUnicodeString)*&,CATLISTV(CATUnicodeString)*)
- Creates documents from existing files.
- o
NewFrom(CATLISTV(CATUnicodeString)*,CATLISTP(CATDocument)*,short)
- Creates documents from an existing file.
- o
OpenDocument(CATUnicodeString&,CATDocument*&,CATBoolean)
- Opens a given document.
- o
Remove(CATDocument&,short)
- Removes a document.
- o
Save(CATDocument&,CATBoolean)
- Saves a given document in interactive mode.
- o
SaveAs(CATDocument&,CATUnicodeString&,CATUnicodeString&,CATBoolean)
- Saves a document with a different name.
- o
SaveAsNew(CATDocument&,CATUnicodeString&,CATBoolean)
- Creates a new document from an existing one and saves it.
Methods
o GetDocumentInSession
-
Retrieves a document in session by its complete access name.
- Parameters:
-
- iStorageName
- The complete access name to the searched file (path + name of the file ).
See
CATDocument.StorageName for more information about the storage name.
- oOpenedDoc
- The found document.
o GetDocumentLastSaveVersion
-
Retrieves the last save version of a document by its identifier.
- Parameters:
-
- iDocId
- The identifier of the document.
- oVersion
- The last save version of the document (this information is only accessible for documents created from V5R10 and after.
(for example : < Version > 5/ < Version > < Release > 10/ < Release> < ServicePack> 1/< ServicePack > < BuildDate > mm-dd-yyyy.hh.mm/ < BuildDate >).
- Returns:
-
- S_OK: The version has been correctly retrieved,
- E_FAIL : The version could not be retrieved.
o GetMinimalVersionToOpenDocument
-
Retrieves the minimal version to open a document by its identifier.
- Parameters:
-
- iDocId
- The identifier of the document.
- oVersion
- The minimal version needed to open the document (this information is only accessible for documents created from V5R8 and after).
(for example : < Version > 5/ < Version > < Release > 10/ < Release>).
Due to service pack compatibility, no service pack number is specified.
Document can be opened on any service pack of the oVersion version.
- Returns:
-
- S_OK: The version has been correctly retrieved,
- E_FAIL : The version could not be retrieved.
o HasDocumentEducationalFlag
public static HRESULT HasDocumentEducationalFlag( | CATIDocId* | iDocId, |
| int& | iEducational) |
-
Check if a document has been saved with an educational licence.
- Parameters:
-
- iDocId
- The identifier of the document.
- iEducational
-
- 0: This is a standard document.
- 1: This document has been saved with an educational license.
- Returns:
-
- S_OK: The check has been successfully done.
- E_INVALIDARG: Null input iDocId.
- E_FAIL: Impossible to perform this check.
o IsKnownAsAPersistentType
-
Test if a given document type is meant to be CATIA loadable.
Role: Provide support to know if a given document type can be or not
loaded in session memory as a CATDocument
Being a loadable document requires CATIPersistent implementation on the given type
- Parameters:
-
- iType
- The string to define the kind of document to test.
it returns S_OK otherwise E_FAIL
o IsKnownAsAnAliasType
-
Test if a given document alias is meant to be CATIA creatable.
Role: Provide support to know if a given document alias can be or not
provided to be created in session memory as a CATDocument (See New)
Being a creatable document requires CATIDocAlias or CATIPersistent implementation on the given alias
- Parameters:
-
- iAliasType
- The string to define the kind of document to test.
it returns S_OK, this can be used as a creation alias
it returns E_FAIL, this is not.
o New
-
Creates a document of a given type.
Role: Creates and initializes data of a document of the given type. The
initialization is done thanks to the
CATInit.init method.
The document must be removed from the session before exiting or when it is
no longer needed. See explanations, at the top of this page, about the life
cycle of the document.
The name of the document is iType + Number + suffix. The suffix
is dedicated to iType such as .CATPart for the type Part.
As long as the document is not saved, the storage name (
CATDocument.StorageName ), is equal to the name.
- Parameters:
-
- iType
- The string to define the kind of document to create.
The string is the one which appears in the panel File/New.
- oNewDoc
- The document created.
o NewFrom
public static HRESULT NewFrom( | CATLISTP(CATDocument)* | oListOfDocuments, |
| const CATLISTV(CATUnicodeString)*& | iListOfPaths, |
| const CATLISTV(CATUnicodeString)* | iListOfNewFileNames | =NULL) |
-
Creates documents from existing files.
Role:This method allows you to create, in the current session, new documents
from existing ones. The links between the original documents are reported accordingly
between the new documents.
If an error occurs during the process of one document or if one the original documents
is already opened in session, a NULL pointer is put in oListOfDocuments and the method
continues and returns the corresponding error code. So the output list of new documents has
the same length as the input list of storage names.
- Parameters:
-
- oListOfDocuments
- The list of new documents.
The length of this output list is equal to the length of the input list but it can contain
NULL pointers if the method has failed for one of the input paths.
- iListOfPaths
- The list of complete access file names.
- iListOfNewFileNames
- The list of the new file names (optional).
NULL : default value, new names will be computed automatically for the new documents.
- Returns:
-
- S_OK: All documents are created.
- S_FALSE : One of the processed document was already loaded.
- E_FAIL : An error has occurred during for at least one of the documents.
o NewFrom
public static HRESULT NewFrom( | CATLISTV(CATUnicodeString)* | iListOfStorageName, |
| CATLISTP(CATDocument)* | oListOfDocuments, |
| short | iIndividualNewFrom | =TRUE) |
-
Creates documents from an existing file.
Role:This method allows you to create, in the current session, a new document
from an existing one. But if the original document is already opened in session, no new
document is generated.
The method processes separately each document. But if an error occurs during the process of
one document the method is stopped and returns the error code about the last processing. So the
output list of new document can be shorter than the input list of storage name.
- Parameters:
-
- iListOfStorageName
- The list of complete access file names.
- oListOfDocuments
- The list of new documents.
The length of this output list is equal to correct processed document.
- iIndividualNewFrom
- Useless
- Returns:
- The result of the last processed storage name:
- S_OK: All documents are created. The lenght of iListOfStorageName is equal to
oListOfDocument
- S_FALSE : The last processed document was already loaded. The lenght of oListOfDocument
is equal to correct document previously processed.
- E_FAIL : An error is occured during the last document processed. The lenght of
oListOfDocument is equal to correct document previously processed.
o OpenDocument
-
Opens a given document.
Role: If the file already exists in the session, it will not be re-loaded.
The document must be removed from the session before exiting or when it is no
longer needed. See explanations at the top of this page about the life
cycle of the document.
Note: This method does not allow opening .feat or .CATfct catalogs. It is not possible to access .feat
catalogs because they contain Dassault Systemes private data. To open a .CATfct catalog, see CATCatalogFactoryServices
(ObjectSpecsModeler framework).
- Parameters:
-
- iStorageName
- The complete access name of the file to open ( path + name of the file ).
See
CATDocument.StorageName for more information about the storage name.
- oOpenedDoc
- The opened document.
If the "open" is a "re-open", the pointer is not a new pointer. Do not remove
the pointer twice.
- iReadOnly
- FALSE: Default value, the document will be in read/write mode.
TRUE: The document is in read only mode.
In case of a re-opening, the mode of the document is defined by the first open.
- Returns:
- S_OK : The document was opened sucessfully.
S_FALSE : The document has already been loaded. The returned oOpenedDoc pointer
points to this document.
E_FAIL : The open operation failed.
o Remove
-
Removes a document.
Role:This method closes the document in the session.
CautionThis method is without effect if the document has been previously
locked. If you have locked your document, a call to this method is not necessary, the last
unlock closes it.
Read information at the top of the page about the life cycle of the document.
- Parameters:
-
- iDoc
- The document to remove.
- iEmptyClipbordIfNecessary
- TRUE : will remove all the links from clipboard to iDoc.
o Save
-
Saves a given document in interactive mode.
Role:To save a document two cases:
- In interactive mode, use this method or the method
CATIIniInteractiveSession::Save twice are equal
- In batch mode, use
SaveAs in using the current storage name of your document
CATDocument.StorageName
CATUnicodeString StorageNameDocument ;
StorageNameDocument = pDocument->StorageName();
::SaveAs(pDocument,StorageNameDocument);
- Parameters:
-
- iDocument
- The document to save.
- iSavePointedIfNecessary
- TRUE : default value, to save all documents referred to by iDocument if they have
been modified during the session.
FALSE: only iDocument will be saved.
- Returns:
- S_OK : The document was saved successfully.
S_FALSE : The document does not need to be saved.
E_FAIL : The document save operation failed.
o SaveAs
-
Saves a document with a different name.
Role:Save the document in the file specified by iStorageName.
Please note that no thumbnail for the document is generated or updated in batch mode.
- Parameters:
-
- iDocument
- The document to save.
- iStorageName
- The complete access name of the file.
The format of this argument is: path + name of the file.
It is the new storage name of the document.
See
CATDocument.StorageName to have more information about the storage name.
- iFormat
- To save the document with a specific format. (recognized by iDocument).
The string is the one which appears in the "Format" combo of the panel
File/Save or File/SaveAs.
- SavePointedIfNecessary
- TRUE : default value, to save all documents referred by iDocument if they
have been modified during the session.
FALSE: only iDocument will be saved.
o SaveAsNew
-
Creates a new document from an existing one and saves it.
Role:The new document is identical to the original except for its UUIDs.
The original document, iDocument, remains unchanged.
The new document does not exist in the session,it is just created in a file.
- Parameters:
-
- iDocument
- The original document from which the new document will be generated and saved
with different UUIDs.
- iStorageName
- The name under which the new document will be saved.
- iSaveRecursively
- Not used. FALSE by default.
This object is included in the file: CATDocumentServices.h
If needed, your Imakefile.mk should include the module: CATObjectModelerBase