3D PLM Enterprise Architecture

What You Will Learn With This Use Case

The primary objective of this use case is to familiarize the user with the CATImmCAAServices public interface APIs meant for dealing with the Configuration Handler. The use case introduces the user with the following three APIs :

• The SetPRCConfigHandler API to apply the ConfigHandler on a PRC and Expand the assembly up to specified level.

• The GetPRCConfigHandler API to retrieve the current ConfigHandler applied on the PRC.

• The GetAllPRCConfigHandlers API to retrieve All the ConfigHandlers associated with the PRC.

[Top]

The CAAImmCAAServicesCHTestCmd Use Case

The CAAImmCAAServicesCHTestCmd  is a use case of the CAACATImmENOVIAProvider.edu framework that illustrates CATImmCAAServices interface capabilities.

[Top]

What Does the CAAImmCAAServicesCHTestCmd Use Case Do

The CAAImmCAAServicesCHTestCmd is a test command which seeks the associated Configuration Handler/s and Sets as well as Resets the Configuration Handler on the Root object existing in the current VPM Navigator window providing the liberty to expand the product assembly up to the specified level..

• The Input model shown below [Fig.1] represents PRC and the assembly beneath it in the VPMNav tree on which the CAAImmCAAServicesCHTestCmd command is to be run. The Use Case is illustrated with a Product assembly , but it works with other Data model, as well.

  Fig.1 Input Model

• Click on the icon to run the command CAAImmCAAServicesCHTestCmd included in the CAAImmIdAcqAgentTestCmd toolbar as shown below [Fig.2].

  Fig.2 Toolbar

• The use case retrieves the identifier name, its value and the root type of the Root object existing in the current VPM navigator window and displays this information in a notification window as shown below [Fig.3].

  Fig.3

• The user has the liberty to retrieve the Configuration Handler/s associated with the PRC, he/she can retrieve all the ConfigHandlers associated with PRC by pressing "Yes" button in the notification window as  [Fig.4] shown below or else only the current ConfigHandler can also be retrieved by pressing "No". 

  Fig.4

• As per the user selection, use case retrieves the ConfigHandler/s associated with the PRC and displays them in the notification window as shown below [Fig.5]. The figure below shows the list of All the ConfigHandlers associated with the PRC .

  Fig.5

• Once done with retrieving the associated ConfigHandleres next step is to either set the first ConfigHandler from the list of handlers on the PRC or Reset it. The use case hence asks the user to choose to Set/Reset the ConfigHandler to proceed ahead [Fig.6 ] .

  Fig.6

• If the users happens to Press "OK" , the first Confighandler gets applied on the PRC and the assembly gets expanded to the specified level otherwise the first handler gets removed from the PRC. The Fig.7 below shows the Output model expanded to level One after setting the ConfigHandler on the PRC and the notification window indicating the successful execution of the command.

  Fig.7 Output Model

• If the user chooses to go for current ConfigHandler by Pressing "No" button in the notify window [Fig.4] , use case retrieves only the current ConfigHandler applied on PRC and displays it in the notification window.

  Since this option has been provided to retrieve the Current ConfigHandler, the PRC must have an existing Handler applied on it for this command to work successfully. Otherwise a notification message pops up indicating PRC has no ConfigHandler applied on it currently, as shown below [Fig.8].

  Fig.8

[Top]

How to Launch the CAAImmCAAServicesCHTestCmd command

To launch CAAImmCAAServicesCHTestCmd , the user needs to set up the build time environment, then compile CAAImmCAAServicesCHTestCmd along with its prerequisites, set up the run time environment, and then execute the use case [1] in the following way:

• Run CNEXT on the command line.
• Connect to Enovia using the command on Enovia V5 Toolbar.
• Enter Login, Password and Enovia Server information and click OK to login.
• Open a PRC from the VPM Navigator window.
• Run the CAAImmCAAServicesCHTestCmd shown in Fig.2 available from VPM Navigator workbench. This command has been included in CAAImmIdAcqAgentTestCmd toolbar.
• To proceed further refer to the What does the use case do section explained above.

