Enumerator instance (category)
The enumerator consists of an identifier as category name, an enumerator value and an optional object type (complex data type) for the category. Since enumerations in ODABA support hierarchies (hierarchical classifications), enumerators may contain a list of subcategories (enumerators).
When no enumerator values are defined, the values are created automatically according to the position of the instance in the enumeration list.
An enumerator may refer to a list of sub items. Enumerator values in the hierarchy must be unique. When the enumerator is typed, all subcategories must refer to the same type or specializations to the type.
Enumerators can be linked with multilingual definition topics, which allow defining label and definitions in different languages.
enumerator |= identifier [ref_type] [ enum_value ] [enum_def] [',']
Enumerator attributes are read into the dictionary on demand. In order to request enumerator attributes, one may access the enumeration via odaba::TypeDefinition or access enumerator attributes as attributes of enumerator values. The following enumerator attributes are accessible:
- code - the numerical enumerator value as being stored in the enumerator attribute
- name - the enumerator name as being used in programs
- label - language depending enumerator name
- title - language depending short description
- description - detailed language depending description of the enumerator value (html)
- condition - condition or default value associated with the category
- type - data type associated with the category
When defining enumerated attributes within a complex data type or as variable (e.g. within an OSI function), enumerator attributes may be provided for the enumerator value currently set in the attribute.
// OSI
// obtain from enum value
... fragment ( Languge my_lang ) { my_lang contains an enum-value
Message(my_lang.name); // display enumerator name
Message(my_lang.label); // display enumerator label
if ( !my_lang.condition.isEmpty() )
Message(my_lang.condition);// display condition
}
// obtain from type definition in dictionary
... fragment ( Dictionary &dict ) {
VARIABLES
TypeDefintion td = dict.typeDefinition("Language"); // system enum
int count = td.enumerator.count;
EnumeratorDefinition ed;
PROCESS
while ( --count >= 0 ) {
ed = td.enumeratorDefinition(count);
Message(ed.name); // display enumerator name
Message(ed.label); // display enumerator label
if ( !ed.condition.isEmpty() )
Message(ed.condition); // display condition
}
Internally, enumerator attributes are odaba::String (except code, which is numeric). Hence, within OSI functions one cannot apply operators on enumerator attributes, but odaba::String functions, only.
In principle, multilingual support is provided for enumerators. Thus, label, title and description may be provided in several languages. Language depending attributes are provided according to the language set in option DSC_Language. Since enumerator definitions are part of the dictionary, language cannot be changed while running the application.
In order to provide textual information in a certain language, one may directly access enumeration definitions as being stored in the resource database (dictionary). The DSC_Language option has to be set to the required language before reading.
// read value descriptions from dictionary database
// (fragment)
String oldLanguage(Option("DSC_Language").toString());
Option("DSC_Language") = "German"; // set documentation language
try {
Property enum_ph(dict,"SDB_ValueList");
Property evals(enum_ph,"values"); // all values
Property topic(evals,"resource_ref(0).definition");
Value title(topic,"name");
Value label(topic,"label");
Value characteristic(topic,"definition.characteristic");
enum_ph.get("AccessModes|0");
while ( evals.next() )
output(label.toString() + "(" +title.toString() + "): " +
characteristic.toString();
} catch ( ... )
// handle exceptions
}
Option("DSC_Language") = oldLanguage; // reset original language
ODABA supports hierarchical enumerations, i.e. each category (enumerator) may get any number of subcategories. Internally, the hierarchical view to enumerators will be provided, i.e. each enumeration definition provides a list with the top level enumerators and each enumerator provides a list with subcategories.
Within the dictionary, enumerations are provided as SDB_ValueList, which contain a list with all enumerator instances (values) as well as a list with top categories (top_values), where each category may have got a number of subcategory values (sub_values).
In order to provide subordinated enumerators for an EnumeratorDefinition in the dictionary, one may call subEnumeratorDefinition() or subEnumeratorEntry().
// read categories recursively
// (fragment)
try {
Property enum_ph(dict,"SDB_ValueList");
Property evals(enum_ph,"top_values"); // top categories
enum_ph.get("_OptOptions|0");
while ( evals.next() )
displayCategory(evals,0);
} catch ( ... )
// handle exceptions
}
// display catagory and sub-categories
void displayCategory(Property &eval, int level) {
Property evals(eval,"sub_values"); // sub-categories
try {
output(sys_ident.toString() + "(" +level + ")");
while ( evals.next() )
displayCategory(evals,0);
} catch ( ... )
// handle exceptions
}
}