|
EDCS Reference Manual
Concept Mapping from EDCS 2.x to EDCS 3.0 |
This document describes how environmental concepts are mapped from the EDCS Version 2.x (including, in particular, EDCS Version 2.9) to EDCS Version 3.0.
The EDCS provides mechanisms to unambiguously specify objects used to model environmental concepts. This is accomplished in EDCS Version 2.x by specifying four types of concepts: classifications, attributes, enumerants, and units of measure.
In EDCS Version 2.x, three mechanisms existed for denoting classification, attribute, and enumerant concepts: the "label", the name, and the code.
-- For classifications, for example, from file "edcs_cc_2x.c" in the SDK Version 3.1 release:
/*
* GLOBAL VARIABLE (Label): EDCS_CC_MINE
* Name: Extraction Mine
* EDCS Classification Code: AA010
* ...
*/
const EDCS_CC_ID EDCS_CC_MINE={{'A','A','0','1','0'}};
The classification "label" is "EDCS_CC_MINE", the name is "Extraction Mine",
and the code is the EDCS_CC_ID data type (a 5-character string) containing "AA010".
-- For attributes, for example, from files "edcs_ac_2x.h" and "edcs_ac_2x.c" in the SDK Version 3.1 release:
/*
* GLOBAL VARIABLE (Label): EDCS_3P0_AC_DEPTH_BELOW_OCEAN_FLOOR
* Name: Depth Below Ocean Floor
* EDCS Attribute Code: DBOF
* ...
*/
const EDCS_3p0_AC_ID EDCS_3P0_AC_DEPTH_BELOW_OCEAN_FLOOR={{'D','B','O','F'}};
The attribute "label" is "EDCS_3P0_AC_DEPTH_BELOW_OCEAN_FLOOR",
the name is "Depth Below Ocean Floor",
and the code is the EDCS_3p0_AC_ID data type (a 4-character string) containing "DBOF".
-- For enumerants, for example, from file "edcs_ee_2x.c" in the SDK Version 3.1 release:
/* * GLOBAL CONSTANT: SE_PROP_VAL_BUT__MARKER_SHIP * Name: Marker ship * ENUMERATOR FOR EDCS Attribute Code: BUT_ * EDCS_AC_BUOY_TYPE_CATEGORY * ... */ #define SE_PROP_VAL_BUT__MARKER_SHIP ((EDCS_3p0_AC_ENUM_VALUE) 106)The enumerant "label" is "SE_PROP_VAL_BUT__MARKER_SHIP", the name is "Marker Ship", and the code is the EDCS_3p0_AC_ENUM_VALUE data type (an integer) of value 106.
In EDCS Version 2.x, a different mechanism existed for denoting units of measure. For example, from file "edcs_types_2x.h" in the SDK Version 3.1 release:
/*
* ENUM: EDCS_3p0_UNIT_ENUM
*/
typedef enum
{
EDCS_3P0_UNITS_AMPERE, /* Electric Current */
EDCS_3P0_UNITS_AMPERES_PER_METER, /* Magnetic Field Strength */
...
} EDCS_3p0_UNIT_ENUM;
The unit of measure "label" is "EDCS_3P0_UNITS_AMPERE",
the name is undefined, and the code is assigned by
the compiler (as a value of the "C" enum datatype EDCS_3p0_UNIT_ENUM).
In summary:
The "label" (the reason for the quote marks will become clear when describing the EDCS Version 3.0) was a symbolic constant that could be used by programmers as a short-hand for the code, e.g., the "label" EDCS_CC_MINE denoting the classification concept known as an "Extraction Mine".
The name was human-readable, but followed no particular syntactic rules. In general names were assigned for ease-of-recognition and to allow for some logical organization of similar concepts, e.g. classification concepts of which one is named "Extraction Mine".
The code was a 5- (or 4-) character string, or an integer, intended for efficient software use, but in practice might be an inefficient string that was (sometimes) human interpretable, e.g., the code "AA010" denoting the classification concept known as an "Extraction Mine".
The EDCS provides mechanisms to unambiguously specify objects used to model environmental concepts. This is accomplished by specifying a collection of nine EDCS Dictionaries of environmental concepts, and a functional interface to convert between numeric values given in different units of measure and scales. An EDCS Dictionary is a list of EDCS Dictionary Entries each of which specifies a single concept. Each EDCS Dictionary contains entries of a similar nature, however each entry is unique. Each EDCS Dictionary Entry consists of the following fields:
The EDCS Application Program Interface (API) supports conversion between real values given in different units of measure.
See the EDCS Website for more information on the structure and content of the EDCS.
Every concept In the EDCS Version 3.0 can be consistently denoted in two fashions: a label and a code.
The label field of an EDCS Dictionary Entry is a compact and human-readable designator that is used to denote a concept. Labels may include the name or names for the concept. Labels:
The code field of an EDCS Dictionary Entry is a compact, and not necessarily human-readable, designator that is used to denote a concept. Codes:
There is a one-to-one relationship between labels and codes in the same EDCS Dictionary. Therefore, a label and a code may be used interchangeably to denote the same concept.
The EDCS Version 3.0 carefully separates the abstract specification of the EDCS (see ISO/IEC 18025 EDCS) from language-specific bindings (see ISO/IEC 18041-4 EDCS Language Bindings: Part 4: C).
As a result, in EDCS Version 3.0, three mechanisms exist for denoting EDCS concepts: the symbolic constant, the label, and the code.
For example, from files "edcs_types.h" and "edcs_class_iso.h" in the SDK Version 3.1 release:
/*
* GLOBAL CONSTANT: ECC_EXTRACTION_MINE
*
* Definition:
* An <EXCAVATION> made in the <TERRAIN> for the purpose of extracting
* and/or exploiting natural resources; an extraction mine.
*/
#define ECC_EXTRACTION_MINE ((EDCS_Classification_Code)343)
static const EDCS_Classification_Label_Entry
EDCS_Classification_Labels[]=
{...
{ECC_EXTRACTION_MINE, "EXTRACTION_MINE"},
...
}; /* EDCS_Classification_Labels */
The classification symbolic constant is "ECC_EXTRACTION_MINE", the label is "EXTRACTION_MINE", and the code is the EDCS_Classification_Code data type (an integer) of value 343.
Analogous mechanisms, and supporting structures and data types, exist for concepts in each of the other eight EDCS Dictionaries.
Thus:
The symbolic constant can be used by programmers as a shorthand for the code, with the value of the code denoting the concept (e.g.) "Extraction Mine". The symbolic constants are defined in ISO/IEC 18041-4 EDCS Language Bindings: Part 4: C.
The label is human-readable, and follows particular syntactic rules. It also denotes the concept (e.g.) "Extraction Mine", and is represented as a string with no prefix. Its string-value is defined in the EDCS abstract specification (ISO/IEC 18025 EDCS). The corresponding symbolic constant is derivable from the label through a set of rules documented in ISO/IEC 18041-4; in particular, the results of applying those rules are fully documented there.
The code is an integer, and is intended for efficient software use. It also denotes the concept (e.g.) "Extraction Mine".
In summary:
The EDCS Version 3.0 includes significant changes from EDCS Version 2.x in the manner in which EDCS concepts (classifications, attributes, enumerants, and units of measure) are denoted -- i.e., how each unique concept may be referenced by either humans or software. In EDCS Version 3.0, three mechanisms exist for denoting EDCS concepts: the symbolic constant, the label, and the code. These are equivalent in purpose to the "label", name, and code, respectively, in the EDCS Version 2.x.
The EDCS Version 3.0 symbolic constant is equivalent to the EDCS
Version 2.x "label", and remains a constant that can be used
by programmers as a shorthand for the code.
-- The EDCS Version 3.0 symbolic constant, like the EDCS Version 2.x
"label", is a C-language specific construct, which includes
one or more prefixes, in order to ensure uniqueness in the namespace of the
C-language compiler. Therefore, for example, EUC_METRE and ECC_METRE are unique
symbolic constants that denote concepts in two different Dictionaries (the Unit
and Classification Dictionaries, respectively). Those concepts may have the
same value for their label.
The EDCS Version 3.0 label is equivalent to the EDCS Version 2.x name.
It is human-readable, but follows particular syntactic rules and can be machine parsed.
The corresponding symbolic constant is easily derivable from it.
-- It is important to remember that the EDCS Version 3.0 label, like the EDCS
Version 2.x name, is independent of a particular language binding. As such,
it has no prefix. EDCS Version 3.0 labels are only unique within the scope
of their applicable Dictionary. Therefore, a "METER" might be the
value of the label of a concept of measurement, or the value of the
label of a concept of classification, or even both.
The EDCS Version 3.0 code is equivalent to the EDCS Version 2.x
code, however it is always an integer. In the EDCS Version 2.x,
codes were either strings, integers, or the value of a specific enum data type.
-- It is important to keep these differences in code types in mind. EDCS Version
2.x codes for classifications and attributes were character strings; while
for enumerants they were 3-digit non-consecutively assigned positive integers. All
EDCS Version 3.0 codes are positive, non-zero integers that are consecutively
assigned within the scope of an EDCS Dictionary. The code whose value
is the integer 1 will denote different concepts in different EDCS Dictionaries,
just as the label whose value is "METER" will denote different
concepts in different EDCS Dictionaries.
Example concepts from each EDCS Dictionary follow, first stating its label, and then specifying its symbolic constant, and finally specifying its code data type (always fundamentally an integer) and finally its value.
EDCS Dictionaries containing concepts comparable to those in EDCS Version 2.x:
EDCS Dictionaries containing concepts not comparable to those in EDCS Version 2.x:
Units of measure in the EDCS Version 2.x were represented by a set of enumerated values such as EDCS_UNITS_KILOGRAM. In the EDCS Version 3.0, concepts of units of measure have been given their own EDCS Dictionary and a new EDCS Scale Dictionary has been created to support the specification of the scale of the units of measure for an attribute value. Unit and scale labels are prefixed with "EUC_" and "ESC_", respectively, and their codes are represented as positive, non-zero consecutively assigned integers. Both the unit and scale are required in order to fully specify the meaning of the value of many quantitative attributes.
For example, to fully specify the value of the mass of a car, in EDCS Version 2.x the SE_UNITS_ENUM C language enum value of EDCS_UNITS_KILOGRAM would have been used. In the EDCS Version 3.0, the same information would be specified using two separate, orthogonal concepts: EUC_GRAM and ESC_KILO, where EUC_GRAM specifies the "gram" unit of measure and ESC_KILO specifies the "kilo" scale of that unit of measure. Changes in the SEDRIS DRM Version 3.1 accommodate the EDCS Version 3.0 requirement for representing these two separate concepts.
Included in the EDCS Version 3.0 is a new EDCS Dictionary called the Unit Equivalence Class Dictionary. This dictionary is used to define equivalence classes such as "LENGTH" and all of the units of measure that are its members. Attribute values, specified in terms of two units of measure in the same equivalence class can be converted between one another using the EDCS Version 3.0 API function EDCS_ConvertQuantityValue.In EDCS Version 3.0, these concepts have been moved into the EDCS Attribute Value Metadata Dictionary, where they can be applied to attributes of any type. The labels of attribute value metadata concepts are prefixed with "EMC_" and their codes are represented as positive, non-zero, consecutively assigned integers. Changes in the SEDRIS DRM Version 3.1 accommodate the EDCS Version 3.0 requirements for representing attribute value metadata concepts separate from attribute value concepts. For example:
SE_PROPERTY_DATA_VALUE value;
value.value_type = SE_PDV_ENUMERANT_CODE;
value.u.eac_enum_value = SE_PROP_VAL_AGC__DATA_WITHHELD;
[SDK Version 3.1 with EDCS Version 3.0]
SE_Property_Data_Value value;
value.value_type = SE_PDV_METADATA_CODE;
value.u.em_code = EMC_VALUE_WITHHELD;
SE_PROPERTY_CHARACTERISTIC_TYPE_ENUM meaning = SE_MAX_VALUE;
[SDK 3.1 with EDCS Version 3.0]
EDCS_Metadata_Code meaning = EMC_MAXIMUM_VALUE;
Due to the changes in the data types of codes from the EDCS Version 2.x to EDCS Version 3.0, the API has changed considerably. Whereas in EDCS Version 2.x most functions took pointers to EDCS_CC_IDs and EDCS_AC_IDs (strings), in EDCS Version 3.0 the comparable functions now take the actual value of the codes (integers; no pointers involved). Special-purpose code comparison functions are no longer necessary, since the codes are all simply integers and can be compared using the == operator. There are comparison functions for each EDCS Dictionary that takes pointers to codes that can be used in the C library qsort operation.
The following table lists all replaced EDCS Version 2.x functions and their equivalent EDCS Version 3.0 functions, or otherwise equivalent operations:
For a complete list and description of the EDCS Version 3.0 API functions (there are many more than are listed above), see the EDCS 3.0 Functions HTML documentation.
Concepts encoded using the EDCS Version 2.x are encoded differently using the EDCS Version
3.0, however essentially all concepts supported by EDCS Version 2.x are also supported by
EDCS Version 3.0, albeit sometimes using a combination of several EDCS Version 3.0 "atomic" concepts.
The tables at the end of this section document the mapping of concepts from EDCS Version 2.x to EDCS Version 3.0. In the significant majority of cases, the concept mapping is one-to-one and direct. In some cases, however, the mapping is more complex.
These tables document the mappings for each of the concept types in EDCS Version 2.x: classifications, attributes, enumerants, and units of measure. In addition to listing the "EDCS 2.9 Code" and "EDCS 2.9 "Label"" for each concept, each table includes the columns "EDCS 3.0 Concept Mapping Type", "EDCS 3.0 Concept Mapping Information", and "Additional Notes".
The Concept Mapping Types are as follows:
This section describes the EDCS Version 2.x to EDCS Version 3.0 Mapping API functions, data structures, and use examples. The implementation of this mapping API is not included by default with the EDCS distribution but can be downloaded separately at www.sedris.org.
1. Mapping API Functions
|