DataMuseum.dk

Presents historical artifacts from the history of:

Rational R1000/400 Tapes

This is an automatic "excavation" of a thematic subset of
artifacts from Datamuseum.dk's BitArchive.

See our Wiki for more about Rational R1000/400 Tapes

Excavated with: AutoArchaeologist - Free & Open Source Software.


top - download
Index: ┃ T V

⟦a7a4fde66⟧ TextFile

    Length: 40326 (0x9d86)
    Types: TextFile
    Names: »V«

Derivation

└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
    └─ ⟦fc9b38f02⟧ »DATA« 
        └─⟦9b46a407a⟧ 
            └─⟦12c68c704⟧ 
                └─⟦this⟧ 
└─⟦5f3412b64⟧ Bits:30000745 8mm tape, Rational 1000, ENVIRONMENT 12_6_5 TOOLS 
    └─ ⟦91c658230⟧ »DATA« 
        └─⟦458657fb6⟧ 
            └─⟦220843204⟧ 
                └─⟦this⟧ 

TextFile

with Action;
with Calendar;
with Cmvc_Implementation_Errors;
with Directory;
with Io;

package Cmvc_Implementation is
    pragma Subsystem (Tools);
    pragma Module_Name (4, 3760);

    -- CMVC is based on the notion of elements.  An element is a logical
    -- entity that encapsulates changes within objects over time.  Any
    -- object class that has a text representation and conversion functions
    -- can be managed by CMVC.  Elements have an internal name, supplied
    -- when the element is created.  This is the name used for all CMVC
    -- operations.  There is an external name associated with each version
    -- set, which is used for all copy in and out operations.

    -- Each version of an element is a snapshot of that element.  It
    -- represents a physical realization of that element at some point in
    -- its history.  A Gamma version has this property.  Each successive
    -- version is a new generation of the element.

    -- A view is defined to mean a snapshot of a collection of elements; it
    -- calls out specific versions of specific elements.  This isn't
    -- necessarily a physical representation.  In other words, this isn't a
    -- world but a more abstract concept.

    -- A version set is a time ordered set of versions for one element.
    -- There is a straight line of descent; each version was created from
    -- its parent by changing the parent.  There is no skipping; every
    -- generation of the element is represented. Each version set for an
    -- element represents a different time line, and each can be reserved
    -- independently.  Only one version in a version set can be checked
    -- out, and this is the newest version.  The version set is optionally
    -- named, which is useful for iterating over the sets.  The version set
    -- also maintains the external name for this set of versions of the
    -- element.

    -- A configuration is a realization of a view. A configuration can have
    -- a directory name, which means there is some representation on the
    -- disk for it. There are two types of configurations, release
    -- configurations and working configurations.  A working configuration
    -- is one in which versions can be changed.  A release configuration
    -- specifies a set of versions which are frozen; neither the release
    -- configuration nor the versions specified can be changed.
    -- Configurations are named by the user.

    -- In many cases software must run on various targets.  It is often the
    -- case that most of the elements are the same, but a few may be
    -- different to account for the differences in the targets.  It is
    -- desirable to capture this information in order to allow simultaneous
    -- independent changes to the elements that are different, while
    -- controlling access to the elements that are the same.  Another
    -- common scenario is the need to have two people work on one element
    -- in parallel for some time, then merge the changes together. The
    -- process of splitting elements and operating on them is called
    -- maintaining varying lines of descent. These variants branch out from
    -- some line, and may rejoin later. Branching out is done using create;
    -- bringing two alternate lines together is done using merge. In CMVC,
    -- alternate lines of descent is accomplished by using version sets and
    -- configurations.  Each version set is a line of descent for some
    -- element.  Each configuration selects at most one version set for an
    -- element.  Configurations that refer to the same version set are
    -- linked; the element has one reservation across all such
    -- configurations, and can only be changed serially.  If the
    -- configurations refer to different version sets for an element, the
    -- element can be reserved independently.

    -- There is a database for each set of related configurations.  The
    -- database must be provided to each operation discussed below.

    No_Such_Generation  : exception;
    No_Such_Version_Set : exception;
    No_Such_Element     : exception;
    Bogus_Parameters    : exception;
    Unknown_Error       : exception;

    -- The above are the only exceptions propagated out of this package.
    -- Unknown_error is raised for internal errors and unexpected errors
    -- propagated out of other packages.  Bogus_Parameters is raised when
    -- the parameters make no sense, such as when configurations from one
    -- database are mixed with elements from another.

    subtype Library_Name is String;
    subtype History_File is String;

    subtype Error_Status is Cmvc_Implementation_Errors.Status;
    subtype Error_Msg    is String;

    function Is_Bad (Status : Error_Status) return Boolean
        renames Cmvc_Implementation_Errors.Is_Bad;

    function Error_Msg_Of (Status : Error_Status) return Error_Msg;

    ---------------------------------

    -- Note: values of the following types can be reliably compared for
    -- equality using "=" only if there is one database handle being used
    -- in some job for one database.  If this can't be guaranteed, the
    -- name should be extracted and compared.  If it is possible that
    -- different databases are in use, then the database name should also be
    -- extracted and compared.


    -- There is a database for each set of related configurations.

    type Database is private;
    function Nil                    return Database;
    function Is_Nil (Db : Database) return Boolean;

    type Configuration is private;
    function Nil                             return Configuration;
    function Is_Nil (Config : Configuration) return Boolean;

    type Element is private;
    function Nil                     return Element;
    function Is_Nil (Elem : Element) return Boolean;

    type Element_Class is
        record
            Class    : Directory.Class;
            Subclass : Directory.Subclass;
        end record;
    type Version_Set is private;
    function Nil                        return Version_Set;
    function Is_Nil (Set : Version_Set) return Boolean;

    subtype Generation is Natural;
    function Nil          return Generation;
    function Last_Version return Generation;

    -- Last_Version returns a value that stands in for whatever the newest
    -- generation in the version set is.  It is not the actual generation
    -- of the newest version

    package Database_Operations is
        function Name_Of (Db : Database) return String;

        procedure Open (Db_Name   :     String;
                        Action_Id :     Action.Id;
                        Db        : out Database;
                        Status    : out Error_Status);

        procedure Open (Db_Object :     Directory.Object;
                        Action_Id :     Action.Id;
                        Db        : out Database;
                        Status    : out Error_Status);

        procedure Create (Db_Name          :     String;
                          Action_Id        :     Action.Id;
                          Db               : out Database;
                          Status           : out Error_Status;
                          Dont_Keep_Source :     Boolean := False);

        procedure Close (Db             :     Database;
                         Status         : out Error_Status;
                         Prevent_Commit :     Boolean := False);


        -- If dont_keep_source is true, no source differentials are kept in
        -- the database.  This means versions cannot be retrieved from the
        -- database, and that the merge command depends on external objects
        -- versus internal information.  It is set to true to save disk
        -- space and to speed up check in.

        procedure Expunge (Db : Database; Status : out Error_Status);

        -- Removes all elements and version sets not referenced by a
        -- configuration.
    end Database_Operations;

    package Configuration_Operations is
        function Name_Of     (Config : Configuration) return String;
        function Database_Of (Config : Configuration) return Database;

        subtype Configuration_Object is Directory.Object;
        function Is_Configuration_Object
                    (Obj : Configuration_Object; Action_Id : Action.Id)
                    return Boolean;


        procedure Open (Config_Name :     String;
                        Config      : out Configuration;
                        Status      : out Error_Status;
                        Db          :     Database);

        procedure Open (Obj       :        Configuration_Object;
                        Action_Id :        Action.Id;
                        Db        : in out Database;
                        Config    : out    Configuration;
                        Status    : out    Error_Status);

        -- Return a handle to a configuration.  The configuration must exist.
        -- This handle is used for most interesting element operations.

        procedure Create (Config_Name      :     String;
                          Config           : out Configuration;
                          Status           : out Error_Status;
                          Golden_Config    :     Configuration := Nil;
                          Default_Library  :     String        := "";
                          Version_Set_Name :     String        := "";
                          Initial          :     Configuration := Nil;
                          Make_Copies      :     Boolean       := False;
                          Is_Release       :     Boolean       := False;
                          Db               :     Database);

        -- Create a new configuration.  It can optionally be initialized.

        -- If make_copies is true, new version_sets are made in each of the
        -- elements selected by the initial configuration, which are then
        -- initialized with the version selected by the initial
        -- configuration.  These version sets are given the name provided.
        -- If no name is provided, the version sets are given the
        -- configuration name.

        -- If make_copies is false, the new configuration
        -- references all the same version sets and versions as the initial
        -- configuration, and the version_set_name parameter is ignored. In
        -- other words, it is linked. If is_release is true, the new
        -- configuration is frozen (is a release).

        -- Golden_Config is the name of a configuration that is to be
        -- copied into automatically whenever an element is checked in.
        -- The intent is to allow the user to keep a current copy of
        -- everything.  This package doesn't actually do the copying, but
        -- makes available the information to the command packages.

        -- Default_Library is the name of the library to be used by default
        -- for this configuration.  It is used in all commands that require
        -- a library, but are given the null string.

        function Golden_Config_Of (Config : Configuration) return Configuration;

        function Default_Library_Of (Config : Configuration) return String;

        procedure Create_Config_Object (Name   :     String;
                                        Config :     Configuration;
                                        Status : out Error_Status);

        -- Create a configuration object with name 'name'.  This object can be
        -- used to get a configuration handle.  If a configuration object
        -- editor is ever provided, it would accept one of these.

        procedure Delete (Config         :     Configuration;
                          Status         : out Error_Status;
                          Delete_Release :     Boolean := False);

        -- Delete a configuration.  The elements and version sets are not
        -- deleted.  Delete_release must be true to delete a release
        -- configuration.

        function Is_Release (Config : Configuration) return Boolean;

        -- Returns true if the argument is a release configuration.

    end Configuration_Operations;

    package Element_Operations is
        function Name_Of (Elem : Element) return String;


        procedure Open (Element_Name :     String;
                        Elem         : out Element;
                        Status       : out Error_Status;
                        Db           :     Database);

        -- Gets a handle for an element.  This handle is used to look at the
        -- various version sets for the element.

        procedure Create (Element_Name      :     String;
                          Config            :     Configuration;
                          Class             :     Element_Class;
                          External_Name     :     String;
                          Elem              : out Element;
                          Status            : out Error_Status;
                          Initial_Value_Set :     Version_Set := Nil;
                          Initial_Value     :     Generation  := Nil;
                          Version_Set_Name  :     String      := "";
                          Dont_Keep_Source  :     Boolean     := False);

        procedure Create (Element_Name      :     String;
                          Db                :     Database;
                          Class             :     Element_Class;
                          External_Name     :     String;
                          Version_Set_Name  :     String;
                          Elem              : out Element;
                          Status            : out Error_Status;
                          Initial_Value_Set :     Version_Set := Nil;
                          Initial_Value     :     Generation  := Nil;
                          Dont_Keep_Source  :     Boolean     := False);

        procedure Create (Element_Name         :     String;
                          Config               :     Configuration;
                          Class                :     Element_Class;
                          External_Name        :     String;
                          Elem                 : out Element;
                          Status               : out Error_Status;
                          Initial_Value_Object :
                             Directory.Object                := Directory.Nil;
                          Version_Set_Name     :     String  := "";
                          Dont_Keep_Source     :     Boolean := False);

        procedure Create
                     (Element_Name         : String;
                      Db                   : Database;
                      Class                : Element_Class;
                      External_Name        : String;
                      Version_Set_Name     : String;
                      Elem                 : out Element;
                      Status               : out Error_Status;
                      Initial_Value_Object : Directory.Object := Directory.Nil;
                      Dont_Keep_Source     : Boolean := False);

        -- Create a new element.  The new element can be inserted into a
        -- configuration (using the first procedure).  An empty version set is
        -- created for the element.  In the case that a configuration is
        -- supplied, the version set name defaults to the configuration name.
        -- In the database case, the version set name must be supplied.  The
        -- version set is optionally initialized by copying the contents of a
        -- version into it (as generation 1). The configuration must be a
        -- working configuration. Path_from_library specifies a string that is
        -- to be prepended to the element name and appended to the library name
        -- when the element is copied out of the database. Initial_value_object
        -- is the name of some directory object that is to be used as an
        -- initial value.

        procedure Delete (Elem   :     Element;
                          Config :     Configuration;
                          Status : out Error_Status);

        -- Delete the element from the configuration.  The element is not
        -- deleted from the database.  The configuration must be a working
        -- configuration.

        procedure Delete (Elem : Element; Status : out Error_Status);

        -- Delete the element from all working configurations in the database.
        -- This operation ignores release configurations.

        procedure Add (Elem   :     Element;
                       Status : out Error_Status;
                       Config :     Configuration);

        -- This operation adds an element (and a version set) to a working
        -- configuration.  There must be only one version set associated with
        -- the element to use this operation.

        function Is_In_Configuration
                    (Elem : Element; Config : Configuration) return Boolean;

        -- Returns true if some version set of the element is referenced by the
        -- configuration

        function Class_Of (Elem : Element) return Element_Class;

        -- return the class data for an element
        function Saves_Source (Elem : Element) return Boolean;

        -- Is source saved for this element?

    end Element_Operations;

    ---------------------------------

    package Version_Set_Operations is
        function Name_Of (Set : Version_Set) return String;

        procedure Open (Set_Name :     String;
                        Elem     :     Element;
                        Set      : out Version_Set;
                        Status   : out Error_Status);

        -- Get a handle on a version set.  This handle is used to traverse
        -- across the versions contained in the set.

        procedure Open (Elem   :     Element;
                        Set    : out Version_Set;
                        Status : out Error_Status;
                        Config :     Configuration);

        -- Get a handle on a version set determined by an element/configuration
        -- pair.

        procedure Create (Set_Name          :     String;
                          Elem              :     Element;
                          External_Name     :     String;
                          Set               : out Version_Set;
                          Status            : out Error_Status;
                          Initial_Value_Set :     Version_Set := Nil;
                          Initial_Value     :     Generation  := Nil);

        procedure Create
                     (Set_Name             : String;
                      Elem                 : Element;
                      External_Name        : String;
                      Set                  : out Version_Set;
                      Status               : out Error_Status;
                      Initial_Value_Object : Directory.Object := Directory.Nil);

        -- Create a new version set in some element.  The new version set can
        -- be initialized.

        procedure Add (Set        :     Version_Set;
                       Config     :     Configuration;
                       Status     : out Error_Status;
                       Gen        :     Generation := Last_Version;
                       Replace_Ok :     Boolean    := True);

        -- Add (or replace) a version set to a configuration.  This operation
        -- implies the adding of an element as well, as a version set is
        -- contained within an element.  The configuration must be a working
        -- one.  The configuration is set to refer to the specified version

        procedure Prune (Set              :     Version_Set;
                         Up_To_Generation :     Generation;
                         Status           : out Error_Status);

        -- Throw away the first up to the up_to_generation versions from the
        -- version set.  This operation fails if any configuration references a
        -- version to be discarded.  An iterator exists to help find these
        -- blocking configuration(s).

        procedure Change_External_Name (Set           :     Version_Set;
                                        External_Name :     String;
                                        Status        : out Error_Status);

        -- Modify the name used for the version set.  This name is appended to the
        -- library name to build a complete external name.
        -- Note that this affects all configurations using the version set.

        function External_Name_Of (Set : Version_Set) return String;

        -- Return the path specified when the version set was made.

        function Element_Of (Set : Version_Set) return Element;
    end Version_Set_Operations;

    ---------------------------------

    package Generation_Operations is
        function Generation_Of
                    (Elem : Element; Config : Configuration) return Generation;

        function Generation_Of (Set : Version_Set; Config : Configuration)
                               return Generation;

        -- Get the generation selected by a configuration.

        function First_Generation_Of (Set : Version_Set) return Generation;

        -- Return the generation of the first version for the set.  This is
        -- something other than one after a prune_version_set

        function Last_Generation_Of (Set : Version_Set) return Generation;
    end Generation_Operations;


    package Reservation_Operations is
        procedure Create_From_Db (Set    :     Version_Set;
                                  Where  :     String;
                                  Status : out Error_Status;
                                  Gen    :     Generation := Last_Version);

        procedure Create_From_Db (Set    :     Version_Set;
                                  Where  :     Directory.Object;
                                  Status : out Error_Status;
                                  Gen    :     Generation := Last_Version);
        -- Only works for objects of class 'file'

        procedure Create_From_Db (Set     :        Version_Set;
                                  To_File : in out Io.File_Type;
                                  Status  : out    Error_Status;
                                  Gen     :        Generation := Last_Version);

        generic
            with procedure Put_Line (Text : String);
        procedure Create_From_Db_Generic (Set    : Version_Set;
                                          Status : out Error_Status;
                                          Gen    : Generation := Last_Version);

        procedure Check_Out (Set    :     Version_Set;
                             Gen    : out Generation;
                             Status : out Error_Status;
                             Config :     Configuration;
                             User   :     String := "");

        procedure Check_In (Set            :     Version_Set;
                            Current_Source :     Directory.Object;
                            Gen            : out Generation;
                            Status         : out Error_Status;
                            Config         :     Configuration;
                            User           :     String := "");

        -- Check out (or in) some element.  Since the element is specified
        -- by the version set, the element need not be provided.  Check out
        -- creates a new version.  The configuration is changed to reflect
        -- the use of the new version.  Check in verifies the same
        -- configuration is being used.  The command package can check to see
        -- if the user doing the check in is the same one that did the
        -- check out.

        -- Check out returns the generation for the new copy.  The
        -- generation can be used to locate a copy of the element on the
        -- disk somewhere by using the last_known_object history item. The
        -- application must copy this object to the destination.  If the
        -- last_known_object is Nil, the application should request a copy
        -- to built out of the database, supplying the destination
        -- location.

        -- Check in wants the directory.object of the item being checked
        -- in. It uses this to compute the differentials, and also saves it
        -- in the database (for passing to the next check out).  It returns
        -- the generation for any later processing that might be needed
        -- (like compiling or accepting).

        -- The command package check in might also want to check for the
        -- existence of a golden configuration, and copy the object there.
        -- The resulting object would be given to check in. If a golden
        -- configuration is desired, the returned generation should be
        -- accepted into that golden configuration to bring that
        -- configuration up to date.  Remember to do all of the work
        -- required before check in under one action, so the operations can
        -- be backed out if the check in fails.  The most common failure is
        -- 'wrong configuration', so the command package might want to
        -- check that itself first.

        -- The user string is used to mark who did the operation.  If "" is
        -- supplied, the login name is used.

        procedure Abandon_Reservation (Set           :     Version_Set;
                                       Revert_To_Gen :     Generation;
                                       Status        : out Error_Status;
                                       Config        :     Configuration);

        -- Abandon a previous check out operation.  The checked out version
        -- is thrown away.  It is the command package's responsibility to
        -- ensure that the version being reverted to is copied into the
        -- appropriate place.  The configuration is changed to refer to the
        -- specified generation.  Giving 'last_version' as the generation
        -- will revert to the generation before the check out (as it is the
        -- last after the revert).

        procedure Accept_Changes (Set    :     Version_Set;
                                  Result : out Generation;
                                  Status : out Error_Status;
                                  Gen    :     Generation := Last_Version;
                                  Config :     Configuration);

        -- The configuration is changed to refer to the requested version.
        -- The actual generation selected is returned.  If the last version
        -- is checked out, the last - 1 version is returned.  The
        -- configuration is changed to refer to the returned generation.
        -- This operation can be reversed by accepting some other version.
        -- It is the command package's responsibility to actually copy the
        -- data.
    end Reservation_Operations;

    package Merge_Operations is
        procedure Merge_Changes (Elem               :     Element;
                                 From_Config        :     Configuration;
                                 Conflicts_Detected : out Boolean;
                                 Gen                : out Generation;
                                 Status             : out Error_Status;
                                 To_Config          :     Configuration;
                                 List_File          :     String  := "";
                                 Join_Configs       :     Boolean := True;
                                 User               :     String  := "");

        -- The versions in the two version sets selected by elem are merged
        -- together, with the result being left in the to_config.  This
        -- operation always creates a new version.  The to_config is marked
        -- to refer to the new version.  An error occurs if join_configs is true
        -- and from_config doesn't refer to the last version in its version
        -- set, or if to_config doesn't refer to the last version in its set.

        -- This command requires that the two version sets be related,
        -- which means that one of the sets must have been created from the
        -- other. If the split point cannot be located, or never existed,
        -- the merge fails.

        -- If conflicting changes are found, the out parameter
        -- conflicts_detected is set to true.  This by itself is not an error

        -- List_file specifies a text file where the merged result can be
        -- placed.  The merge points in the file are marked in the same
        -- fashion as file_utilities.merge.

        -- Effort_only will do the merge without actually updating the
        -- database.

        -- Join_configs, if true, will change from_config to refer to the
        -- same version set as to_config. In other words, the two
        -- configurations are relinked.
    end Merge_Operations;

    type Basic_History is
        record
            Ever_Checked_Out      : Boolean;
            When_Checked_Out      : Calendar.Time;
            Checked_Out_To_Config : Configuration;
            Ever_Checked_In       : Boolean;
            When_Checked_In       : Calendar.Time;
            Expected_Check_In     : Calendar.Time;
            Edit_Time_Stamp       : Calendar.Time;
            Last_Known_Object     : Directory.Object;
            Split_From_Set        : Version_Set;
            Split_From_Version    : Generation;
            Merged_From_Set       : Version_Set;
            Merged_From_Version   : Generation;
        end record;

    -- Split refers to the source version when the set was created.  merged
    -- refers to a version that was merged into this one.
    -- Checked_out_to_config is nil if the config has been deleted.

    package History_Operations is
        procedure Get (Set     :     Version_Set;
                       History : out Basic_History;
                       Status  : out Error_Status;
                       Gen     :     Generation := Last_Version);

        -- Return the history for some generation in the set.

        function Who_Checked_Out
                    (Set : Version_Set; Gen : Generation := Last_Version)
                    return String;
        function Who_Checked_In
                    (Set : Version_Set; Gen : Generation := Last_Version)
                    return String;

        -- Return the string history items

        procedure Set_Expected_Check_In (Set     :     Version_Set;
                                         To_Time :     Calendar.Time;
                                         Status  : out Error_Status);

        -- Change the expected check in time for the last generation of the set.
        -- It must be checked out.

        procedure Set_Last_Known_Object (Set : Version_Set;
                                         To_Object : Directory.Object;
                                         Status : out Error_Status;
                                         Gen : Generation := Last_Version);

        -- Set the last known object entry in the basic history for the specified
        -- generation.  It need not be checked out.

        function Is_Checked_Out (Set : Version_Set) return Boolean;

        -- simple way to see if a version is currently checked out

        package What_Changed is

            -- Compute the difference between two adjacent versions in a
            -- version set.  Make the text available for reporting.

            type Region_Iterator is private;

            type Region_Record is
                record
                    Newer_Start_Line : Natural;
                    Newer_Stop_Line  : Natural;
                    Older_Start_Line : Natural;
                    Older_Stop_Line  : Natural;
                end record;

            -- The Newer_Start_Line and Newer_Stop_Line are line numbers of
            -- the full text of the newer generation, and do not take into
            -- account insertions, deletions, or replacements from the
            -- older generation.  These line numbers are always
            -- the correct numbers to give to the text extraction
            -- function below.  Line numbers 1..Last_Newer_Line(iter) will
            -- span the entire text of the newer generation.

            -- Older_Start_Line and Older_Stop_Line are line numbers
            -- within regions of difference and are not necessarily
            -- actual line numbers within the older generation, but can
            -- be used by the text extraction function to get the
            -- text of the older generation within the difference regions.
            -- The entirety of the older generation cannot be printed
            -- by this package.

            -- If newer_start > newer_stop, text from older_start to
            -- older_stop has been deleted from between newer_stop
            -- and newer_start.

            -- If newer_start <= newer_stop and
            --      If older_start > older_stop, text between newer_start
            --          and newer_stop has been inserted.
            --  or  If older_start <= older_stop text is being replaced

            -- Line numbers not mentioned in a region are common between the
            -- two generations.


            procedure Initialize (In_Set          : Version_Set;
                                  Result          : out Region_Iterator;
                                  Status          : out Error_Status;
                                  Generation_Pair : Generation := Last_Version);

            -- Compute an iterator for differences between generation and
            -- generation - 1.


            function  Done  (Iter : Region_Iterator) return Boolean;
            function  Value (Iter : Region_Iterator) return Region_Record;
            procedure Next  (Iter : in out Region_Iterator);

            function Last_Newer_Line (Iter : Region_Iterator) return Natural;

            function Text_Of_Newer
                        (Iter : Region_Iterator; Line_Number : Natural)
                        return String;
            function Text_Of_Older
                        (Iter : Region_Iterator; Line_Number : Natural)
                        return String;
        private
            type Region_Iterator_Record;
            type Region_Iterator is access Region_Iterator_Record;
            pragma Segmented_Heap (Region_Iterator);
        end What_Changed;

        procedure Set (From_File : in out Io.File_Type;
                       Set       :        Version_Set;
                       Status    : out    Error_Status);

        -- Copy the text file to the history database, and
        -- associate it with the last version in the version set.  The version
        -- must be checked out and not checked in.

        procedure Append (From_File : in out Io.File_Type;
                          Set       :        Version_Set;
                          Status    : out    Error_Status);

        -- Same as above, only the file is appended instead of replacing.

        procedure Get (To_File : in out Io.File_Type;
                       Set     :        Version_Set;
                       Status  : out    Error_Status;
                       Gen     :        Generation := Last_Version);

        -- Copy the history file from the database into a text file

        procedure Set (From_String :     String;
                       Set         :     Version_Set;
                       Status      : out Error_Status);

        -- Copy the string to the history database, and
        -- associate it with the last version in the version set.  The version
        -- must be checked out and not checked in.  Lines must be separated
        -- by Ascii.Lf

        procedure Append (From_String :     String;
                          Set         :     Version_Set;
                          Status      : out Error_Status);

        -- Same as above, only the string is appended instead of replacing.

        function Get (Set : Version_Set; Gen : Generation := Last_Version)
                     return String;

        -- Return the history info from the database as a string.  Lines
        -- are separated by Ascii.Lf
    end History_Operations;

    package Iterator_Operations is
        type Configuration_Iterator is private;

        procedure Initialize (Db : Database; Iter : out Configuration_Iterator);

        procedure Initialize (Elem :     Element;
                              Iter : out Configuration_Iterator);

        procedure Initialize (Set  :     Version_Set;
                              Iter : out Configuration_Iterator);

        procedure Initialize (Set           :     Version_Set;
                              Up_To_Version :     Generation;
                              Iter          : out Configuration_Iterator);

        procedure Next (Iter : in out Configuration_Iterator);

        function Done (Iter : Configuration_Iterator) return Boolean;

        function Value (Iter : Configuration_Iterator) return Configuration;

        -- Iterate over configurations.  The iterator can be built to iterate
        -- over all configurations, all configurations that reference some
        -- element, all configurations that reference some version set, or
        -- all configurations that reference the first up to n'th version of
        -- a version set.

        type Element_Iterator is private;

        procedure Initialize (Config :     Configuration;
                              Iter   : out Element_Iterator);

        procedure Initialize (Db : Database; Iter : out Element_Iterator);

        procedure Next (Iter : in out Element_Iterator);

        function Done (Iter : Element_Iterator) return Boolean;

        function Value (Iter : Element_Iterator) return Element;

        -- Iterate over elements.  The options are to iterate over all elements
        -- in the database, or to iterate over all elements in a configuration.

        type Version_Set_Iterator is private;

        procedure Initialize (Db : Database; Iter : out Version_Set_Iterator);

        procedure Initialize (Config :     Configuration;
                              Iter   : out Version_Set_Iterator);

        procedure Initialize (Elem : Element; Iter : out Version_Set_Iterator);

        procedure Next (Iter : in out Version_Set_Iterator);

        function Done (Iter : Version_Set_Iterator) return Boolean;

        function Value (Iter : Version_Set_Iterator) return Version_Set;

        -- Iterate over the version sets specified by a configuration, over
        -- the version sets associated with an element, or over all version
        -- sets in the database.  Iterating over version sets is useful for
        -- finding an external name and matching it against the name of
        -- some object, in order to find an element name.  This would be
        -- done by stripping off the library and then comparing what is
        -- left to the external names for the version sets.
    private
        type Ci_Limit_Enumeration   is (All_Configs, Elem_Limit, Set_Limit);
        type Ci_Record (What_Sort : Ci_Limit_Enumeration);
        type Configuration_Iterator is access Ci_Record;
        pragma Segmented_Heap (Configuration_Iterator);


        type Ei_Limit_Enumeration is (All_Elements, Config_Limit);
        type Ei_Record (What_Sort : Ei_Limit_Enumeration);
        type Element_Iterator     is access Ei_Record;
        pragma Segmented_Heap (Element_Iterator);


        type Vsi_Limit_Enumeration is (All_Sets, Config_Limit, Elem_Limit);
        type Vsi_Record (What_Sort : Vsi_Limit_Enumeration);
        type Version_Set_Iterator  is access Vsi_Record;
        pragma Segmented_Heap (Version_Set_Iterator);
    end Iterator_Operations;

private
    type Database_Record;
    type Database is access Database_Record;
    pragma Segmented_Heap (Database);

    type Configuration_Record;
    type Configuration is access Configuration_Record;
    pragma Segmented_Heap (Configuration);

    type Element_Record;
    type Element is access Element_Record;
    pragma Segmented_Heap (Element);

    type Vs_Record;
    type Version_Set is access Vs_Record;
    pragma Segmented_Heap (Version_Set);

end Cmvc_Implementation;