Retrieving Information on a Document Without Loading it

3D PLM PPR Hub Open Gateway	File XPDM (PX1)	Retrieving Information on a Document Without Loading it How to retrieve its type, its last save path, and its last save version?
Use Case

Abstract

This article shows how to retrieve some information on a file document without loading it:

Its real type, meaning independently of its file extension,
Its last save path,
The CATIA version used for the last save,
Its preview file.

What You Will Learn With This Use Case
The CAAxPDMCheckDocType 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 use the CATIxPDMItem interface to retrieve information on a file document. Mainly through samples, you will learn the meaning and the limits of three methods of this interface:

GetItemType, to retrieve the real type of the document (CATPart, CATProduct).
GetLastSavePath, to retrieve the last file path.
GetLastSaveVersion, to retrieve the CATIA version used for the last save,
GeneratePreview, to create the preview file.

[Top]

The CAAxPDMCheckDocType Use Case

CAAxPDMCheckDocType is a use case of the CAAxPDMInterfaces.edu framework that illustrates CATxPDMInterfaces framework capabilities. Be careful, such as all use cases illustrating the CATxPDMInterfaces framework, the current one requires a PX1 licence.

[Top]

What Does CAAxPDMCheckDocType Do

CAAxPDMCheckDocType begins by opening a session, then retrieves and displays the information about a given file, without loading it, and finally closes the session.

Here are given the outputs of the use case for different files located in the following directory:

Windows	`InstallRootDirectory\CAAxPDMInterfaces.edu\InputData\DocCheck`
Unix	`InstallRootDirectory/CAAxPDMInterfaces.edu/InputData/DocCheck`

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

Before to detail the different cases, we specify where come from the outputs.

Read all information on file : the input argument, i.e the complete path of the file to analyze.

To reduce the output string, we have cut the middle of the complete file name (\...\) to keep only the most important string, the filename and its extension.

Type: the type returned by GetItemType
Save Path: the save path returned by GetLastSavePath
Version: the version returned by GetLastSaveVersion
Path Preview image (jpg): the filename of the preview file generated by GeneratePreview

Part1.CATPart

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\InputData\DocCheck\Part1.CATPart
Type:CATPart
Save Path:E:\users\bpe\ADELE\CXR7\bpePRJ7Base2\ObjectModelerBase.tst\FunctionTests\InputData\SampleDocEnv\Part1.CATPart
Version:
Path Preview image (jpg):E:\...\CAAxPDMInterfaces.edu\InputData\DocCheck\Part1.CATPart.jpg
...

Part1 is really a Part document, so the returned type is "CATPart". You can see that the file has been moved (or copied) from its last Save operation, because the Save path is different from the input file path. The version is not displayed because the document has been created before the V5R10 level. (The version can be found only for document created after the V5R10). The last output, is the filename of the preview file.

If you copy Part1.CATPart into Part1 (without extension), or into Part1.txt, or into Part1.xxx ( xxx is what you want), the returned type of GetItemType will be ever "CATPart".

Part3.CATPart

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\DocCheck\Part3.CATPart
Type:CATPart
Save Path:E:\users\jdp\AdeleIMOR15\omi15jdp1\CAAxPDMInterfaces.tst\FunctionTests\InputData\Part3.CATPart
Version:<Version>5</Version><Release>14</Release><ServicePack>2</ServicePack><HotFix>0</HotFix>
Path Preview image (jpg):E:\...\CAAxPDMInterfaces.edu\InputData\DocCheck\Part3.CATPart.jpg
...

Part3 is really a Part document, so the returned type is "CATPart". You can see that the file has been moved (or copied) from its last Save operation, because the Save path is different from the input file path. Part3 has been saved for the last time with the V5R14SP2 level. The generated preview file is the following:

Part1.CATProduct

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\DocCheck\Part1.CATProduct
Type:CATPart
Save Path:E:\users\bpe\ADELE\CXR7\bpePRJ7Base2\ObjectModelerBase.tst\FunctionTests\InputData\SampleDocEnv\Part1.CATPart
Version:
Path Preview image (jpg):E:\...\CAAxPDMInterfaces.edu\InputData\DocCheck\Part1.CATProduct.jpg
...

Despite the file extension of Part1 (.CATProduct), the file is not a Product document, but a Part document, so the returned type is "CATPart". The version is not displayed because the document has been created before the V5R10 level. The generated preview file is the same image as the Part1.CATPart.

