Initializing and Querying Plant Ship Applications

Equipment & Systems	Distributive Systems	Initializing and Querying Plant Ship Applications How to initialize and query an application and domain
Use Case

Abstract

This article discusses the CAAPspApplication use case.

What You Will Learn With This Use Case
The CAAPspApplication 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 activate a Plant Ship application, query its domain information, and get the name and location of the application resources.

[Top]

The CAAPspApplication Use Case

CAAPspApplication is a use case of the CAAPlantShipInterfaces.edu framework that illustrates CATPlantShipInterfaces framework capabilities.

[Top]

What Does CAAPspApplication Do

The goal of CAAPspApplication is to show you how to use the CATPlantShipInterfaces methods to query and obtain application and domain related information from the objects in a design document.

[Top]

How to Launch CAAPspApplication

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

CAAPspEduIn.CATProduct - the entire pathname, name and extension (.CATProduct) of the input drawing. Normally, it should be stored in the CNext/resources/graphic directory of the CAAPlantShipInterfaces.edu framework.

[Top]

Where to Find the CAAPspApplication Code

CAAPspApplication code is located in the CAAPspApplication.m use case module of the CAAPlantShipInterfaces.edu framework:

Windows	`InstallRootDirectory\CAAPlantShipInterfaces.edu\CAAPspApplication.m`
Unix	`InstallRootDirectory/CAAPlantShipInterfaces.edu/CAAPspApplication.m`

where InstallRootDirectory is the root directory of your CAA V5 installation. It is made of two unique source files named CAAPspApplicationMain.cpp and CAAPspApplication.cpp.

Additional prerequisite code is located in the CAAPspUtilities.m directory of the same framework.

[Top]

Step-by-Step

There are seven logical steps in CAAPspApplication:

Prolog
Initializing the Environment
Creating an Application Object and Obtaining the CATIPspApplication, CATIPspClass and CATIPspResource Interfaces
Initializing and Querying the Piping Design Application
Retrieving the Names of the Application, Domain, and Feature Catalogs
Retrieving the Class Names of the Application Start-Up Objects
Retrieving the Resource Names and Locations of the Application Resources

[Top]

Prolog

In this use case, we open an input document containing some Equipment and Piping Design objects.

[Top]

Initializing the Environment

The CAAPspApplication code is derived from the CAAPspBaseEnv base class. The base class contains functionality common to the other CAAPsp samples. Initializing the environment involves the following method:

CAAPspBaseEnv::CreateCATProductEnv

This method performs the following functions:

Creating a session, namely "Session DSA CAAPspBaseEnv CATProduct".
Loading the input document.
Initializing the document using the CATInit interface Init.
Retrieving the pointer to the root container object.

[Top]

Creating an Application Object and Obtaining the CATIPspApplication, CATIPspClass and CATIPspResource Interfaces

Create an application late type object and obtain the CATIPspApplication, CATIPspClass, CATIPspResource interface pointers from this application object. The Piping Design application (CATPiping) is used for this sample since the input document was created in the Piping Design workbench.

CATObject *piObj = new CATObject("CATPiping");
if ( NULL != piObj )
{
   //  Find CATIPspApplication interface 
   rc = piObj->QueryInterface(IID_CATIPspApplication,(void **)&piApplication);
   //  Find CATIPspClass interface
   rc = piObj->QueryInterface(IID_CATIPspClass,(void **)&piClass);
   //  Find CATIPspResource interface
   rc = piObj->QueryInterface(IID_CATIPspResource,(void **)&piResource);
   piObj->Release();
   piObj = NULL;
}

[Top]

Initializing and Querying the Piping Design Application

To initialize or activate an application means to make all its resources (catalogs, sample data, design rules, etc.) visible and available. These application resources are defined by the project administrator in a Project Resource Management file at project setup time. After the application is initialized, the CATIPspApplication interface is used to get the following information:

List of domain names that the Piping Design application belongs to
Main domain name of the application if it belongs to more than one domain
If the application is a 3D application

       //----------------------------------------------------------------------
       //  Activate the Piping application
       //----------------------------------------------------------------------
       if ( SUCCEEDED(piApplication->Initialization(piRootCont)) )
          cout << "Piping application initialized" << endl;

       //----------------------------------------------------------------------
       //  List domains supported by this application
       //----------------------------------------------------------------------
       CATICStringList *pListDomains = NULL;
       if ( SUCCEEDED(piApplication->ListDomains(&pListDomains)) &&
             NULL != pListDomains )
       {
          unsigned int size = 0; 
          if ( SUCCEEDED(pListDomains->Count(&size)) )
          {
             int NumOfDomains = (int)size;
             cout << "Number of domains for this application: " << NumOfDomains << endl;
             for (int j = 0; j < NumOfDomains; j++ )
             {
                char *DomainName = NULL;
                pListDomains->Item(j,&DomainName);
                if ( DomainName )
                {
                   cout << DomainName << endl;
                   delete [] DomainName; DomainName = NULL;
                }
             }
          }
          pListDomains->Release();  pListDomains = NULL;
       }

       //----------------------------------------------------------------------
       //  Is application a 3D application?
       //----------------------------------------------------------------------
       CATBoolean Is3D;
       rc = piApplication->Is3DApplication(&Is3D);
       if ( Is3D )
          cout << "Piping is a 3D application" << endl;

       //----------------------------------------------------------------------
       //  Get the application main domain name
       //----------------------------------------------------------------------
       if ( SUCCEEDED(piApplication->GetApplicationDomain(sDomain)) )
          cout << "Application's main domain: " << sDomain << endl;

