#
        return ""
      }
    }
 
    proc getBuildConfiguration {} {
      #
      # NOTE: See if the "configuration" setting has been overridden by the user
      #       (e.g. on the command line).  This helps control exactly which set
      #       of binaries we are testing (i.e. those built in the "Debug" or
      #       "Release" build configurations).  To override this value via the
      #       command line, enter a command similar to one of the following (all
      #       on one line):
      #
      #       EagleShell.exe -preInitialize "set test_configuration Debug"
      #         -file .\path\to\all.eagle
      #
      #       EagleShell.exe -preInitialize "set test_configuration Release"
      #         -file .\path\to\all.eagle
      #
................................................................................
      #       EagleShell.exe -file .\path\to\all.eagle -preTest
      #         "unset -nocomplain test_configuration"
      #
      if {[info exists ::test_configuration] && \
          [string length $::test_configuration] > 0} then {
        #
        # NOTE: Use the specified test configuration.  The default value used
        #       for this variable is "Release", as set by the test suite itself.

        #
        return $::test_configuration
      } else {
        #
        # NOTE: Normally, we will never hit this case because the value of the
        #       test configuration variable is always set by the test suite
        #       itself; however, it can be overridden using the unset command
................................................................................
        # NOTE: No path is available, return an empty string.  This point
        #       should not be reached.
        #
        return ""
      }
    }
 
    proc joinBuildDirectory { path native year platform configuration } {
      #
      # NOTE: Figure out and then return the fully qualified path to the build
      #       directory based on all the arguments provided by our caller.
      #
      if {$native} then {
        return [file join $path bin $year $platform $configuration]
      } else {
................................................................................
        #       the latest version of MSBuild available and the "test_year" may
        #       need to be adjusted accordingly to actually run the test suite.
        #       Refer to the comments in [getBuildYear] for more information on
        #       how to set this variable.
        #
        set native [hasRuntimeOption native]

        return [joinBuildDirectory [getBuildBaseDirectory] $native \
            [getBuildYear] [getBuildPlatform $native] [getBuildConfiguration]]
      }
    }
 
    proc getBuildFileName { fileName } {
      #
      # NOTE: Returns the specified file name as if it were located in the
................................................................................
        foreach year [getBuildYears] {
          foreach configuration [getBuildConfigurations] {
            tputs $channel [appendArgs \
                "---- checking for System.Data.SQLite build \"" [expr \
                {$native ? "native/" : ""}] $year / $configuration "\"... "]

            set fileName [file nativename [file join [joinBuildDirectory \
                [getBuildBaseDirectory] $native $year [getBuildPlatform \
                $native] $configuration] System.Data.SQLite.dll]]

            if {[file exists $fileName]} then {
              tputs $channel yes\n
            } else {
              tputs $channel no\n
            }
................................................................................
            {temporary true} {varName db} } {
      #
      # NOTE: First, see if our caller has requested an in-memory database.
      #
      set isMemory [isMemoryDb $fileName]

      #
      # NOTE: For now, all test databases used by the test suite are placed into
      #       the temporary directory.  Each database used by a test should be

      #       cleaned up by that test using the "cleanupDb" procedure, below.
      #
      if {!$isMemory && $qualify} then {
        set fileName [file join [getDatabaseDirectory] [file tail $fileName]]
      }

      #
      # NOTE: By default, delete any pre-existing database with the same file
................................................................................
        set flags [combineFlags $flags $::connection_flags]

        tputs $::test_channel [appendArgs \
            "---- combined connection flags are: " $flags \n]
      }

      #
      # NOTE: If our caller specified a SQLiteConnectionFlags, add the necessary
      #       portion of the connection string now.
      #
      if {[string length $flags] > 0} then {
        append connection {;Flags=${flags}}
      }

      #
      # NOTE: If our caller specified an extra payload to the connection string,
      #       append it now.
      #
      if {[string length $extra] > 0} then {
        append connection \; $extra
      }

      #
      # NOTE: Open the database connection now, placing the opaque handle value
................................................................................
      #
      return $db
    }
 
    proc getDbConnection { {varName db} } {
      #
      # NOTE: Refer to the specified variable (e.g. "db") in the context of our
      #       caller.  The handle to the database previously opened by [setupDb]
      #       should be stored there.
      #
      upvar 1 $varName db

      #
      # NOTE: This returns the ADO.NET IDbConnection object instance for the
      #       specified databse handle.  Since getting this object relies upon
      #       Eagle internals, great care should be taken to avoid disposing of
................................................................................
              $db "\", error: " \n\t $result \n]
        }
      }
    }
 
    proc freeDbConnection { {varName connection} } {
      #
      # NOTE: Refer to the specified variable (e.g. "connection") in the context
      #       of our caller.  The opaque object handle for an ADO.NET connection
      #       previously returned by [getDbConnection] should be stored there.

      #
      upvar 1 $varName connection

      #
      # NOTE: Attempt to remove the opaque object handle from the interpreter
      #       now.  This [object dispose] call will not actually dispose of the
      #       underlying object because the +NoDispose flag was set on it during
      #       creation of the opaque object handle.
      #
      if {[info exists connection] && \
          [catch {object dispose $connection} error]} then {
        #
        # NOTE: We somehow failed to remove the handle, report why.
        #
        tputs $::test_channel [appendArgs \
................................................................................
      #
      if {$collect} then {
        collectGarbage $::test_channel
      }

      #
      # NOTE: Refer to the specified variable (e.g. "db") in the context of our
      #       caller.  The handle to the database previously opened by [setupDb]
      #       should be stored there.
      #
      upvar 1 $varName db

      #
      # NOTE: Close the connection to the database now.  This should allow us to
      #       delete the underlying database file.
      #
      if {[info exists db] && [catch {sql close $db} error]} then {
        #
        # NOTE: We somehow failed to close the database, report why.
        #
        tputs $::test_channel [appendArgs \
            "==== WARNING: failed to close database \"" $db "\", error: " \

        #
        return ""
      }
    }
 
    proc getBuildConfiguration {} {
      #
      # NOTE: See if the "configuration" setting has been overridden by the
      #       user (e.g. on the command line).  This helps control exactly
      #       which set of binaries we are testing (i.e. those built in the
      #       "Debug" or "Release" build configurations).  To override this
      #       value via the command line, enter a command similar to one of
      #       the following (all on one line):
      #
      #       EagleShell.exe -preInitialize "set test_configuration Debug"
      #         -file .\path\to\all.eagle
      #
      #       EagleShell.exe -preInitialize "set test_configuration Release"
      #         -file .\path\to\all.eagle
      #
................................................................................
      #       EagleShell.exe -file .\path\to\all.eagle -preTest
      #         "unset -nocomplain test_configuration"
      #
      if {[info exists ::test_configuration] && \
          [string length $::test_configuration] > 0} then {
        #
        # NOTE: Use the specified test configuration.  The default value used
        #       for this variable is typically "Release", as set by the test
        #       suite itself.
        #
        return $::test_configuration
      } else {
        #
        # NOTE: Normally, we will never hit this case because the value of the
        #       test configuration variable is always set by the test suite
        #       itself; however, it can be overridden using the unset command
................................................................................
        # NOTE: No path is available, return an empty string.  This point
        #       should not be reached.
        #
        return ""
      }
    }
 
    proc joinBuildDirectory { native path year platform configuration } {
      #
      # NOTE: Figure out and then return the fully qualified path to the build
      #       directory based on all the arguments provided by our caller.
      #
      if {$native} then {
        return [file join $path bin $year $platform $configuration]
      } else {
................................................................................
        #       the latest version of MSBuild available and the "test_year" may
        #       need to be adjusted accordingly to actually run the test suite.
        #       Refer to the comments in [getBuildYear] for more information on
        #       how to set this variable.
        #
        set native [hasRuntimeOption native]

        return [joinBuildDirectory $native [getBuildBaseDirectory] \
            [getBuildYear] [getBuildPlatform $native] [getBuildConfiguration]]
      }
    }
 
    proc getBuildFileName { fileName } {
      #
      # NOTE: Returns the specified file name as if it were located in the
................................................................................
        foreach year [getBuildYears] {
          foreach configuration [getBuildConfigurations] {
            tputs $channel [appendArgs \
                "---- checking for System.Data.SQLite build \"" [expr \
                {$native ? "native/" : ""}] $year / $configuration "\"... "]

            set fileName [file nativename [file join [joinBuildDirectory \
                $native [getBuildBaseDirectory] $year [getBuildPlatform \
                $native] $configuration] System.Data.SQLite.dll]]

            if {[file exists $fileName]} then {
              tputs $channel yes\n
            } else {
              tputs $channel no\n
            }
................................................................................
            {temporary true} {varName db} } {
      #
      # NOTE: First, see if our caller has requested an in-memory database.
      #
      set isMemory [isMemoryDb $fileName]

      #
      # NOTE: For now, all test databases used by the test suite are placed
      #       into the database directory.  Each database and related files
      #       used by a test should be cleaned up by that test using the
      #       "cleanupDb" procedure, below.
      #
      if {!$isMemory && $qualify} then {
        set fileName [file join [getDatabaseDirectory] [file tail $fileName]]
      }

      #
      # NOTE: By default, delete any pre-existing database with the same file
................................................................................
        set flags [combineFlags $flags $::connection_flags]

        tputs $::test_channel [appendArgs \
            "---- combined connection flags are: " $flags \n]
      }

      #
      # NOTE: If our caller specified some SQLiteConnectionFlags, add the
      #       necessary portion of the connection string now.
      #
      if {[string length $flags] > 0} then {
        append connection {;Flags=${flags}}
      }

      #
      # NOTE: If our caller specified an extra payload to the connection
      #       string, append it now.
      #
      if {[string length $extra] > 0} then {
        append connection \; $extra
      }

      #
      # NOTE: Open the database connection now, placing the opaque handle value
................................................................................
      #
      return $db
    }
 
    proc getDbConnection { {varName db} } {
      #
      # NOTE: Refer to the specified variable (e.g. "db") in the context of our
      #       caller.  The handle to the database previously opened via the
      #       [setupDb] procedure should be stored there.
      #
      upvar 1 $varName db

      #
      # NOTE: This returns the ADO.NET IDbConnection object instance for the
      #       specified databse handle.  Since getting this object relies upon
      #       Eagle internals, great care should be taken to avoid disposing of
................................................................................
              $db "\", error: " \n\t $result \n]
        }
      }
    }
 
    proc freeDbConnection { {varName connection} } {
      #
      # NOTE: Refer to the specified variable (e.g. "connection") in the
      #       context of our caller.  The opaque object handle for an ADO.NET
      #       connection previously returned by [getDbConnection] should be
      #       stored there.
      #
      upvar 1 $varName connection

      #
      # NOTE: Attempt to remove the opaque object handle from the interpreter
      #       now.  This [object dispose] call will not actually dispose of the
      #       underlying object because the +NoDispose flag was set on it
      #       during creation of the opaque object handle.
      #
      if {[info exists connection] && \
          [catch {object dispose $connection} error]} then {
        #
        # NOTE: We somehow failed to remove the handle, report why.
        #
        tputs $::test_channel [appendArgs \
................................................................................
      #
      if {$collect} then {
        collectGarbage $::test_channel
      }

      #
      # NOTE: Refer to the specified variable (e.g. "db") in the context of our
      #       caller.  The handle to the database previously opened via the
      #       [setupDb] procedure should be stored there.
      #
      upvar 1 $varName db

      #
      # NOTE: Close the connection to the database now.  This should allow us
      #       to delete the underlying database file.
      #
      if {[info exists db] && [catch {sql close $db} error]} then {
        #
        # NOTE: We somehow failed to close the database, report why.
        #
        tputs $::test_channel [appendArgs \
            "==== WARNING: failed to close database \"" $db "\", error: " \