3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

This use case is intended to show you how to create length and magnitude type parameters, create a formula using these parameters, retrieve and display a parameter value, modify a parameter value and check how the formula result is affected.

[Top]

The CAALifGettingStarted Use Case

CAALifGettingStarted is a use case of the CAALiteralFeatures.edu framework that illustrates KnowledgeInterfaces framework capabilities.

[Top]

What Does CAALifGettingStarted Do

CAALifGettingStarted gives you a feel of how you can create and manipulate the parameter and relation objects. The parameters define a cylinder. They are the cylinder radius, height, and volume. Since the volume of the cylinder can be computed from its radius and height, a formula, that is, a relation object, is created to perform this computation. The different values of the parameters are retrieved and displayed, and the radius is modified to show the formula result update.

[Top]

How to Launch CAALifGettingStarted

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

[Top]

Where to Find the CAALifGettingStarted Code

The CAALifGettingStarted use case is made of a single source file named CAALifGettingStarted.cpp located in the CAALifGettingStarted.m module of the CAALiteralFeatures.edu framework:

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

[Top]

Step-by-Step

To create parameters that describe a cylinder and a formula that computes the cylinder volume using these parameters, there are five main steps:

1. Prolog
   This step creates a session, a CATPart document, and retrieves from the document's root container a pointer to the factory to be used to create the parameters as well as the formula.
2. Creating the Parameters
   The cylinder is described using two length type parameters named Radius and CylHeight. The cylinder volume is a magnitude type parameter named CylVolume
3. Creating the Formula
   The cylinder volume is computed using the formula:
CylVolume = (PI * Radius**2)*CylHeight
4. Modifying a Parameter Value and Checking the Formula Update
   The cylinder height is modified. The formula updates the volume and the new volume value is displayed.
5. Epilog
   This step closes the document and the session.

[Top]

Prolog

Before going any further in literal programming, you must initialize your environment.

