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
public static HRESULT GetDocumentInSession( const CATUnicodeString& iStorageName,
CATDocument*& oOpenedDoc)
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
public static HRESULT GetDocumentLastSaveVersion(CATIDocId* iDocId,
CATUnicodeString& oVersion)
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
    public static HRESULT GetMinimalVersionToOpenDocument(CATIDocId* iDocId,
    CATUnicodeString& oVersion)
    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
    public static HRESULT IsKnownAsAPersistentType( const CATUnicodeString& iType)
    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
    public static HRESULT IsKnownAsAnAliasType( const CATUnicodeString& iAliasType)
    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
    public static HRESULT New( const CATUnicodeString& iType,
    CATDocument*& oNewDoc)
    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
    public static HRESULT OpenDocument( const CATUnicodeString& iStorageName,
    CATDocument*& oOpenedDoc,
    CATBoolean iReadOnly=FALSE)
    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
    public static HRESULT Remove(CATDocument& iDoc,
    short iEmptyClipbordIfNecessary=TRUE)
    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
    public static HRESULT Save(CATDocument& iDocument,
    CATBoolean iSavePointedIfNecessary= TRUE)
    Saves a given document in interactive mode.
    Role:To save a document two cases:
    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
    public static HRESULT SaveAs(CATDocument& iDocument,
    const CATUnicodeString& iStorageName,
    const CATUnicodeString& iFormat="",
    CATBoolean iSavePointedIfNecessary= TRUE)
    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
    public static HRESULT SaveAsNew(CATDocument& iDocument,
    const CATUnicodeString& iStorageName,
    CATBoolean iSaveRecursively=FALSE)
    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

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