3D PLM PPR Hub Open Gateway

Knowledge Modeler

Creating and Manipulating Formulas

How to do some basic operations with formulas

Use Case

Abstract

This article explains how to create, modify, and display formulas. To keep up with the material presented in this article, it is better if you have a prerequisite knowledge of formulas from an end user point of view. If need be, refer to the Knowledge Advisor User's Guide.

What You Will Learn With This Use Case
The CAALifFormula Use Case

What Does CAALifFormula Do
How to Launch CAALifFormula
Where to Find the CAALifFormula Code

Step-by-Step
In Short
References

What You Will Learn With This Use Case

In this use case, you will learn how to:

Create and modify a formula
Test the formula activity, then reactivate a formula after it has been deactivated.

[Top]

The CAALifFormula Use Case

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

[Top]

What Does CAALifFormula Do

The CAALifFormula use case:

Creates three parameters of string type:
- ModuleName - with an initial value of CAALifRelations
- ProjectKey - with no initial value specified
- Topic - with no initial value specified
Creates a formula specifying that the ProjectKey parameter value is determined from the six first characters of the ModuleName parameter. To extract this sub-string from ModuleName, we use the Extract function. The extract function is provided by default as a string function in the dictionary which is displayed in the "Formulas" dialog box when you create a formula as an end user. For information on how to use this function, see the Knowledge Advisor Programming Guide.
Modifies the formula expression. The initial formula ExtractForm:ProjectKey=ModuleName.Extract(0,6) is replaced with ExtractForm:ProjectKey=Topic.Extract(0.5) tests the formula activity. When a formula is modified, it is deactivated. In this step, we check that the formula is deactivated.
Re-activates the formula.

Reminder

The ExtractForm:ProjectKey=ModuleName.Extract(0,6) notation the one used to display a formula in the specification tree. ExtractForm is the formula name, ProjectKey is the parameter to be constrained by the formula, ModuleName is the parameter the Extract method applied to.

In this article, we use the same notation as in the specification tree.

[Top]

How to Launch CAALifFormula

To launch CAALifFormula, you will need to set up the build time environment, then compile CAALifFormula along with its prerequisites, set up the run time environment, and then execute the use case which main program is CAALifRelationMain. This program encompasses two use cases [1].

[Top]

Where to Find the CAALifFormula Code

The CAALifFormula use case is made of CAALifFormula.cpp file located in the CAALifRelations.m module of the CAALiteralFeatures.edu framework:

