1. Introduction
2. Migration Tools
3. Build Environment Changes
4. File Renames, Reorganization, Deletions, and Additions
5. Data Representation Model (DRM) Changes, including Class and Constraint Changes
6. Environmental Data Coding Specification (EDCS) Changes
7. Spatial Reference Model (SRM) Changes
8. Read/Write API Changes

Introduction

This migration document describes the required changes to migrate applications developed using SEDRIS SDK Release 3.0.x to SEDRIS SDK Release 3.1. New SEDRIS SDK users do not need to read this document.

For general information about this release, where to obtain it, and items that require specific attention, see the Release Notes.

For help with the migration process or other questions and comments please send email to help@sedris.org. If you are an associate, please send email to se-coders@sedris.org.

Return to: Top

Migration Tools

This release includes a name replacement Perl script (name_change.pl) that can help users to replace old names in their source code (i.e. function names, data type names, etc.) with the new ones. This script covers most of the cases where there is a one-to-one mapping. However, there are cases where manual editing of the source code will be required. In addition, the script can be customized to map user-defined types. Please read the Name Change script Readme file for more information.

Return to: Top

Build Environment Changes

This section describes the changes to the build environment.

• The following compilers are now supported:
  • Sun 5.2. More information...
  • GCC 3.0.1
• Added capability to build a single SEDRIS lib that contains all the component libraries. More information...
• Changed the default build mode from STD to OPT
• EGCS compiler is no longer supported

Return to: Top

File Renames, Reorganizations, Deletions, and Additions

This section describes the changes to the source tree structure and file names. This information is only relevant if you are using a source code distribution.

• Changed the source tree structure by completely separating the source code from the generated object code, libraries and executables. The object code generated during a build will no longer be embedded in the source tree, instead it will be stored in a separate "object" directory tree. The changes to the top level directories are as follows:

  Old	New
  - libsrc - templates - apps - transmittals - docs	- src/lib - src/template - src/apps - transmittal - docs




• Renamed the "conversions" directory to the "srm" directory

• Renamed the "data_model" directory to the "drm" directory and replaced prefix "se_" by "drm_" for all files in this directory

• Collapsed "STF_Map", "STF_System", "STF_Transmittal", "stf_api" sub-directories to a single "stf" directory

• In the "stf_api" directory added sub-directories "zlib" and "guid"

• Removed the "unsupported", "support", "dynamic", and "debug" directories.

Return to: Top

Data Representation Model (DRM) Changes, including Class and Constraint Changes

This section summarizes the major changes to the DRM technology component. For detailed information on DRM type and function changes, see Migration Guide - DRM and DRM API. For further information on class field mappings, other individual class changes, and constraint changes, see Migration Guide - Classes.

The Relevant SEDRIS Change Requests (SCR) applied to this release are discussed below.

1. SE_CORE-165A

   • The formal <Image Mapping Function>, <Color>, <Spatial Domain>, and <Classification Data> components of <Feature> have been moved down to the <Primitive Feature> and the <Aggregate Feature> classes, so as to remove them from the <Feature Model Instance> class, for which they have no valid application.

   • The formal <Spatial Domain> component of <Geometry Hierarchy> was moved to <Aggregate Geometry> and <Property Grid Hook Point>.

   • The formal <Image Mapping Function>, <Color>, <Light Rendering Properties>, and <Rendering Properties> components of <Geometry Model Instance> were removed.

2. CORE-178B

   • The SE_ID ID field was removed from the following classes:

     • <Model>
     • <Image>
     • <Attribute Set Table Group>
     • <Color Table Group>
     • <Sound>
     • <Symbol>

   • The sound_id field was removed from <Sound Instance> and the image_id field was removed from <Image Mapping Function>.

   • The SE_IMAGE_SIGNATURE_IMAGE_ID entry in SE_IMAGE_SIGNATURE_ENUM was replaced by SE_IMG_SIG_IMAGE_INDEX. All fields within <Image>, <Image Lookup>, or SE_Desired_Image_Parameters that referred to image_id were renamed to refer to image_index.

   • The <<Unique ID Field>> constraint was updated to apply only to the remaining classes with ID fields.

   • The Level 1 API functions SE_ModelIDFromGMI() and SE_ModelIDFromFMI() were removed.

