3D PLM PPR Hub Open Gateway

What You Will Learn With This Use Case

In this use case, you will learn how to create a user function to be added to the Knowledge Advisor dictionary.

[Top]

The CAALifUserFunction Use Case

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

[Top]

What Does CAALifUserFunction Do

This use case creates the Hypothenuse function. Given X and Y two input arguments, the function is defined as follows:

"Hypothenuse = SQRT(X*X+Y*Y)"

[Top]

How to Launch CAALifUserFunction

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

[Top]

Where to Find the CAALifUserFunction Code

The CAALifUserFunction use case is made of several classes located in the CAALifUserFunction.m  and CAALifBasis.m modules of the CAALiteralFeatures.edu framework:

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

The use case is divided into four parts:

1. The code portion which defines the function signature. It is provided in the CAALifDicoLibrary.cpp file of the CAALifBasis.m module. This class is an implementation of  the CATIAddLibrary interface.
2. The code portion which specifies how the user function is computed to generate a result. This part is called the evaluator and it is supplied in the CAALifEval.cpp file of the CAALifBasis.m module.
3. The piece of code which loads the library containing the user function. This part is delivered in the CAALifCreateExt.cpp file of the CAALifBasis.m module. It is an extension of the CAALifDicoLibrary class to implement the CATICreateInstance interface.
4. The main program which is delivered in the CAALifUserFunctionsMain.cpp of the CAALifUserFunctions.m module. Its purpose is only to check that the function defined in the CAALifDicoLibrary class is valid and can be used in a formula.

[Top]

Step-by-Step

The CAALifUserFunction use case is divided into the following steps:

1. Defining the Function Signature
2. Writing the Evaluator
3. Creating a User Function Object
4. Checking the User Function Validity (Main Program)

[Top]

Defining the Function Signature

Actually, to define a user function signature, you must provide an implementation of the CATIAddLibrary interface (KnowledgeInterfaces framework). By doing this, you define a type that you will have to instantiate later on to finally create your user function object. The only method to implement is CATIAddLibrary::Add.

1. Start by declaring the CATImplementClass macro. The object type to be created (CAALifDicoLibrary) is to be passed as the first argument of the macro.
2. Specify that the CAALifDicoLibrary object implements CATIAddLibrary by including the TIE header file as well as the TIE macro. Let's remind you that the TIE_CATIAddLibrary.h header is generated from the TIE_interface.tsrc file. Refer to the System framework documentation for more information.
3. Provide the implementation of the CATIAddLibrary::Add method. When declaring a user function signature, use the methods provided by CATICkeFunctionFactory object retrieved with CATCkeGlobalFunctions::GetFunctionFactory.
   1. CATICkeFunctionFactory::CreateFunction allows you to create a function. You must pass the user function name ("Hypothenuse") as the first argument, the type of the return value as the second argument and the evaluator as the third argument.
   2. CATICkeFunctionFactory::CreateArg enables you to create an argument.
   3. CATIParmDictionary::GetxxxType allows you to specify an argument type.
4. Specify the arguments of the user function. To do this, use the CATICkeSignature::AddArgument which takes as its argument a CATICkeArg object. You retrieve the CATICkeArg object by using the CATICkeFunctionFactory::CreateArg method.

   In our example, the "Hypothenuse" function has two input arguments. Output arguments can also be specified. To do so, you must specify a third argument as following: spSign->AddArgument(CATCkeGlobalFunctions::GetFunctionFactory()->CreateArg("iC", CATCkeGlobalFunctions::GetParmDictionary()->GetLengthType(), CATICkeArg::Out)); A user-function which returns the computed value in an output argument cannot be used in a formula.

[Top]

Writing the Evaluator

The purpose of the evaluator is to compute the O (result) = SQRT(A*A + B*B) relation. The programming steps typically required when writing an evaluator are:

1. Retrieve the parameters from the argument list passed in the first argument of the evaluator. When the user function has output arguments, you must also get the pointers to the output arguments as the purpose of the evaluator is finally to assign the computed result to the output argument(s). Examples of functions using output arguments are the default:

   point.coord(coordNumber)
   point.coord(Real1, Real2, Real3)

   provided in the knowledgeware editors and operating on GSM objects.

2. Retrieve the input parameter values. To do this, use one of the appropriate CATICkeInst::Asxxx method. If any, you must also get the output arguments.
3. Write the C++ code allowing the user function to evaluate. Performing the computation is very simple in our example. But you may come across more complicated cases, needing to access the geometric modeler data.
4. Assign the computed result either to the function return value or to the output argument. In our example, the user function has no output argument, the computed result is assigned to the return value.

[Top]

Creating a User Function Object

The System framework provides you with a service whereby you can create an instance of an object adhering to a given interface. To create an object adhering to the CATIAddLibrary interface, we extend the code implementing CATIAddLibrary and provide in this extension the CATICreateInstance implementation. To implement the CreateInstance method, you just have to use the new operator.

...
CATImplementClass(CAALifCreateExt, CodeExtension, CATBaseUnknown, CAALifDicoLibrary);

#include <TIE_CATICreateInstance.h>
TIE_CATICreateInstance(CAALifCreateExt); 

// Implement CATICreateInstance::CreateInstance
HRESULT __stdcall CAALifCreateExt::CreateInstance (void **ppv)
{
*ppv = new CAALifDicoLibrary ();
return S_OK;
}

[Top]

Checking the User Function Validity (Main Program)

The purpose of the CAALifUserFunctions.cpp sample is only to check that the user function can be used in a formula, i.e. that the expression declaration is correct and that the parameter constrained by the formula is properly updated.

Here are the programming steps:

1. The environment is initialized, then the CATICkeParmFactory is retrieved from the document container. Refer to [2] for more information on the purpose of this factory.
2. Two parameters of real type are created. These parameters are to be used as input arguments in the user function used in "Formula1". For information on how to create parameters, see [3].
3. The real type parameter "z" is created. This parameter is to be constrained by "Formula1".
4. The formula created specifies that the "z" parameter equals 2 * "Hypothenuse(x, y)". For information on how to create a formula, see [4].
5. The Formula1 syntax is checked. To do this, we use the CATICkeRelation::CanBeEvaluated method. If the method returns 1, the formula evaluates and the resulting value is displayed in the standard output. Otherwise, a message warns you that the formula syntax is wrong.

[Top]

In Short

To write the code of a user-function, you must:

1. Specify the function signature: its name, arguments and evaluator. This function signature is defined through a type which is extended to create the user-function object itself.
2. Write the evaluator declared in the function signature.
3. Create an object which has the type of the signature. To do so, you must provide an implementation of the CATICreateInstance interface (System framework).

[Top]

References

History

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