Accessing Enumerations
Using enumerations has some advantages when being used in a programming language. You may define a common (readable) name and use a numeric representation e.g. in switch blocks. An enumerations in ODABA is more than a simple name/value mapping. ODABA enumerators provide code, name, condition, type, label, title and a description. Moreover, each enumerator may have got a sub list, which allows defining hierarchical enumerations.
Label, title and a description are language depending and might be provided in any number of languages. Thus, a developer may define an enumeration in several languages and access language depending definitions from within an application. This is quite useful when developing multilingual applications.
Usually, within object instances enumerated properties are stored with the code value for an enumerator (code). The enumerators code value is linked with a enumerator instance, which provides more detailed information as title and description.
Enumerators of an enumerations might be read via dictionary or database. There are three different ways accessing details of an enumeration.
- Accessing enumerators via type definition
- Accessing enumerators via enumeration property handle
- Accessing enumerators via SDB_ValueList extent in the dictionary
Providing enumerations by type definition or enumeration property handle provides language depending information (display_name, title, description) for the language set in the language option DSC_Language, only. Type definition data is cached in the dictionary and will not be reread after changing the language settings within the application. Both, dictionary and database property refer to the cached dictionary information. Thus, different language versions can be accessed only by reading enumerations via SDB_ValueList property handles.
Details for an enumeration are provided via type definitions. Type definitions might be provided via the dictionary or via a value handle referring to an enumerated value (value.typeDefinition()). The type definition is the fastest and most simple way accessing enumerators. It is, however, less flexible, since you cannot change enumerator order and language.
Type definition data is cached in the dictionary and will not be reread after changing the language settings within the application. Different language versions can be accessed only by reading enumerations via SDB_ValueList property handles.
... fragment ( Dictionary &dict ) {
TypeDefinition td(dict.typeDefinition("GenderTypes"));
EnumeratorDefinition enum_def(td.enumeratorDefinition("male");
printf("%s: %s\n",enum_def.displayName(),enum_def.description());
}
ODABA allows considering enumerations as database extents (linked or lookup tables), which provide extended information for an enumerated value stored in an attribute. This allows joining object types with enumerations via enumerated properties. In order to access enumerations as database extent, a property handle with the enumeration name might be opened, which provides the object properties code, name, type, display_name, title, description, condition and value_list for sub enumerators.
The property internally refers to the enumeration loaded into the dictionary. Thus, similar to type definitions, property handles for enumerations cannot change language after loading the enumeration ones. In contrast to type definitions, you may change, however, the sort order and access enumerations by different order keys: ik_code, ik_name, ik_type and ik_display_name.
... fragment ( Database &database ) {
Property types(database,"GenderTypes",PI_Read);
Value display_name(types,"display_name");
Value description(types,"description");
types.get("male");
printf("%s: %s\n",display_name.toString(),description.toString());
}
When accessing enumerations via dictionary, you may access them by opening a property handle for SDB_ValueList, which contains the enumeration definitions in the dictionary. The simple way is accessing enumerations via type definitions, but the access via an SDB_ValueList property handle.
This is the most flexible way of accessing enumerations. The SDB_ValueList instances provide the enumeration definitions from the dictionary database. Different language versions for enumerators can be provided only by reading enumerations via SDB_ValueList property handles. accessing enumeration values looks a bit difficult, since enumerator properties are not directly stores in the SDB_Value instances (database representation for enumerators). The known enumerator properties are mapped to the following access paths in SDB_Value:
code: __AUTOIDENT
name: sys_ident
type: type
condition: condition
displayName: resource_ref(0).description(0),definition.label
title: resource_ref(0).description(0),definition.definition.characteristic
The enumerator collection might be ordered by code (ik_code) or name (ik_value). Hierarchical access becomes possible by accessing the top_values property in the enumeration and reading subordinated values via property value_list. All enumerations can be accessed via the values property in SDB_ValueList.
... fragment ( Dictionary &dict ) {
Property enums(dict,"SDB_ValueList",Read);
Property values(enums,"values"); // SDB_Value (all values)
Property topic(values,"resource_ref(0).description(0)");
Value display_name(topic,"definition.label");
Value description(topic,"definition.definition.characteristic");
enums.get("GenderTypes"); // select enumeration, default order is ik_name
values.get("male"); // select value in enumeration
printf("%s: %s\n",display_name.toString(),description.toString());
}