The DataSourceComponent object is the most commonly used object in GeoCalc. It represents a data source XML file that has been loaded into memory. In order to retrieve or modify any of the definitions in the data source file, you must interact with the DataSourceComponent.
Commonly, the DataSourceComponent will be created by dropping the DataSourceComponent object onto a form in the Microsoft Visual Studio Designer. This process is described in Lesson2. The DataSourceComponent object can also be instantiated in the same way as any other object. The construction of the DataSourceComponent may throw a GeoCalcException if a valid license for GeoCalc cannot be found. For instructions on licensing, see Lesson 1. Here is how we will create a DataSourceComponent:
Dim gcDataSource As DataSourceComponent
Try
gcDataSource = New DataSourceComponent
Catch ex As GeoCalcException
If ex.ErrorCode = GeoCalcException.Code.NoLicensedDataSource Then
MessageBox.Show("A license is required to use GeoCalc")
End If
End Try
DataSourceComponent gcDataSource;
try
{
gcDataSource = new DataSourceComponent();
}
catch(GeoCalcException ex)
{
if(ex.ErrorCode == GeoCalcException.Code.NoLicensedDataSource)
{
MessageBox.Show("A license is required to use GeoCalc");
}
}
Once we have created our DataSourceComponent, we must populate it with data by loading one of the data source XML files into it. This is accomplished by using the LoadFile method:
If Not gcDataSource.LoadFile("c:\\bmg\\GeoCalcNET\\data\\geocalc.xml") Then
MessageBox.Show("LoadFile failed")
End If
if(! gcDataSource.LoadFile("c:\\bmg\\GeoCalcNET\\data\\geocalc.xml"))
{
MessageBox.Show("LoadFile failed");
}
We now have an instance of the DataSourceComponent object that is full of useful definitions and ready to be used.
All objects that can be stored in the DataSourceComponent inherit from the Serializable object. For each kind of Serializable object, there are three methods on the DataSourceComponent for retrieving and modifying the object: a Get method, a Put method, and a Remove method.
For example, there is a GetProjectedCoordSys method that retrieves a ProjectedCoordSys from the DataSourceComponent, a PutProjectedCoordSys method that puts a ProjectedCoordSys into the DataSourceComponent, and a RemoveProjectedCoordSys method that removes a ProjectedCoordSys from the DataSourceComponent.
Let's now walk through using each of these methods with a ProjectedCoordSys. In order to retrieve a ProjectedCoordSys from the DataSourceComponent, we will need to know an identifier for the object. For more information about identifiers, see Lesson 3. If we did not know the identifier for an object, it would be possible to get the object by using the GeoCalc dialogs and browsing through the DataSourceComponent. These dialogs are covered in more depth in Lesson 5. Here we will work with the ProjectedCoordSys that corresponds to the UTM 19N coordinate system:
Dim cs As ProjectedCoordSys
Try
cs = gcDataSource.GetProjectedCoordSys("BMG", "UTM-19N")
Catch ex As GeoCalcException
If ex.ErrorCode = GeoCalcException.Code.IdentifierNotFound Then
MessageBox.Show("Invalid Identifier")
End If
End Try
ProjectedCoordSys cs = null;
try
{
cs = gcDataSource.GetProjectedCoordSys("BMG", "UTM-19N");
}
catch(GeoCalcException ex)
{
if(ex.ErrorCode == GeoCalcException.Code.IdentifierNotFound)
{
MessageBox.Show("Invalid Identifier");
}
}
Now we have an instance of a ProjectedCoordSys that we can work with and modify.
If we want to modify it and then save these modifications in the DataSourceComponent, then we would need to use the Put method to put the changes into the DataSourceComponent. This method can be used to either add a new object to the DataSourceComponent, or to change an existing object. The Put method takes two arguments, the first of which is the object to be put into the DataSourceComponent, and the second of which is a boolean value indicating whether this object should overwrite an existing object in the DataSourceComponent with the same identifier.
Let's make some changes to our ProjectedCoordSys, and then put the changes in the DataSourceComponent. In this case, we do not want to overwrite the existing definition for the UTM 19N system, so we will change the identifiers on our ProjectedCoordSys and add it as a new object:
Dim datum As HorizontalDatum
datum = gcDataSource.GetHorizontalDatum("BMG", "NAD27")
cs.Datum = datum
cs.Identifiers.Item("GC") = "UTM-19N-NAD27"
cs.Identifiers.Item("BMG") = "UTM-19N-NAD27"
cs.Identifiers.Remove("EPSG")
If Not gcDataSource.PutProjectedCoordSys(cs) Then
MessageBox.Show("Unable to save ProjectedCoordSys")
End If
HorizontalDatum datum = gcDataSource.GetHorizontalDatum("BMG", "NAD27");
cs.Datum = datum;
cs.Identifiers.set_Item("GC", "UTM-19N-NAD27");
cs.Identifiers.set_Item("BMG", "UTM-19N-NAD27");
cs.Identifiers.Remove("EPSG");
if(! gcDataSource.PutProjectedCoordSys(cs))
{
MessageBox.Show("Unable to save ProjectedCoordSys");
}
Now we have put our definition into the data source, without modifying the existing definition for the UTM 19N system. It is important to note that we have not yet made any changes to the XML file - we have just modified the in-memory DataSourceComponent. We will discuss saving these changes to a file later in this lesson.
We can remove existing definitions from the DataSourceComponent by using the Remove methods. Suppose we now want to remove the ProjectedCoordSys definition that we just added to the DataSourceComponent. We can accomplish this with the RemoveProjectedCoordSys method. In order to remove a ProjectedCoordSys from the DataSourceComponent, we will need to know an identifier for the object. For more information about identifiers, see Lesson 3. If we did not know the identifier for an object, it would be possible to remove the object from the DataSourceComponent by using the GeoCalc dialogs and browsing through the DataSourceComponent. These dialogs are covered in more depth in Lesson 5. However, we do know an identifier for this object, so here is how we will remove it:
If Not gcDataSource.RemoveProjectedCoordSys("GC", cs.Identifiers.Item("GC")) Then
MessageBox.Show("Unable to remove ProjectedCoordSys")
End If
if(! gcDataSource.RemoveProjectedCoordSys("BMG", cs.Identifiers.get_Item("GC")))
{
MessageBox.Show("Unable to remove ProjectedCoordSys");
}
Now we have removed our new definition, and our DataSourceComponent is back to the state it was in when we first loaded it.
It is possible to import some kinds of external coordinate system definitions into GeoCalc. This is accomplished with the ImportCoordSysFromFile, ImportCoordSysFromString, and ImportFile methods. Currently, GeoCalc has the ability to import definitions in the form of Well-Known Text (WKT), ESRI PRJ files, MapInfo MAP files, and MapInfo TAB files.
For this lesson, let's assume we have a PRJ file located on our C drive called "MyCoordSys.prj". We can import this into GeoCalc like this:
Dim importedCS As CoordSys
importedCS = gcDataSource.ImportCoordSysFromFile("c:\\MyCoordSys.prj")
CoordSys importedCS = gcDataSource.ImportCoordSysFromFile("c:\\MyCoordSys.prj");
We now have a CoordSys object that contains the coordinate system definition given by the PRJ file.
GeoCalc also provides the ability to export CoordSys definitions, but there are fewer supported export formats than there are import formats. The methods ExportCoordSysToFile and ExportCoordSysToString will export CoordSys definitions as Well-Known Text (WKT). Here we export the CoordSys we just imported to a WKT string:
Dim wktString As String
wktString = gcDataSource.ExportCoordSysToString(importedCS)
String wktString = gcDataSource.ExportCoordSysToString(importedCS);
When changes are made to the DataSourceComponent, they are not automatically made to the XML file. It is necessary to use the CommitToFile method to save the DataSourceComponent to an XML file, such that the modifications made in one instance of the DataSourceComponent can be accessed by another instance. There are two signatures for the CommitToFile method, one of which takes no arguments and saves the DataSourceComponent to the file from which it was loaded, and one of which takes a string argument that specifies where to save the DataSourceComponent. This is how you save the DataSourceComponent:
If Not gcDataSource.CommitToFile Then
MessageBox.Show("CommitToFile failed")
End If
if(! gcDataSource.CommitToFile())
{
MessageBox.Show("CommitToFile failed");
}
Finally, we must clean up after ourselves and free the memory that was allocated in this lesson using the Dispose method:
cs.Dispose()
datum.Dispose()
importedCS.Dispose()
gcDataSource.Dispose()
cs.Dispose();
datum.Dispose();
importedCS.Dispose();
gcDataSource.Dispose();