3D PLM Enterprise Architecture

What Are Setting Attributes and Repositories?

Setting attributes provide an easy way for applications to store and retrieve default values and last used values, or values to save and restore upon request, for the parameters or objects they use.

Setting attributes are stored in one or several setting repositories, instances of the class CATSettingRepository. Each setting repository has a unique name used by the application to access it. The application sees the setting repository as an aggregate of named attributes which gathers copies of all the parameters or objects the application has decided to save.

Even if the setting attributes are objects, you can not handle setting attributes as objects, that is you cannot instantiate them using a constructor, use the new and delete operators, and use their methods. You will see them only as named attributes.

A setting repository instance can be saved in memory for temporary storage using a commit/rollback mechanism, and in a file for persistent storage.

The base class for setting repositories is CATSettingRepository. The application should instantiate this class to create its own setting repository.

[Top]

Basic Setting Rules

The following rules apply to setting attributes:

1. Keep the meaning of an attribute defined in an earlier version
2. Define the default value of an attribute once
3. Never modify a setting attribute value out of the Options command of the Tools menu
4. Always store the attributes of a given Options command property page in the same setting file
5. Any parameter storing a file or directory pathname must accept environment variables and DLNames to make up the pathname
6. Any parameter displayed in an Options command property page must be lockable and restorable.

[Top]

A Setting Example

This example uses the simple types integer and float. The example is split in several parts to give full explanations on each part.

#include "CATSettingRepository.h"
...
  int length=10;

  CATSettingRepository * SampleRepository; // instantiate a repository

  SampleRepository =                       // get a repository by its name 
         CATSettingRepository::GetRepository("sample");
                                           // read settings
  SampleRepository->ReadSetting("LengthSetting",&length);
...

The setting repository SampleRepository is instantiated, and then assigned the values retrieved from the file sample.CATSettings. If sample.CATSettings exists as a disk file in one of the directories whose pathnames are declared using the CATUserSettingPath and CATReferenceSettingPath environment variables, it is copied into SampleRepository. Otherwise SampleRepository remains empty and can be used after being filled in to create the disk file sample.CATSettings using the method SaveRepository.

The method ReadSetting assigns the value of the setting attribute LengthSetting to the variable length. If LengthSetting does not exist, ReadSetting executes first the method WriteSetting with the current value of length to initialize LengthSetting.

...
  int newlength;
  SampleRepository->ReadSetting("LengthSetting",
                                &newlength);
...

The method ReadSetting assigns the value saved in the setting attribute LengthSetting to newlength which is thus set to 10.

...
  SampleRepository->Commit();
  length=11;
  SampleRepository->WriteSetting("LengthSetting",&length);
  SampleRepository->Rollback();
  SampleRepository->ReadSetting("LengthSetting",&length);
...

The setting repository SampleRepository is saved in memory using the method Commit. This saves the setting attribute LengthSetting along with its current value, that is 10. The method WriteSetting assigns then the current value of length, that is 11, to the setting attribute LengthSetting.

The method Rollback restores the saved setting repository SampleRepository. The setting attribute LengthSetting is assigned the value 10. The ReadSetting method assigns this value to length.

...
  SampleRepository->SaveRepository();
...

The method SaveRepository writes the setting repository SampleRepository to the disk file sample.CATSettings. In addition, this method executes the method Commit and thus saves SampleRepository in memory for a possible future Rollback.

[Top]

How Do Setting Repositories and Attributes Work?

Setting repositories are the basic objects to store setting attributes. They are accessed using their name. If the setting repository searched for with a given name does not exist, it is created as an empty setting repository with this name.

[Top]

Saving and Restoring Application Objects using Setting Attributes

A setting repository contains setting attributes. Each setting attribute is accessed by its name. Reading from and writing to a setting repository works as follows:

• Application objects used must be instantiated and valued
• Reading a setting attribute from a setting repository to value an application object copies the value saved in the setting attribute into the application object if the setting attribute exists, or creates and valuates the setting attribute with the application object current value if it does not exist. This avoids from testing if the setting attribute exists before using it.
• Writing a setting attribute into a setting repository copies the application object value to save into the setting attribute.

The methods ReadSetting and WriteSetting strictly control the type of their arguments and issue an error when the application attempts to overload or redefine an existing type.

[Top]

Saving and Restoring Setting Repositories

The commit/rollback mechanism using the methods Commit and Rollback allows to save the current state of a setting repository in memory, and to restore it upon request. This save is dedicated to be used within the application and is lost when exiting.

To save a setting repository as a disk file, use the method SaveRepository, which also executes the Commit method. This is the method to use for a persistent save. The directories to use are declared using two environment variables:

1. CATReferenceSettingPath to declare the administrator directory pathnames
2. CATUserSettingPath to declare the user directory pathnames.