Windows	`InstallRootDirectory\CAALiteralFeatures.edu\CAALifRelations.m\`
Unix	`InstallRootDirectory/CAALiteralFeatures.edu/CAALifRelations.m/`

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

The main program related to this file is CAALifRelationMain.

[Top]

Step-by-Step

CAALifFormula is divided into seven steps:

Creating the Parameters
Creating the Parameter List
Creating the Formula
Displaying the Extracted String
Modifying the Formula Expression
Testing the Formula Activity
(Re)-Activating the Formula

[Top]

Creating the Parameters

Three parameters are created [2] [3]. Note that in a usual application, these parameters are already created. You just have to retrieve them and append them within a list.

The CATParmDictionary::VisibleParms method can be used to retrieve list of parameters below a published feature.

...
// -------------------------
// 1 - Create the parameters
// -------------------------

  // Create the "ModuleName" parameter
  // Initial value = "CAALifRelations"
  CATICkeParm_var 
    spString1=spFact->CreateString("ModuleName","CAALifRelations");
  
  // Create the "ProjectKey" parameter
  // No initial value specified
  CATICkeParm_var 
    spString2=spFact->CreateString("ProjectKey",""); 
  
  // Create the "Topic" parameter
  // Initial value is "Formulas"
  CATICkeParm_var 
    spString3=spFact->CreateString("Topic","Formulas"); 
...

[Top]

Creating the Parameter List

Before creating a formula or any other relation, you must create a parameter list containing at least, all the parameters to be used in the formula. The parameter to be constrained by the formula and the parameters used as the arguments in the formula expression must be appended to the list.

Note that you can create a list with more parameters that required.

Objects can be appended in any order but you should bear in mind that the order they are declared in the list (that is their rank) is reused when you create the formula.

...
// -----------------------------
// 2 - Create the parameter list
// -----------------------------

  // Create the parameter list
  CATCkeListOf(Parm) pList;

  // Append ModuleName to the created list
  pList.Append (spString1);  // a1 = "ModuleName"

  // Append ProjectKey to the created list 
  pList.Append (spString2);  // a2 = "ProjectKey" 

  // Append Topic to the created list
  pList.Append (spString3);  // a3 = "Topic"
...

If you modify the parameter list, pay attention to the relations which rely on this parameter list.

[Top]

Creating the Formula

The CATICkeParmDictionary::CreateFormula method allows you to create a formula. The formula created specifies that the ProjectKey parameter equals the first six characters of the ModuleName parameter value.

About the Extract Method (see the Knowledge Advisor Programming Guide)
: Extract is to be used as a method applying to ProjectKey. It returns the sub-string starting at a given position with a specified length. The first argument of Extract is the index of the sub-string first character. The second argument is the sub-string length.

The formula which would be displayed ExtractForm:ProjectKey.Extract(0,6) in the specification-tree is specified "a1.Extract(0,6)" in the CreateFormula method.

// -------------------------------------------------------------
// 3 - Create the ExtractForm formula which extracts
//     the first six characters from the ModuleName parameter
// -------------------------------------------------------------
CATICkeRelation_var
  spFormula1 = spFact->CreateFormula ("ExtractForm",
                                                 "",
                                                 "",
                                          spString2,
                                              &list,
                                  "a1.Extract(0,6)",
                                           NULL_var,
                                     CATCke::False);

Here is the description of the arguments:

argument 1: specify the name of the formula to be created ("ExtractForm")
argument 2: should be a blank string
argument 3: should be a blank string
argument 4: specify the parameter to be constrained ("ProjectKey")
argument 5: specify the list of parameters to be used in the formula
argument 6: specify the expression defining the constrained parameter.
The a_i notation allows you specify a relation argument from its rank in the parameter list.
"ModuleName" is the first parameter appended to the list. It is denoted a1 in the CreateFormula method.
argument 7: should be NULL_var
argument 8: should be CATCke::False.

If the syntax of the formula expression is wrong, the CreateFormula method returns NULL_var.

[Top]

Displaying the Extracted String

The expected value for ProjectKey parameter is CAALif. To check this value, we use the CATICkeInst::AsString method.

...
// -------------------------------------------------------------
// 3 - Retrieving and displaying the new ProjectKey value
// -------------------------------------------------------------
cout << "The ProjectKey value is: " ;
cout << (spString2->Value()->AsString()).CastToCharPtr() << endl; 
...

At run-time, the statements above display in the standard output the message below:

The ProjectKey value is: CAALif

[Top]

Modifying the Formula Expression

The CATICkeRelationExp::Modify method is to be used to modify the expression of a formula. Note that modifying a formula deactivates it. If you display the value of the constrained parameter before the relation has been reactivated, you don't get the new value.

...
// ------------------------------------------------
// 4 - Modify the formula
//     Replace a1.Extract(0,6) with a3.Extract(0.5)
// ------------------------------------------------
CATICkeRelationExp_var spExpform = spFormula1 ;
spExpform->Modify(&list,"a3.Extract(0,5)", NULL_var, CATCke::False);

Here is the description of the arguments:

argument 1: specify the parameter list where the parameters used to specify the formula expression are appended.
argument 2: specify the new formula expression
argument 3: should be NULL_var
argument 4: should be CATCke::False

[Top]

Testing the Formula Activity

A formula which is modified is deactivated. We check that ExtractForm is no longer active.

...
// ------------------------------------------------
// 5 - Test the formula activity
// ------------------------------------------------
cout << spFormula1->IsActivated() << endl;
...
cout << "The ProjectKey value is: " ;
cout << (spString2->Value()->AsString()).CastToCharPtr() << endl;

At run-time, the statements above display in the standard output the messages below

0
The ProjectKey value is: CAALif

[Top]

(Re)-Activating the Formula

The CATICkeRelation::Activate() method allows you to reactivate a formula which has just been modified (this also applies to rules and checks).

...
// ------------------------------------------------
// 6 - Re-activate the formula
// ------------------------------------------------
spFormula1->Activate();
cout << "The ProjectKey value is: " ;
cout << (spString2->Value()->AsString()).CastToCharPtr() << endl;

At run time, the statements above display in the standard output the messages below:

The ProjectKey value is: Formu

[Top]

In Short

The following programming steps are typically required when writing formulas:

Create the parameter list to be passed as the argument 5 of the CATICkeParmFactory::CreateFormula method
Create the formula itself. The a_i notation method relies on the parameter rank in the parameter list.
If need be, modify the formula by using the CATIRelationExp::Modify method. Modifying a formula deactivates this formula.

[Top]

References

[1]	Building and Launching a CAA V5 Use Case
[2]	Using Persistent Parameters
[3]	Using Volatile Parameters
[Top]

History

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