3. E&S-026A

   • The class <Presentation Domain> has been added to the DRM, and added as an optional formal component to the following classes.

     • <Aggregate Feature>
       Added to provide new functionality, allowing data providers of feature data to convey presentation domain information.

     • <Aggregate Geometry>
       Added to provide new functionality, allowing data providers of geometry data to convey presentation domain information at a high level and let it be inherited down the tree, rather than "paying" for it by specifying it more than once in individual fields at the primitive and attribute level.

     • <Attribute Set>
       Added to provide new functionality, allowing data providers to convey presentation domain information at a high level within the <Attribute Set> and let it be inherited down the tree, rather than "paying" for it more than once by specifying it in individual fields at the primitive and attribute level.

     • <Colour>
       Replaces the presentation_domain field, provided the field value was not previously an empty set.

     • <Colour Table>
       Replaces the presentation_domain field, provided the field value was not previously an empty set.

     • <Image>
       Added to provide new functionality, allowing data providers of geo-specific <Image> instances that are not referenced by any <Image Mapping Function> to specify their presentation domain, if they are specific to one.

     • <Image Mapping Function>
       Replaces the presentation_domain field, provided the field value was not previously an empty set.

     • <Primitive Feature>
       Added to provide new functionality, allowing data providers of feature data to convey presentation domain information.

     • <Primitive Geometry>
       Added to provide new functionality, allowing data providers of geometry data to convey presentation domain information at a high level and let it be inherited down the tree, rather than "paying" for it by specifying it more than once in individual fields at the primitive and attribute level.

   • The inheritance rules for <Colour> and <Rendering Properties> were revised to accomodate the changes wrought with the addition of the <Presentation Domain> class. See Part 4, Volume 9: Attribute Inheritance and Context Technical Guide for details of the various inheritance rules.

4. E&-101
   This SCR explicitly specified that the former SE_IMAGE_SIGNATURE_BUMP image signature represents bump map height, and added a second bump map signature for UV component representation.

5. LMIS-119
   This SCR was absorbed into the general overhaul of string fields described by PDB-016D and PDB-021C, which replaced all the file_name / file_path combinations of fields with URNs.

6. LMIS-122A

   • Syntactically speaking, <Feature Hierarchy> is now an optional rather than a mandatory formal component of <Feature Model>, although this is semantically valid only within cases permitted by the applicable constraint (see below).

   • Syntactically speaking, <Geometry Hierarchy> is now an optional rather than a mandatory formal component of <Geometry Model>, although this is semantically valid only within cases permitted by the applicable constraint (see below).

   • The <<Non-Empty Model>> constraint has been updated to accomodate the new definition of an "empty" <Model>. Please refer to the <<Non-Empty Model>> constraint for more details.

7. PDB-016
   The SE_STRING type was replaced by 3 types, where the specific type in use within the DRM depends on the context in which it appears: EDCS_String, SE_String, and SE_URN, the last of which only represents URNs. The first two are used for human-readable string data, and have been augmented by the addition of locale fields specifying the country and language in use, and the underlying character types now use UTF-8 encoding. ASCII is a subset of UTF-8 so forward mapping is not difficult for current data providers. UTF-8 provides the additional functionality of supporting non-Latin character sets, including multibyte characters.

8. PDB-020
   Various EDCS attributes were dropped from EDCS as being too specific to the SEDRIS DRM. Consequently, the SE_Index_Code and SE_Variable_Code types have been added to the DRM to support these codes, and most occurrences of EDCS Attributes in the DRM have been replaced by the tagged union data structure SE_Element_Type, allowing the use of EDCS_Attribute_Code, SE_Index_Code, or SE_Variable_Code as needed so that there is no loss of functionality.

9. PDB-023
   The <<Axis Type Restrictions>> constraint was revised to spell out the restrictions on spatial <Axis> instances previously captured directly in the class definitions, as well as enforcing the semantic constraints on the type and EQ bindings for attributes (EDCS_Attribute_Code, SE_Index_Code, and SE_Variable_Code). The monotonicity constraints for various <Axis> subclasses were slightly relaxed (both increasing and decreasing are now allowed).

   In addition and most noticeably, all values_are_ints fields within <Axis> classes, together with numeric value arrays, first value fields, and spacing fields were replaced by SE_Property_Data_Value fields.

10. PDB-024
    The SE_PROPERTY_CHARACTERISTIC_TYPE_ENUM was removed, having been superceded by the addition of the EM dictionary to EDCS. EDCS_Metadata_Code replaces its previous occurrences in the DRM, and in addition has been given a new entry within SE_Property_Data_Value.

