3D PLM PPR Hub Open Gateway

Knowledge Modeler

Programming with Design Tables

How to create and modify a design table
Use Case

Abstract

This article discusses the CAALifDesignTableCreate use case. This use case illustrates how to create a design table from an external text file, how to specify associations and select a current configuration.

What You Will Learn With This Use Case

This use case is intended to teach you how to create a design table from an external .txt file, do automatic associations as well as one-by-one associations and manage configurations.

[Top]

The CAALifDesignTableCreate Use Case

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

[Top]

What Does CAALifDesignTableCreate Do

This use case:

[Top]

How to Launch CAALifDesignTableCreate

To launch CAALifDesignTableCreate, you will need to set up the build time environment, then compile CALifDesignTableMain along with its prerequisites, set up the run time environment, and then execute the use case which main program is CALifDesignTableMain [1] with a string argument containing the path of the graphic directory in the runtimeview where the text file of the design table can be found (" ...../intel_a(or solaris_a)/resources/graphic").

[Top]

Where to Find the CAALifDesignTableCreate Code

The CAALifDesignTableCreate use case is made of single source file named CAALifDesignTableCreate.cpp which is called by its CAALifDesignTableMain.cpp main program. Both files are located in the CAALifDesignTable.m module of the CAALiteralFeatures.edu framework:

Windows InstallRootDirectory\CAALiteralFeatures.edu\CAALifDesignTable.m\
Unix InstallRootDirectory/CAALiteralFeatures.edu/CAALifDesignTable.m/

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

[Top]

Step-by-Step

Here is the step-by-step description of the program:

  1. Prolog
    This step which is performed in CAALifDesignTableMain creates a session, retrieves a pointer to be used to create parameters from the document root container .
  2. Creating the Parameters
    Six parameters are created. These parameters are intended to be associated with the values of the design table to be created later on.
  3. Creating the Design Table
    The DesignTable.1 design table is created from the CAALifDesignTable.txt file.
  4. Doing Associations
    Only one parameter ("Column1") is associated automatically. Other associations are done one-by-one.
  5. Retrieving the Current Configuration
    The current configuration(0) is displayed by using the CATIDesignTable::ConfigurationRow method
  6. Setting a New Configuration
    Configuration1 is declared as active by using the CATIDesignTable::SetCurrentConfiguration method. You can check that the first line of the CAALifDesignTable00.txt file is applied to DesignTable.1
  7. Removing an Association
    The association created with Column4 is removed by using the CATIDesignTable::RemoveAssociation method. Configuration2 is now selected as active configuration. The parameter values are displayed again. They all match the second line of the CAALifDesignTable00.txt file except the first and the fourth parameter values.
    When a cell is empty in the input design table or when an association has been removed, the value assigned to the corresponding parameter is the last which has been assigned to it.
  8. Epilog
    This step closes the document and the session.

[Top]

Prolog

Before going any further, 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 Parameters

Six parameters are created using the CATICkeParmFactory smart pointer [2].

...
CATICkeParm_var spPp1 = spFact->CreateInteger ("Column1",0);
CATICkeParm_var spPp2 = spFact->CreateReal ("r",0.0);
CATICkeParm_var spPp3 = spFact->CreateString ("s","");
CATICkeParm_var spPp4 = spFact->CreateBoolean ("b",CATCke::True);
CATICkeParm_var spPp5 = spFact->CreateLength ("l",0);
CATICkeParm_var spPp6 = spFact->CreateAngle ("a",0);
...

Note that in a usual application, these parameters are retrieved from a document by using the CATParmDictionary::VisibleParms method.

[Top]

Creating the Design Table

The DesignTable.1 design table is created using the CATICkeParmFactory smart pointer. The CreateDesignTable method of the CATICkeParmFactory interface is used. This method takes as its first argument the design table name, as its second argument a comment and as its third argument the path of the external file.

The CreateDesignTable method returns NULL_var when:

[Top]

Doing Associations

This task is done in three sub steps:

  1. Creating the list of parameters to be associated automatically with the design table values. Only the parameters with the same name in the document and in the design table can be associated. "Column1" is the only parameter which fulfills this condition. 
    ...
CATLISTV(CATBaseUnknown_var) spList;
spList.Append(spPp1);
...
  2. Creating the automatic associations themselves
    The AutomaticAssociations method of the CATIDesignTable interface is used. This method takes as its first argument the CATIParmPublisher root (the root container is a CATIParmPublisher), as its second argument the NULL_var smart pointer, and as its third argument the list of parameters to be associated with the design table values. 
    ...
spDesign->AutomaticAssociations(iCont, NULL_var, &spList);
...

    The list passed as the third argument of the AutomaticAssociations method contains only a single item: "Column1". The spP1 value is automatically added to the design table. If you make the input list longer by adding all the other parameters, the AutomaticAssociations method won't give you a different result as the names of the other parameters differs from the design table column names. If you want to associate a parameter with a column with a different name, you must use the AddAssociation method of the CATIDesignTable interface and perform the associations one-by-one as in the step below.

  3. Creating other Associations One-by-One The AddAssociation method of the CATIDesignTable interface is used. This method takes as its first argument the name of the design table column and as its second argument the document parameter to be associated with the design table column. 
    ...
spDesign->AddAssociation("Column2", spPp2);
spDesign->AddAssociation("Column3", spPp3);
spDesign->AddAssociation("Column4", spPp4);
spDesign->AddAssociation("Column5", spPp5); 
// 11 is expected
cout<< spDesign->AddAssociation("Column16", spPp6) << endl;
...

    Here is the list of errors that can be returned by the AddAssociation method: 

      NoError,
  ColumnNamesNotUnique,
  BadCellType,
  BadColumnType,
  NotAMagnitude,
  ParameterNotAssociated,
  AttributeProblem,
  BadConfiguration,
  ParseSheetError,
  ParameterAlreadyAssociated,
  ColumnAlreadyAssociated,
  ColumnDoesntExist

    This list is described by an enum. When there is no error, 0 is returned. When the column does not exist, 11 is returned.

[Top]

Retrieving the Number of Associations

The Associations method of the CATIDesignTable interface returns the list of associations that have been done for a document.

...
// 5 is expected
cout << "The number of associations is: ";     
cout << spDesign->Associations()->Size() << endl;

The number of associations is displayed. One associations has been done automatically, four others have been done one-by-one by using the AddAssociation method of the CATIDesignTable interface.

[Top]

Retrieving the Current Configuration

After a design table has been created and associations done between the design table values and the document parameters, there is no current configuration. The design table configuration must be specified by using the SetCurrentConfiguration method of the CATIDesignTable interface.

The ConfigurationRow method of the CATIDesignTable interface returns the configuration number. 0 means that there is no active configuration.

...
cout << "The current configuration is (0 expected): " ;
cout << spDesign->ConfigurationRow() << endl;

spDesign->SetCurrentConfiguration(1); 

cout << "The new current configuration is (1 expected): " ;
cout << spDesign->ConfigurationRow() << endl;
...

Redisplaying the parameter values allows to check that the first row of the CAALifDesignTable00.txt file is applied to DesignTable.1

[Top]

Removing an Association

The association created with Column4 is removed by using the RemoveAssociation method of the CATIDesignTable interface. The new number of associations is now 4.

[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

The following programming steps are typically required when creating a design table:

[Top]

References

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

History

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

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