int main()
{
  CAALifServices services;
  // Initialize the session
  int rc = 0;
  rc = services.CAALifInitSession ();
  if( rc != CAALifOk )
    return rc;

  // Retrieve the parameter factory 
  CATIContainer* container = NULL;		
  rc = services.CAALifCreateInstanceContainer( &container );
  if( rc != CAALifOk )
    return rc;

  CATICkeParmFactory_var spFact = container;
  ...

This task consists in:

1. Creating a session
   This is done by the CAALifInitSession method of the CAALifServices class defined in the CAALifBasis.m module.
2. Creating a document and retrieving its root container through a literal factory interface.
   This is done by the CAALifCreateInstanceContainer method of the CAALifServices class that is also defined in the CAALifBasis.m module and that returns a CATIContainer interface smart pointer, cast into a CATICkeParmFactory smart pointer. There are two important points about this interface:
   1. It is implemented by any root container
   2. It provides you with all the literal and relation creation methods.

[Top]

Creating the Parameters

Three parameters are created using the CATICkeParmFactory smart pointer: two length type parameters for the cylinder radius and height, and a dimension type parameter for the cylinder volume.

1. Creating two length type parameters

   ... CATUnicodeString RadiusName("Radius"); double RadiusValue = 2.5; CATICkeParm_var spRadius = spFact->CreateLength(RadiusName, RadiusValue); if (NULL_var != spRadius) { ... // Display the radius CATUnicodeString HeightName("CylHeight"); double HeightValue = 4.; CATICkeParm_var spHeight = spFact->CreateLength(HeightName, HeightValue); if (NULL_var != spHeight) { ... // Display the cylinder height ...

   The length type parameters are created using the CreateLength method of the CATICkeParmFactory interface. This method takes as its first argument the parameter name and as its second argument the initial value assigned to the parameter. This value must be expressed according to the International System of Units (SI), that is, in meters.
   

2. Creating a dimension type parameter

   ... CATICkeMagnitude_var spVolumeMagnitude = CATParmDictionary::FindMagnitude("VOLUME"); if (NULL_var != spVolumeMagnitude) { CATUnicodeString VolumeName("CylVolume"); double VolumeValue = 2.; CATICkeParm_var spVolume = spFact->CreateDimension(spVolumeMagnitude, VolumeName, VolumeValue); if (NULL_var != spVolume) { ... // Display the volume ...

   The dimension type parameter must have a magnitude chosen among those managed by the dictionary of types. A smart pointer to the VOLUME magnitude is asked to the dictionary using the static CATParmDictionary::FindMagnitude method. The dimension type parameter is created thanks to the CreateDimension method of the CATICkeParmFactory interface, that takes the magnitude as a parameter in addition to the parameter name and initial value. This value is also expressed according to the International System of Units (SI), that is, in cubic meters.

[Top]

Creating the Formula

The formula will compute the cylinder volume. This task is done in two substeps:

1. Creating the list of parameters to be used in the formula

   ... // Create the list of parameters to be used in the formula CATCkeListOf(Parm) pParamList; pParamList.Append (spVolume); pParamList.Append (spRadius); pParamList.Append (spHeight); ...

   Before creating a formula, you must provide its parameter list. It is a CATCkeListOf(Parm) instance containing at least all the parameters referred to in the formula. The list is built by appending all the required parameters, including the one to be computed. The parameters required to define the formula are: the volume, the radius, and the cylinder height.

2. Creating the formula itself

   When you create a formula, you must specify the parameter to be constrained as well as the expression that defines it. Here is the portion of the code that creates the "VolumeFormula" relation.

   ... // Create the formula "CylVolume = PI * (Radius ** 2) * CylHeight CATICkeRelation_var spFormula = spFact->CreateFormula ("VolumeFormula", "", "", spVolume, &pParamList, "PI*(a2**2)*a3", NULL_var, CATCke::False); if (NULL_var != spFormula) { cout << "The cylinder volume calculated from VolumeFormula is " ; cout << spVolume->Show().CastToCharPtr() << endl; ...

   The formula is a created using the CreateFormula method of the CATICkeParmFactory interface that returns a smart pointer to the CATICkeRelation interface. The arguments of the CreateFormula method are:

   VolumeFormula	The formula name
   spVolume	The parameter to compute
   pParamList	The list of parameters to be used in the formula
   PI*(a2**2)*a3	The expression defining the constrained parameter. The ai notation allows you specify a relation argument from its rank in the parameter list. spVolume is the first parameter appended to the list. It defines a1. spRadius is the second parameter appended to the list. It defines a2. spHeight is the third parameter appended to the list. It defines a3.

   Note that the second and third arguments must be passed as blank strings, that the seventh argument is a smart pointer that must be set to NULL_var, and that the last argument must be set to CATCke::False.

   The volume of the cylinder is automatically computed as soon as the formula is created. The Show method of the CATICkeParm interface retrieves the volume value as a CATUnicodeString instance that must be cast to a char * using the CastToCharPtr method to be displayed using cout. This value is expressed using the units specified in your CATIA settings (Tools->Options->General->Units). For example, if the volume unit defined in your settings is the cubic inch, you should see:

   The cylinder volume calculated from VolumeFormula is 4.793e+006in3

[Top]

Modifying a Parameter Value and Checking the Formula Update

There are several ways to modify a parameter. In our example, we use the Valuate method of the CATICkeParm interface and specify a double as its arguments.

  ...
  // Modify the "Radius" value
  double NewRadiusValue = 4.;
  spRadius -> Valuate(NewRadiusValue);

  cout << "New radius value is " ;
  cout << spRadius->Show().CastToCharPtr() << endl;
  cout << "The new cylinder volume calculated from the VolumeFormula is " ;
  cout << spVolume->Show().CastToCharPtr() << endl;
  ...

The Valuate method of the CATICkeParm interface modifies the cylinder radius value. The value passed as the argument should always be expressed according to the International System of Units (SI). The new radius value is 4 meters. The Show method of the CATICkeParm interface retrieves this value as a CATUnicodeString instance that must be cast to a char * using the CastToCharPtr method to be displayed using cout.

The values returned by the Show method are expressed using the units specified in your CATIA settings (Tools->Options->General->Units). For example, if the default length unit in your settings is the mm and the default volume unit the cubic meter, you should see:

New radius value is 4000mm

The new cylinder volume calculated from the VolumeFormula is 201.062 m3

[Top]

Epilog

  ...
  rc = services.CAALifCloseSession();
  return rc;
}

The CAALifCloseSession method of the CAALifServices class defined in the CAALifBasis.m module removes the Part document and deletes the session.

[Top]

In Short

This use case shows the objects and interfaces used when creating and using parameter and relation objects. The CATCkeParmFactory interface that provides methods to create these objects is implemented by any document's root container. This factory creates parameters and returns them as CATICkeParm interface pointers. A length type parameter is created using a name and a value, while a dimension type parameter has a magnitude in addition. This magnitude is retrieved from the dictionary of types as a CATICkeMagnitude interface pointer. A formula computes, or constrains, a parameter using others. Each parameter is first set as a CATCkeListOf(Parm) collection item, and the collection is passed to the formula factory method with the parameter to value, and the formula itself. The Valuate method of the CATICkeParm interface modifies the parameter values. The formula is then automatically updated.

[Top]

References

History

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