11. PDB-025
    Structured data types for intervals were added to EDCS, explicitly distinguishing various flavours of open and closed intervals. With the addition of these types, <Interval Axis> and <State Data> were revised to use these types via SE_Property_Data_Value. This removes the restrictions to which those classes were previously subject, regarding semi-open intervals.

12. PDB-026
    The various changes wrought with the changeover of EDCS to align with the ISO committee draft (CD) standard made it necessary to revise all classes referring to ECs to enable them to provide multiple qualifying <Property Value> instances. See individual classes in Migration Guide - Classes for details.

13. PUBLIC-115
    All concrete <Location> subclasses were revised to directly reference the corresponding SRM coordinate data structures rather than replicating their structure.

14. SAIC-164E

    • See the removed classes segment of Migration Guide - Classes, regarding <Feature Edge Terminal Node> and its sub-classes, <Feature Edge Starting Node> and <Feature Edge Ending Node>.

    • The <Edge Direction> class was added as a link class to the one-way association from <Feature Node> to <Feature Edge>. The same was done for the relationships between <Geometry Edge> and <Geometry Node>.

    • See the removed classes segment of Migration Guide - Classes, regarding <Contained Within Feature Face> and <Contained Feature Node>, as well as <Contained Within Geometry Face> and <Contained Geometry Node>.

    • See the removed classes segment of Migration Guide - Classes, regarding <Bordered Feature Face> and <Bordered Geometry Face>.

    • The one-way aggregation from <Feature Face Ring> was changed to a one-way association. The same was applied to the relationships between <Geometry Edge> and <Geometry Face>.

    • The <Union Of Feature Topology> class was modified as follows.

      • Made <Union of Feature Topology> a subclass of <Feature Topology Hierarchy>, allowing a <Union of Feature Topology> instance to be a two-way component of an <Aggregate Feature> instance.

      • Moved the feature_topology_level field from the <Aggregate Feature> class to the <Feature Topology Hierarchy> class, and added it to the <Feature Topology Hierarchy> class.

      • Removed the independent_topologies field from the <Aggregate Feature> class. (Having a component <Feature Topology Hierarchy> instance now identifies an <Aggregate Feature> as having an independent topological complex.)

    • The relationships between each subclass of <Primitive Feature> and the corresponding subclass of <Feature Topology> changed from aggregation to two-way association relationships. See the entries for each subclass of <Primitive Feature> within Migration Guide - Classes.

    • The following Level 1 API functions were removed and replaced by the function SE_GetNthComponentOfType().

      • SE_GetEndingNodeForEdge()
      • SE_GetStartingNodeEdge()

15. SAIC-168
    All one-way aggregations in the DRM were changed to two-way aggregations.

16. SAIC-169A
    29 link classes were removed without loss of functionality and consolidated into other link classes. The following is a description of those changes.

    • The <Geometry Instance Template Index> and <Feature Instance Template Index> classes were consolidated into a single link class, <Model Instance Template Index>.

    • The <Base Hierarchy Data>, <Feature Hierarchy Data>, and <Geometry Hierarchy Data> classes were consolidated into a single link class, <Hierarchy Data>.

    • The <Base Oct Tree Data>, <Feature Oct Tree Data>, and <Geometry Oct Tree Data> classes were consolidated into a single link class, <Oct Tree Data>.

    • The <Edge Direction>, <Feature Edge Direction>, <Geometry Edge Direction>, <Feature Ring Edge Direction>, and <Feature Ring Edge Direction> classes were consolidated into a single class, <Edge Direction>. Please see SCR SAIC-164 for further changes in the relationships of <Edge Direction>.

    • The link classes <Base Quad Tree Data>, <Feature Quad Tree Data>, and <Geometry Quad Tree Data> were consolidated into a single link class, <Quad Tree Data>.

    • The link classes <Base Spatial Index Data>, <Feature Spatial Index Data>, <Geometry Spatial Index Data>, and <Feature Topology Spatial Index Data> were consolidated into a single link class, <Spatial Index Data>.

    • The link classes <Base State Data>, <Feature State Data>, and <Geometry State Data> were consolidated into a single link class, <State Data>.

    • The <Base Classification Data>, <Feature Classification Data>, <Geometry Classification Data>, and <Classification Data> classes were consolidated into a single class, <Classification Data>.

    • The <Base Perimeter Data>, <Feature Perimeter Data>, <Geometry Perimeter Data>, <Feature Topology Perimeter Data>, and <Sound Perimeter Data> classes were consolidated into a single class, <Perimeter Data>.

    • The <Base Level Of Detail Data>, <Feature Level Of Detail Data>, <Geometry Level Of Detail Data>, and <Level Of Detail Data> classes were consolidated into a single class, <Base Level Of Detail Data>, merging with the previous <Base Level Of Detail Data> class. All the sub-classes of the previous <Base Level Of Detail Data> class, now subclasses of the conjoined <Base Level Of Detail Data> class, became link classes.

    • The <Base Time Constraints Data>, <Feature Time Constraints Data>, <Geometry Time Constraints Data>, and <Time Constraints Data> classes were consolidated into a single class <Time Constraints Data>.

