Using CATPspServices and CATPspListServices

Equipment & Systems	Distributive Systems	Using CATPspservices and CATPspListServices How to use CATPspservices and CATPspListServices
Use Case

Abstract

This article discusses the CAAPspServices use case.

What You Will Learn With This Use Case
The CAAPspServices 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 and make use of CATPspServices and CATPspListServices functions.

[Top]

The CAAPspServices Use Case

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

[Top]

What Does CAAPspServices Do

The goal of CAAPspServices 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 CAAPspServices

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

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

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

where InstallRootDirectory is the root directory of your CAA V5 installation. It is made of two unique source files named CAAPspServicesMain.cpp and CAAPspServices.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 CAAPspServices:

Prolog
Initializing the Environment
Use of CATPspListServices::CreateCATIUnknownList()
Use of CATPspListServices::CreateCATICStringList()
Use of CATPspListServices::CreateCATIStringList()
Retrieving a list of PSP application names
Retrieving a list of domain names

[Top]

Prolog

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

[Top]

Initializing the Environment

The CAAPspServices 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]

Use of CATPspListServices::CreateCATIUnknownList() and Locate() functions

First get a physical object from the input document and then create CATIUnknownList interface implementation object by calling CATPspListServices::CreateCATIUnknownList() and then add a IUnknown pointer got from a physical object. In order to locate physical object just added to CATIUnknownList object, use CATPspListServices::Locate() as illustrated in the following code.

       rc = CATPspListServices::CreateCATIUnknownList(&piUnkList); // Create a list of unknowns

       if( SUCCEEDED (rc) )
       {
          cout << "CAAPspServices: "
               << "Succeeded in creating a CATIUnknownList interface implementation object" << endl;
       }
    
       if ( NULL != piPhysical )
          rc = piPhysical->QueryInterface (IID_IUnknown, (void **)&piUnknown);

       if (SUCCEEDED(rc) && (NULL != piUnknown) && (NULL != piUnkList))
       {
          rc = piUnkList->Add(0,piUnknown);

          if( SUCCEEDED( rc) )
          {
            int iLocation = 0;
            iLocation = CATPspListServices::Locate(piUnkList, piUnknown);  
                
            if( iLocation >= 0)
            {
               cout << "Found Physical object in the list at index" << iLocation<< endl;
            }
            else
            {
               cout << "Could not find the physical object"  << endl;
            }                                           
          }     
        }

[Top]

Use of CATPspListServices::CreateCATICStringList() and Locate() functions

First create CATICStringList interface implementation object by calling CATPspListServices::CreateCATICStringList() and then add a couple of c- strings to the CreateCATICStringList object. In order to locate character string just added to CATICStringList object, use CATPspListServices::Locate() as illustrated in the following code.

if( SUCCEEDED(CATPspListServices::CreateCATICStringList(&pLCStrNames)) && pLCStrNames )
{
  const char* cStrPiping = "Piping";
  const char* cStrTubing = "Tubing";
	
  // Adding strings to the list
	
  pLCStrNames->Add(0,cStrPiping);
  pLCStrNames->Add(0,cStrTubing);

  //
  // Calling CATPspListServices::Locate() function to locate "Piping"
  // 
  int iLocation = 0;
  iLocation = CATPspListServices::Locate( pLCStrNames, cStrPiping);
  cout << "Location index =" <<  iLocation << endl;
  if( iLocation >= 0)
  {
    cout << "Found the string" << endl;
  }
  else
  {
    cout << "Could not find the string"  << endl;
  }

Use of CATPspListServices::CreateCATIStringList() and Locate() functions

First create CATIStringList interface implementation object by calling CATPspListServices::CreateCATIStringList() and then add a couple of wide character strings to the CreateCATIStringList object. In order to locate one of the wide character string just added to CATIStringList object, use CATPspListServices::Locate() as illustrated in the following code.

     if ( SUCCEEDED(CATPspListServices::CreateCATICStringList(&pLCStrNames)) && pLCStrNames )
     {
       const char* cStrPiping = "Piping";
       const char* cStrTubing = "Tubing";
            
       // Adding strings to the list
            
       pLCStrNames->Add(0,cStrPiping);
       pLCStrNames->Add(0,cStrTubing);

       //
       // Calling CATPspListServices::Locate() function to locate "Piping"
       // 
       int iLocation = 0;
       iLocation = CATPspListServices::Locate( pLCStrNames, cStrPiping);
       cout << "Location index =" <<  iLocation << endl;
       if( iLocation >= 0)
       {
          cout << "Found the string" << endl;
       }
       else
       {
          cout << "Could not find the string"  << endl;
       }

Retrieving a list of PSP application names

Use CATPspServices::ListAllApplicationNames to get a list of application names

if( SUCCEEDED( CATPspServices::ListAllApplicationNames( &pLApplNames) )  )
{
  unsigned int LCStrSize = 0;
  int NumOfCStr = 0;
  if (pLApplNames) 
    HRESULT rc = pLApplNames->Count (&LCStrSize);
  NumOfCStr = LCStrSize;
  if (NumOfCStr)
  {
    cout << "Number of Applications = " << NumOfCStr <<endl;

Retrieving a list of all domain names

Use CATPspServices::ListAllDomainNamesto get a list of domain names

if( SUCCEEDED( CATPspServices::ListAllDomainNames( &pLDomainNames) ))
{
  unsigned int LCStrSize = 0;
  int NumOfCStr = 0;
  if (pLDomainNames) 
    HRESULT rc = pLDomainNames->Count (&LCStrSize);
  NumOfCStr = LCStrSize;
  if (NumOfCStr)
  {
    cout << "Number of Domains =" << NumOfCStr <<endl;

[Top]

In Short

This use case has demonstrated how to use the CATPspServices and CATPspListServices functions. Specifically, it has illustrated:

Obtaining the necessary Psp Interfaces
Use of CATPspListServices and CATPspServices functions

[Top]

References

[1]	Building and Launching a CAA V5 Use Case

History

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

Equipment & Systems

Distributive Systems