[Top]

Where to Find the CAAImmCAAServicesCHTestCmd Code

The test command is made up of a single class named CAAImmCAAServicesCHTestCmd located in the CAAImmCAAServicesCHTestCmd.m module of the CAACATImmENOVIAProvider.edu framework :

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

[Top]

Step-by-Step

The following are the main steps in CAAImmCAAServicesCHTestCmd use case :

1. Instantiate the CATImmCAAServices object
2. Get Current Root and its Identifiers
3. Get the Configuration Handler(s) associated with PRC

         3a. Get All the applied Configuration Handlers

         3b. Get Current Configuration Handler

4. Set/Reset the Configuration Handler
5. Release the CATImmCAAServices object

[Top]

Instantiate the CATImmCAAServices object

The CAAImmCAAServicesCHTestCmd command has been derived from CATCommand. The constructor of the command class has a call to the CAAImmCAAServicesCHTestCmd ::Initialise method which retrieves the current root object and its associated information and then seeks the Configuration Handler/s associated with that root object. Depending upon the user choice to Set/Reset the ConfigHandler on PRC the constructor makes  a call to the CAAImmCAAServicesCHTestCmd ::Activate method for further operation.

CAAImmCAAServicesCHTestCmd::CAAImmCAAServicesCHTestCmd(void* arg):CATCommand(NULL,"CAAServicesTestCmd")
{
  ...
  int a = Initialise();
  if ( a == 2 )
    Activate(NULL,NULL);
  ...  
 }

The CATImmCAAServices object is instantiated in the Initialise method as shown below.

int CAAImmCAAServicesCHTestCmd::Initialise()
{
  ...
  _ImmServiceObj = new CATImmCAAServices();
  ...

In addition some other private members of the type CATUnicodeString and CATListOfCATUnicodeString are defined which contain the information about the root identifiers and their names, configuration filters and their names.

[Top]

Get the Current Root and its Identifiers in the VPMNAV window

 The CATImmCAAServices::GetCurrentRootIdentifiers method retrieves the current Root Identifier from the current VPM Navigator window. This method retrieves the Identifier of the root object, its value and the root type.

  ...
  hr = _ImmServiceObj->GetCurrentRootIdentifiers(_oIdentifierNames,_oIdentifierValues,
     					         _oRootType);
  ...

On the failure of this method a failure message is displayed and the execution of the command ends. Whereas on success, the  identifier name of the PRC, its value and the root type is displayed in the notification dialog box [Fig.3].

[Top]

Get the Configuration Handler(s) associated with the PRC

Once the current root object identifier and the corresponding information is retrieved, the next step is to seek the Configuration Handler(s) associated with it. Since the use case provides the choice to the user to retrieve either All the ConfigHandlers or the Current ConfigHandlers associated with PRC. 

  ...
  CATUnicodeString type_message = CATMsgCatalog::BuildMessage("CAAImmCAAServicesCHTestCmd","ChooseConfigHandler");
  
  CATUnicodeString title = CATMsgCatalog::BuildMessage("CAAImmCAAServicesCHTestCmd", "title");
  CATDlgNotify* pRunDlg = new CATDlgNotify(CATApplicationFrame::GetFrame()->GetMainWindow (),
       				           "VPM_Identification8",CATDlgNfyInformation |
     					   CATDlgNfyYesNoCancel |CATDlgWndModal);
  int CHType = pRunDlg->DisplayBlocked(type_message, title);
  ...  

Depending upon the user selection and the return value (CHType) of the CATDlgNotify::DisplayBlocked method, use case makes a call to the either of GetAllPRCConfigHandlers or GetPRCConfigHandler  these two methods.

Get All the applied Configuration Handlers

Here a call to the CATImmCAAServices::GetAllPRCConfigHandlers retrieves the PRC name(_oIdentifierValues[1]) and the list of ConfigHandlers (_oCHdsValues) associated with it.

  ...
  if (CHType == 3)
  {
    hr = _ImmServiceObj->GetAllPRCConfigHandlers(_oIdentifierValues[1],_oCHdsValues);
    ...
  }
  ...

Get the Current Configuration Handler

A call to the CATImmCAAServices::GetPRCConfigHandler retrieves only the current ConfigHandler(_oCHdsValues[1]) applied on the PRC among the list of all the configuration handlers associated with it..

  else if(CHType == 4)
  {
    hr = _ImmServiceObj->GetPRCConfigHandler(_oIdentifierValues[1],_oCHdsValues[1]);
    ...
  }
 }