Return to: Top

Environmental Data Coding Specification (EDCS) Changes

This section summarizes the major changes to the EDCS technology component. For detailed information on EDCS changes see Migration Guide - EDCS.

1. There is a new set of primitive types that are now specifically defined for the EDCS API whose names are compliant with the ISO naming convention and start with the "EDCS_" prefix (e.g., EDCS_Short_Integer and EDCS_FALSE).

2. Changed the representation of codes and symbolic constants (previously known as "labels"). The new EDCS Classification, Attribute and Enumerant codes are now positive, non-zero integers that are consecutively assigned. Symbolic constants are still strings but their prefix has changed to "ECC_" for Classifications, "EAC_" for Attributes, and "EEC_" for Enumerants.

3. Due to change in the representation of codes the API function parameter type have changed.

4. Added new dictionaries for Attribute Value Metadata, Unit, and Scale:

   • The EDCS_UNITS_ENUM type was replaced by two mechanisms, EDCS_Unit_Code and EDCS_Scale_Code.

   • Some enumerations had metadata enumerants. Those enumerants have been mapped to entries in the Attribute Value Metadata dictionary. The SE_Property_Data_Value structure has changed to accommodate meta-values.

Return to: Top

Spatial Reference Model (SRM) Changes

This section summarizes the major changes to the SRM technology component. For detailed information on SRM changes see Migration Guide - SRM.

1. There is a new set of primitive types specifically defined for the SRM API whose names are compliant with the ISO naming convention and start with the "SRM_" prefix (e.g., SRM_Short_Integer and SRM_FALSE).

2. In general, the words "Coordinate System" are replaced with the acronym SRF.

Return to: Top

Read / Write API Changes

This section summarizes the major changes to the Read / Write API technology component. For detailed information on API changes see Migration Guide - API.

1. CORE-166
   Renamed SE_ReferencePublishedObject() to SE_GetUnresolvedObjectFromPublishedLabel()

2. CORE-168
   SE_CloseTransmittal() now has additional checks to ensure that the given transmittal has been left with a root object after being opened for a CREATE or UPDATE session, and that its version fields match the API implementation in use.

3. CORE-169
   The SE_AddToTransmittal() function was removed, the operation having been absorbed into SE_CreateObject(), which now takes a transmittal argument in place of the former implementation_identifier argument. The SE_AddToTransmittal() was removed from the API because the objects are now committed to the transmittal upon their creation.

4. CORE-172
   The following level 1 utilities now take an SE_Store as an argument rather than a buffer, so that the store rather than the user manages the memory.

   • SE_ImageNameFromImageMappingFunction()
   • SE_ModelNameFromFMI()
   • SE_ModelNameFromGMI()
   • SE_SoundNameFromSoundInstance()

5. CORE-173
   SE_GetUniqueTransmittalID() was added to the Level 0 API.

6. CORE-174
   SE_GetErrorDescription() was added to the Level 0 API.

7. The SE_GetRearrangedImageData() now requires that all the unused "number of bits" for the input parameters be zeroed out for the function to behave correctly. This was not required previously.

8. PDB-022
   SE_DATA_TABLE_EXTENTS was renamed and required so that instead of containing separate start and stop array fields, it contains a single SE_Index_Range array. The level 1 utility functions used to allocate and set variables of this type from the data in a <Data Table> instance were correspondingly renamed and revised.

9. PUBLIC-116
   This SCR specified a general scrub of the search mechanism (both boundary and filter), mostly with regard to names and documentation.

   Various renames were made for clarity and to comply with the naming policy for types and functions. The SE_OBJECT_OR search macros were removed, since they are redundant with the SE_OR macros.

   The FIELD_MATCH macros were given additional arguments to cope with the fact that SE_DRM_Class enumerants and the corresponding field types are now capitalized differently (and therefore a single argument cannot now be used to specify both within the context of a macro).

   Various 1-shot utility functions and macros and utility iterator-creation functions and macros were updated to add ITR behaviour parameters where they were not already available.