The DataSource 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 DataSource.
The DataSource object can be instantiated in the same way as any other object. The construction of the DataSource may raise an error if a valid license for GeoCalc cannot be found. For instructions on licensing, see Lesson 1. Here is how we will create a DataSource:
Dim gcDataSource As New DataSource
var
gcDataSource : DataSource;
begin
gcDataSource := CoDataSource.Create;
Once we have created our DataSource, 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\GeoCalcCOM\data\geocalc.xml") Then
MsgBox ("Failed to load DataSource")
End If
if not gcDataSource.LoadFile('c:\bmg\GeoCalcCOM\data\geocalc.xml') then
begin
ShowMessage('LoadFile failed');
end;
We now have an instance of the DataSource object that is full of useful definitions and ready to be used.
All objects that can be stored in the DataSource inherit from the ISerializable interface. For each kind of ISerializable object, there are three methods on the DataSource 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 DataSource, a PutProjectedCoordSys method that puts a ProjectedCoordSys into the DataSource, and a RemoveProjectedCoordSys method that removes a ProjectedCoordSys from the DataSource.
Let's now walk through using each of these methods with a ProjectedCoordSys. In order to retrieve a ProjectedCoordSys from the DataSource, 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 DataSource. 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
Set cs = gcDataSource.GetProjectedCoordSys("BMG", "UTM-19N")
var
cs : ProjectedCoordSys;
begin
cs := gcDataSource.GetProjectedCoordSys('BMG', 'UTM-19N');
Now we have an instance of a ProjectedCoordSys that we can work with and modify.
If we want to modify our ProjectedCoordSys and then save these modifications in the DataSource, then we would need to use the Put method to put the changes into the DataSource. This method can be used to either add a new object to the DataSource, or to change an existing object. The Put method takes two arguments, the first of which is the object to be put into the DataSource, and the second of which is a boolean value indicating whether this object should overwrite an existing object in the DataSource with the same identifier.
Let's make some changes to our ProjectedCoordSys, and then put the changes in the DataSource. 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:
cs.Datum = gcDataSource.GetHorizontalDatum("BMG", "NAD27")
cs.Identifiers.Item("BMG") = "UTM-19N-NAD27"
cs.Identifiers.Item("GC") = "UTM-19N-NAD27"
cs.Identifiers.Remove "EPSG"
If Not gcDataSource.PutProjectedCoordSys(cs) Then
MsgBox ("The ProjectedCoordSys could not be added to the DataSource")
End If
cs.Datum := gcDataSource.GetHorizontalDatum('BMG', 'NAD27');
cs.Identifiers.Item['GC'] := 'UTM-19N-NAD27';
cs.Identifiers.Item['BMG'] := 'UTM-19N-NAD27';
cs.Identifiers.Remove('EPSG');
if not gcDataSource.PutProjectedCoordSys(cs, true) then
begin
ShowMessage('Unable to put ProjectedCoordSys into the DataSource');
end
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 DataSource. We will discuss saving these changes to a file later in this lesson.
We can remove existing definitions from the DataSource by using the Remove methods. Suppose we now want to remove the ProjectedCoordSys definition that we just added to the DataSource. We can accomplish this with the RemoveProjectedCoordSys method. In order to remove a ProjectedCoordSys from the DataSource, 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 DataSource by using the GeoCalc dialogs and browsing through the DataSource. 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
MsgBox ("Failed to remove the ProjectedCoordSys")
End If
if not gcDataSource.RemoveProjectedCoordSys('GC', cs.Identifiers.Item['GC']) then
begin
ShowMessage('Unable to remove ProjectedCoordSys from the DataSource');
end;
Now we have removed our new definition, and our DataSource 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 ICoordSys
Set importedCS = gcDataSource.ImportCoordSysFromFile("c:\MyCoordSys.prj")
var
importedCS : ICoordSys;
begin
importedCS := gcDataSource.ImportCoordSysFromFile('c:\MyCoordSys.prj');
We now have a ICoordSys object that contains the coordinate system definition given by the PRJ file.
GeoCalc also provides the ability to export ICoordSys definitions, but there are fewer supported export formats than there are import formats. The methods ExportCoordSysToFile and ExportCoordSysToString will export ICoordSys definitions as Well-Known Text (WKT). Here we export the ICoordSys we just imported to a WKT string:
Dim wktString As String
wktString = gcDataSource.ExportCoordSysToString(importedCS)
var
wktString : WideString;
begin
wktString := gcDataSource.ExportCoordSysToString(importedCS);
When changes are made to the DataSource, they are not automatically made to the XML file. It is necessary to use the CommitToFile method to save the DataSource to an XML file, such that the modifications made in one instance of the DataSource can be accessed by another instance. There are two signatures for the CommitToFile method, one of which takes no arguments and saves the DataSource to the file from which it was loaded, and one of which takes a string argument that specifies where to save the DataSource. This is how you save the DataSource:
If Not gcDataSource.CommitToFile Then
MsgBox ("Failed to commit DataSource to file")
End If
if not gcDataSource.CommitToFile(gcDataSource.FileName) then
begin
ShowMessage('Unable to save DataSource');
end;