Root.CATProduct

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\DocCheck\Root.CATProduct
Type:CATProduct
Save Path:E:\users\bpe\ADELE\CXR7\bpePRJ7Base2\ObjectModelerBase.tst\FunctionTests\InputData\SampleDocEnv\SP1.CATProduct
Version:
Path Preview image (jpg):E:\...\CAAxPDMInterfaces.edu\InputData\Root.CATProduct.jpg
...

Root is really a Product document. You can see on the output path that it has been renamed (outside CATIA). There is no displayed version because the document has been created before the V5R10 level.

The generated preview file is the following:

Cube.model

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\DocCheck\CUBE.model
Type:model
...

CUBE is a model document. The type returned by GetItemType is model. The file path and the version are not displayed because it is not a V5 document. There is no previous file.

MyTextDocCheck.txt

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\DocCheck\MyTextDocCheck.txt
Type:txt
...

The MyTextDocChec file is a txt file. The type returned by GetItemType is txt. The file path and the version are not displayed because it is not a V5 document. There is no previous file.

Attention, if MyTextDocChec was not a txt file, but an xls file for example, the returned type will by nevertheless txt. The GetItemType method returns the extension without check if the input file is not a V5 file ( CATPart, CATProduct, ....).

MyTextDocCheck.CATPart

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\DocCheck\MyTextDocCheck.CATPart
Type:NotAV5File
This file has a V5 extension but is not a V5 file
...

The MyTextDocCheck file is actually a txt file with a V5 extension. The GetItemType method returns the "NotAV5File" string. The file path and the version are not displayed because it is not a V5 document. There is no previous file.

NoExistingDoc.CATPart

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\DocCheck\NoExistingDoc.CATPart
ERROR: Impossible to open file E:\...\CAAxPDMInterfaces.edu\DocCheck\NoExistingDoc.CATPart.
...

The NoExistingDoc file does not exist. It is not possible to create an item for it. The GetItemFromFile method returns an error.

MyFileWithoutExtension

...
Read all information on file : E:\...\CAAxPDMInterfaces.edu\DocCheck\MyFileWithoutExtension
...

The MyFileWithoutExtension file is a file without extension, the GetItemFromFile does not return an error, because the file exists on disk. But GetItemType , GetLastSavePath and GetLastSaveVersion fail.

[Top]

How to Launch CAAxPDMCheckDocType

To launch CAAxPDMCheckDocType, you will need to set up the build time environment, then compile CAAxPDMCheckDocType along with its prerequisites, set up the run time environment, and then execute the use case [1]. To launch it, execute the following command:

mkrun -c "CAAxPDMCheckDocType FileName"

where Filename is the complete path of a file. You can use those specified in the What Does CAAxPDMCheckDocType Do section.

[Top]

Where to Find the CAAxPDMCheckDocType Code

The CAAxPDMCheckDocType use case is made of one single file, the CAAxPDMCheckDocTypeMain.cpp file, located in the CAAxPDMCheckDocType.m module of the CAAxPDMInterfaces.edu framework:

Windows	`InstallRootDirectory\CAAxPDMInterfaces.edu\CAAxPDMCheckDocType.m\`
Unix	`InstallRootDirectory/CAAxPDMInterfaces.edu/CAAxPDMCheckDocType.m/`

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

[Top]

Step-by-Step

There are six logical steps in CAAxPDMCheckDocType:

Prolog
Retrieving a CATIxPDMItem Interface Pointer
Retrieving the Document Type
Retrieving the Last Save Path
Retrieving the Version of the Last Save
Generating the Previous File
Epilog

[Top]

Prolog

...
HRESULT rc = S_OK;
char * pSessionName = "CAA_Sample_Session";
CATSession *pSession = NULL;
rc = ::Create_Session(pSessionName,pSession);
CATUnicodeString filename  = argv[1] ;
...

CAAxPDMCheckDocType begins by creating a session and retrieving from the command line the file path to analyze. filename must be a complete path, in other words an absolute path.

[Top]

Retrieving a CATIxPDMItem Interface Pointer

...
CATIxPDMItem_var pIxPDMItem;
rc = CATxPDMFileServices::GetItemFromFile(filename,pIxPDMItem);
...

GetItemFromFile is a static method of the CATxPDMFileServices class. It creates, or retrieves in session, an "item" from a given file without uselessly loading it. This item is represented by the CATIxPDMItem interface.

pIxPDMItem is a smart pointer on the item representing filename, the input file name.

Finally, such as all methods of the CATxPDMFileServices class, the GetItemFromFile method returns a CATError class instance in case of failure. You retrieve this error thanks to CATGetLastError, a global function [2]. You have an illustration, with the NoExistingDoc case in the What Does CAAxPDMCheckDocType Do section.

...
if (FAILED(rc))
{
      CATError * pError = CATError::CATGetLastError(rc);
      if ( NULL != pError )
      {
         CATUnicodeString ErrorMessage = pError->GetNLSMessage() ;
...

[Top]

Retrieving the Document Type

...
CATUnicodeString LocalDocType;
if (SUCCEEDED(pIxPDMItem->GetItemType(LocalDocType)))
{
   if (LocalDocType=="NotAV5File")
   {
     ....
   }
...

Once you have an item of the input file, an item represented by pIxPDMItem, you can retrieve the type of the input file. LocalDocType, the file type, is the output argument of the GetItemType method. Its specifications are the following:

The file has a V5 file extension
- It is a right V5 file: the real V5 file extension is returned
  - Root.CATProduct : (LocalDocType=CATProduct)-It is really a Product document
  - Part1.CATPart : (LocalDocType=CATPart)-It is really a Part document
  - Part1.CATProduct: (LocalDocType=CATPart)-It is actually a Part document.
- It is a not a right V5 file: the "NotAV5File" string is returned
  - For MyTextDocCheck.CATPart - LocalDocType=NotAV5File
The file does not have a V5 file extension
- It is a right V5 file: the real V5 file extension is returned
  - For Part1.txt (LocalDocType=CATPart)-It is really a Part document
- It is not a V5 file: the file extension without check
  - For Cube.model (LocalDocType=model)
  - For MyTextDocCheck.txt (LocalDocType=txt)
The file is without an extension
- It is a right V5 file: the real V5 file extension is returned
  - For Part1 : (LocalDocType=CATPart)-It is really a Part document
- It is not a V5 file: error
  - For MyFileWithoutExtension, GetItemType returns E_FAIL

[Top]

Retrieving the Last Save Path

...
CATUnicodeString SavePath;
if (SUCCEEDED(pIxPDMItem->GetLastSavePath(SavePath)))
...

The GetLastSavePath method returns the complete file path used during the last Save operation. This method is successful only for V5 document.

[Top]

Retrieving the Version of the Last Save

...
CATUnicodeString SaveVersion;
if (SUCCEEDED(pIxPDMItem->GetLastSaveVersion(SaveVersion)))
...

The none NLS string returned by the GetLastSaveVersion method of the CATIxPDMItem interface gives you the CATIA level when the document has been saved for the last time. This string is the concatenation of the following four sub-strings, and in this order:

Sub-string Syntax	Meaning	Comments
`<Version>X</Version>`	The version number
`<Release>X</Release>`	The release number
`<ServicePack>X</ServicePack>`	The service pack number	if X is equal to zero it is a GA level
`<HotFix>X</HotFix>`	The hot fix number	if X is equal to zero it is not an Hot Fix

These information can be retrieved only for document created from and after the V5R10, except for the Hot fix number which it is only available for document created from and after V5R14.

[Top]

Generating the Previous File

...
CATUnicodeString PathPreviewImage;
CATUnicodeString FormatPreviewImage="jpg" ;
if (SUCCEEDED(pIxPDMItem->GeneratePreview(FormatPreviewImage, PathPreviewImage)))
...

The GeneratePreview method generates a file containing the preview of the V5 document. The first argument is the format of the image ( jpg for example), and the second one is the file name. The nomenclature is the following : the name of the file + Its V5 extension. See the different samples in the What Does CAAxPDMCheckDocType Do section.

[Top]

Epilog

The session is closed using the global function named Delete_Session.

...
rc = ::Delete_Session(pSessionName);
...

pSessionName is the name of the session declared and used in the Prolog section.

[Top]

In Short

You have learned that without loading a file in session you can check that it is a real V5 file name, retrieve its last save path, retrieve the CATIA version when it has been saved last time, and generate its previous file.

[Top]

References

[1]	Building and Launching a CAA V5 Use Case
[2]	Managing Errors Using HRESULT
[Top]

History

Version: 1 [Jan 2005]	Document created
[Top]

3D PLM PPR Hub Open Gateway

File XPDM (PX1)