The directory pathnames declared using CATReferenceSettingPath can only be read by the user and are aimed to be shared by several users. Through the applications they use, the users can not add or delete setting attributes in files located in these directories.

The administrator can choose two ways for the users to manipulate the files located in these directories through the applications they use:

1. Allowing for overloading of a file in a user directory which pathname is declared using the CATUserSettingPath variable. This is made possible by setting the file mode to rwxr--r--
2. Preventing from overloading a file is made possible by setting the file mode to rw-r--r--

The variable CATReferenceSettingPath must be valued and has no default value. The variable CATUserSettingPath has the user's $HOME/CATSettings directory as default value with UNIX and c:\Documents and Settings\username\CATSettings with Windows.

The pathnames declared by these variables are concatenated: first those of CATReferenceSettingPath, then those of CATUserSettingPath and files are searched for in this order. The first file found is taken.

[Top]

Saving and Restoring Simple Type Variables

Simple type variables, such as integer, float or character, can be saved as, and restored from, setting attributes by means of the methods ReadSetting and WriteSetting. No customization is required.

[Top]

Setting Attributes Programming Tasks

The setting attributes programming tasks are the following:

• Creating or retrieving a setting repository
• Creating or reading a setting attribute
• Writing a setting attribute
• Searching for a setting attribute
• Deleting a setting attribute
• Listing setting attributes
• Saving and restoring a setting repository to/from a memory area
• Saving a setting repository to a disk file

[Top]

Creating or Retrieving a Setting Repository

Use the method GetSettingRepository which searches for a setting repository file in the directories whose pathnames are declared using the environment variables CATReferenceSettingPath and CATUserSettingPath and concatenated in this order. The first file found is used.

SettingRepository = 
       CATSettingRepository::GetRepository("Repository");

If no file named Repository.CATSettings is found, the setting repository is created in memory and will be written on disk with the file name Repository.CATSettings if the method SaveRepository is executed afterwards.

Never call the GetRepository method from a static object.

[Top]

Creating or Reading a Setting Attribute

Use the method ReadSetting as follows:

SettingRepository->ReadSetting(SettingAttributeName,
                               ObjectToValuate);

ReadSetting restores from SettingRepository the current value of SettingAttributeName into the existing class instance ObjectToValuate. If SettingAttributeName does not exist in the current setting repository, it is created and assigned the current value of ObjectToValuate.

[Top]

Writing a Setting Attribute

Use the method WriteSetting as follows:

SettingRepository->WriteSetting(SettingAttributeName,
                                ObjectToSave);

WriteSetting saves the current value of ObjectToSave into the setting attribute SettingAttributeName in SettingRepository. If this setting attribute does not exist, it is created.

[Top]

Searching For a Setting Attribute

Use the method IsPresent as follows:

SettingRepository->IsPresent(SettingAttributeName,
                             SettingAttributeClass);

IsPresent returns 1 if SettingAttributeName is found in SettingRepository and is an instance of the class SettingAttributeClass.

[Top]

Deleting a Setting Attribute

Use the method DelAttribute as follows:

SettingRepository->DelAttribute(SettingAttributeName);

DelAttribute deletes the setting attribute SettingAttributeName from SettingRepository.

[Top]

Listing Setting Attributes

Use the method NextAttribute as follows:

while (SettingRepository->NextAttribute(
                    SettingAttributeName,
                    SettingAttributeClass) =! -1) {
  cout << SettingAttributeName
       << " is an instance of the class "
       << SettingAttributeClass << endl;
}

NextAttribute used in a loop retrieves the setting attributes one after the other from SettingRepository.

[Top]

Saving/Restoring a Setting Repository to/from a Memory Area

Use the method Commit to save the current state of a setting repository to a memory area. You can then restore it upon request using the method Rollback.

...
SettingRepository->Commit();                // Save
...
SettingRepository->Rollback();              // Restore
...

[Top]

Saving a Setting Repository to a Disk File

Use the method SaveRepository to write the current state of a setting repository to a disk file. The setting repository must be instantiated first using the method GetRepository. The file name is the repository name suffixed by setting, here Repository.CATSettings.

SettingRepository = 
       CATSettingRepository::GetRepository("Repository");
...
SettingRepository->SaveRepository();

Depending on the environment variables and on the administrator declaration, the following can occur:

• If the file does not exist, this file is created in the first directory declared using the CATUserSettingPath environment variable, which value is defaulted to the user's $HOME/CATSettings directory with UNIX and c:\Documents and Settings\username\CATSettings with Windows.
• If the file does exist in a directory declared using CATUserSettingPath, it is overwritten.
• If the file does exist in a directory declared using CATReferenceSettingPath:
• if the file has the access mode rwxr--r--, it is created in the first directory declared using the CATUserSettingPath environment variable
• If the file has the access mode rw-r--r--, it is not created an error is issued.

[Top]

In Short

A setting attribute can be of a simple type.

[Top]

References

History

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