[Top]

Retrieving the Names of the Application, Domain, and Feature Catalogs

The CATIPspDomainEnvironment interface is used to obtain the Feature catalog name, the User Defined Dictionary name and the 3D application name associated to the domain.

       //-------------------------------------------------------------------
       // Get the domain feature catalog name
       //-------------------------------------------------------------------
       CATUnicodeString FeatFileName;
       if ( SUCCEEDED(piDomainEnv->GetFeatFile(FeatFileName)) )
          cout << "Domain feature catalog: "
                 << FeatFileName.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       // Get the domain user defined feature catalog name
       //-------------------------------------------------------------------
       CATUnicodeString UserFeatFile;
       if ( SUCCEEDED(piDomainEnv->GetUserFeatFile(UserFeatFile)) )
          cout << "Domain user defined feature catalog: "
                 << UserFeatFile.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       // Get the 3D application name associated to this domain
       //-------------------------------------------------------------------
       CATString ApplName;
       if ( SUCCEEDED(piDomainEnv->Get3DApplication(ApplName)) )
          cout << "3D application name: " << ApplName << endl;

The CATIPspObject interface is used to obtain the application and domain name of any object in the document. The CATIPspObject interface pointer can be obtained from any physical object, function object, logical line or connector in the document. In this sample, we get the CATIPspObject interface pointer from a physical object.

    //-------------------------------------------------------------------------
    //  Get a physical object in the document and find its 
    //  CATIPspObject interface 
    //-------------------------------------------------------------------------
    CATIPspPhysical *piPhysical = GetAPhysicalObject();
    if ( NULL != piPhysical )
    {
       rc = piPhysical->QueryInterface(IID_CATIPspObject,(void**)&piObject);
       piPhysical->Release();
       piPhysical = NULL;
    }

    //-------------------------------------------------------------------------
    //  CATIPspObject methods
    //------------------------------------------------------------------------- 
    if ( NULL != piObject )
    {
       CATString sApplName;
       CATString sDomainName;
       piObject->GetApplicationName(sApplName);
       piObject->GetDomainName(sDomainName);

       piObject->Release();
       piObject = NULL;
    }

[Top]

Retrieving the Class Names of the Application Start-Up Objects

To retrieve the application Start-Up object classes, the CATIPspClass interface is used. Using the methods of this interface you can get a list of class names for Physical Parts, Function Parts, Connectors, Connections, and Logical Lines.

    if ( NULL != piClass )
    {
       CATICStringList *pList = NULL;
       unsigned int ListSize = 0; 

       if ( SUCCEEDED(piClass->ListStartUpPhysicalParts(&pList)) 
            && NULL != pList )
       {
          pList->Count(&ListSize);
          cout << "Number of physical part classes found: " << (int)ListSize << endl;
          pList->Release();  pList = NULL; ListSize = 0;
       }

       if ( SUCCEEDED(piClass->ListStartUpFunctionParts(&pList))
            && NULL != pList )
       {
          pList->Count(&ListSize);
          cout << "Number of function part classes found: " << (int)ListSize << endl;
          pList->Release();  pList = NULL; ListSize = 0;
       }

       if ( SUCCEEDED(piClass->ListStartUpConnectors(&pList))
            && NULL != pList )
       {
          pList->Count(&ListSize);
          cout << "Number of connector classes found: " << (int)ListSize << endl;
          pList->Release();  pList = NULL; ListSize = 0;
       }

       if ( SUCCEEDED(piClass->ListStartUpConnections(&pList))
            && NULL != pList )
       {
          pList->Count(&ListSize);
          cout << "Number of connection classes found: " << (int)ListSize << endl;
          pList->Release();  pList = NULL; ListSize = 0;
       }

       if ( SUCCEEDED(piClass->ListStartUpLogicalLines(&pList))
            && NULL != pList )
       {
          pList->Count(&ListSize);
          cout << "Number of logical line classes found: " << (int)ListSize << endl;
          pList->Release();  pList = NULL; ListSize = 0;
       }

       piClass->Release();
       piClass = NULL;
    }

[Top]

Retrieving the Resource Names and Locations of the Application Resources