If any of the above two methods fails or no configuration handler is associated with the PRC is found then an appropriate failure message is displayed and the execution of the command ends. Whereas on success, the name/s of the configuration handler/s associated with the PRC get displayed.

[Top]

Set/Reset the Configuration Handler

If there are one or more configuration handlers associated with the PRC then the use case sets the first configuration handler from the list of available configuration handlers on the PRC. This is achieved through the CATImmCAAServices ::SetPRCConfigHandler API, as explained below.

CATStatusChangeRC CAAImmCAAServicesCHTestCmd::Activate(CATCommand*  iFromClient,
      						       CATNotification*  iNotification )
{  
   ...
   CATDlgNotify* pRunDlg = new CATDlgNotify(CATApplicationFrame::GetFrame()->GetMainWindow (),
     					    "VPM_Identification",CATDlgNfyOKCancel|CATDlgWndModal);
   int a = pRunDlg->DisplayBlocked(type_message, title);
   pRunDlg->RequestDelayedDestruction();
   pRunDlg = NULL;
  
   CATListOfCATUnicodeString CHdsValues;
   
   if( a == 2 )
      CHdsValues.Append("");
   else 
      CHdsValues.Append(_oCHdsValues[1]);
   
   int b = Set( _oIdentifierValues[1],CHdsValues[1]);
  ...
}

On the successful execution of the GetAllPRCConfigHandlers method, use case makes a call to the CAAImmCAAServicesCHTestCmd::Activate to proceed ahead with Setting/Resetting the ConfigHandler on PRC. 

A call to CAAImmCAAServicesCHTestCmd::Set function internally calls the CATImmCAAServices::SetPRCConfigHandler API. The API has been specifically designed to set or reset, as per the user selection, the ConfigHandler on the PRC and then to control the level of expansion of the Product assembly instead of expanding the whole assembly unnecessarily. 

int CAAImmCAAServicesCHTestCmd::Set(const CATUnicodeString& iPRCIdentifiersValue,
                                    CATUnicodeString& iCHdsValue)
{
  ...
  int iExpandLevel = 1;
  int iCheckFlag = 1;
  hr = _ImmServiceObj->SetPRCConfigHandler(iPRCIdentifiersValue,iCHdsValue,
      				           iExpandLevel,iCheckFlag);
  ...
}

Here the third argument (iExpandLevel) to specify the expand level has been set to One .

This API also allows the user to check/confirm if the applied Configuration Handler has been actually attached to the PRC or not. The fourth argument (iCheckFlag ) serves this purpose if set to One .If the flag is set to one, the SetPRCConfigHandler method internally makes a call to the CATImmCAAServices::GetPRCConfigHandler API to confirm the same.

[Top]

Release the CATImmCAAServices object

It is recommended to deallocate the CATImmCAAServices object at the end of the command, or when its use is finished in the following way,

...
   if(_ImmServiceObj)
   {
      delete _ImmServiceObj;
      _ImmServiceObj=NULL;
   }	
...

[Top]

In Short

This CAAImmCAAServicesCHTestCmd use case mainly focuses on CATImmCAAServices interface APIs designed to work with the Configuration Handler.

The use case demonstrates how to retrieve the Configuration Handlers associated with the current root object in the VPM Navigator window. Whereas it provides the liberty to the user to retrieve All or only the Current ConfigHandler/s associated with the PRC.

It familiarizes the user with the API meant to Set/Reset the ConfigHandler on the PRC and allows the user to restrict the expansion of the product assembly up to the specified Expand level.

[Top]

References

History

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