The application resources are defined in a Project Resource Management xml file by the project administrator. The CATIPspResource interface is used to retrieve the resource name keyword, the directory paths, file names or data for these resources. Certain resources may not be available or defined for the active application. When the resource is not defined, the CATIPspResource method will fail to return the resource information.

    if ( NULL != piResource )
    {
       CATUnicodeString Blank = "";
       CATUnicodeString ResourceName;
       CATUnicodeString Path, Directory, FileName, Flag;
       CATUnicodeString DomainName = sDomain;

       //-------------------------------------------------------------------
       //  Get the line catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetLineCatalogPath(Blank,Path,ResourceName)) )
       {
          cout << "Line catalog resource name: " << ResourceName.ConvertToChar() << endl;
          //----------------------------------------------------------------
          //  Get a resource's path given a resource name
          //----------------------------------------------------------------
          if ( SUCCEEDED(piResource->GetResourcePath(ResourceName,Path)) )
             cout << "Line catalog path: " << Path.ConvertToChar() << endl;
       }

       //-------------------------------------------------------------------
       //  Get the zone catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetZoneCatalogPath(Blank,Path,ResourceName)) )
          cout << "Zone catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the ID schema directory
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetIDSchemaDir(DomainName,Directory,ResourceName)) )
          cout << "ID Schema directory: " << Directory.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the user dictionary file name
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetUserDictFileName(DomainName,FileName,ResourceName)) )
          cout << "User dictionary file name: " << FileName.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the ID Sequence number directory
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetIDSequenceNumberDir(Directory,ResourceName)) )
          cout << "ID Sequence number directory: " << Directory.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the discrete values directory
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetDiscreteValuesDir(Directory,ResourceName)) )
          cout << "Discrete values directory: " << Directory.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the standards catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetStandardsCatalogPath(Path,ResourceName)) )
          cout << "Standards catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the design rules catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetDesignRulesCatalogPath(Path,ResourceName)) )
          cout << "Design rules catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the Specification catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetSpecificationCatalogPath(Path,ResourceName)) )
          cout << "Specification catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the Insulation Specification catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetInsulationSpecCatalogPath(Path,ResourceName)) )
          cout << "Insulation Specification catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the part catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetPartCatalogPath(Path,ResourceName)) )
          cout << "Part catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the On/Off sheet catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetOffsheetCatalogPath(Path,ResourceName)) )
          cout << "On/Off sheet catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the resolved part catalog directory path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetResolvedPartCatalogDir(Directory,ResourceName)) )
          cout << "Resolved part catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the graphic representation filename
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetGraphicRepFileName(FileName,ResourceName)) )
          cout << "Graphic representation filename: " << FileName.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the file containing a list of valid classes for the
       //  active discipline
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetDisciplineClassesFileName(FileName,ResourceName)) )
          cout << "Discipline classes filename: " << FileName.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the connector attribute filename.
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetCntrAttrFileName(FileName,ResourceName)) )
          cout << "Connector attribute filename: " << FileName.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the report definition directory.
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetReportDefinitionDir(Directory,ResourceName)) )
          cout << "Report definition directory: " << Directory.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the annotation catalog path
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetAnnotationCatalogPath(Path,ResourceName)) )
          cout << "Annotation catalog path: " << Path.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the graphic names directory used in a schematics application.
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetGraphicNamesDir(Directory,ResourceName)) )
          cout << "Graphic names directory: " << Directory.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the flag that indicates if 3D application placement
       //  is schematic driven.
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetSchematicDrivenFlag(Flag,ResourceName)) )
       {
          cout << "Schematic driven flag resource name: " << ResourceName.ConvertToChar() << endl;
          //----------------------------------------------------------------
          //  Get a resource's value given a resource name
          //----------------------------------------------------------------
          if ( SUCCEEDED(piResource->GetResourceValue(ResourceName,Flag)) )
             cout << "Schematic driven flag: " << Flag.ConvertToChar() << endl;
       }

       //-------------------------------------------------------------------
       //  Get the flag that indicates if 3D application placement
       //  is function driven.
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetFunctionDrivenFlag(Flag)) )
          cout << "Function driven flag: " << Flag.ConvertToChar() << endl;

       //-------------------------------------------------------------------
       //  Get the growth factor value.
       //-------------------------------------------------------------------
       double Value;
       if ( SUCCEEDED(piResource->GetGrowthFactorValue(Value)) )
          cout << "Growth factor value: " << Value << endl;

       //-------------------------------------------------------------------
       //  Get the cable clearance value.
       //-------------------------------------------------------------------
       if ( SUCCEEDED(piResource->GetCableClearanceValue(Value)) )
          cout << "Cable clearance value: " << Value << endl;

       piResource->Release();
       piResource = NULL;
    }

[Top]

In Short

This use case has demonstrated how to use the Psp interfaces to initialize and query an application. Specifically, it has illustrated:

Obtaining the necessary Psp Interfaces
Activating an application
Querying for application and domain names
Querying for application object classes
Querying for application resources

[Top]

References

[1]	Building and Launching a CAA V5 Use Case

History

Version: 1 [March 2003]	Document created
[Top]

Equipment & Systems

Distributive Systems