Using the CaliperForm.Connection Class

The Connection class is used to connect to the GISDK environment, open maps and dataviews, execute GISDK functions and macros, create map images, and select geographic data. This class also includes methods for converting data types between the GISDK environment and the .NET environment.

This class also includes methods for converting data types between the GISDK environment and the .NET environment.

Here is an example of using this class in C#:

CaliperForm.Connection Conn = new

CaliperForm.Connection{ MappingServer = "Maptitude" };

Boolean opened = Conn.Open(log_file);

if (opened) {

dynamic dk = Conn.Gisdk;

dk.ShowMessage('Hello world!');

var tutorial_folder = dk.Macro('G30 Tutorial Folder') as string;

Conn.Close();

}

Opening and Closing the Connection

There are two methods that are used to connect to the GISDK environment and manage its status:

Method	Description
Open	Opens a connection to a mapping server. Always call this method before using GISDK.
Close	Closes the connection to the GISDK mapping server object. Always call this method when done with the current connection.

You create a connection with the New() operator, and then you call Open() to connect to the GISDK environment.

Executing GISDK Functions and Macros

After the connection has been open, you can access GISDK functions and macros via the connection GISDK object, which is a dynamic object. The GISDK object lets you call any function directly, for example:

dynamic dk = Conn.Gisdk

var layer_name = dk.GetLayer() as string;

var program_info = dk.GetProgram() as System.Array;

You can also execute macros defined in the default gis_ui library shipped with your product:

var tutorial_folder = dk.Macro('G30 Tutorial Folder') as string;

Executing GISDK Macros in Compiled Modules

With the GISDK you can also run macros defined in custom compiled modules. Let's say your other module has the macro named "Another Macro Name" and it is compiled to the file path/to/another_module.dbd:

Macro "Another Macro Name" (arg1,arg2)

endMacro

In C#, first you get a handle of another GISDK object for this other module via:

dynamic dk = Conn.Gisdk;

other_module = dk.WithAlternateInterface("path/to/another_module.dbd")

then use your macro:

result = other_module.Macro("Another Macro Name",arg1,arg2)

In this way you can refer to two or more different compiled modules in your C# code.

Accessing Instances of GISDK Classes

GISDK classes can be accesed using the CreateObject() method of the GISDK object.  The example below shows how to invoque the GISDK FInder Class and geocode find an address and obtain its latitude and longitude>

// Open the gisdk connection

var connection = new CaliperForm.Connection();
connection.Open();
dynamic gisdk = connection.Gisdk;

// Prepare the options array with the address to be geocode
var options = new OptionsArray();
options["address"] = "200 Beacon St";
options["city"] = "Boston, MA";
options["silent"] = "true";

// Geocode the address

var finder = gisdk.CreateObject("Data.Finder").SetRegion();
var result = finder.Find("ADDRESS", options);

// convert the results to an OptionsArray to get the coordinate property using a key
var results = new OptionsArray(result);

var coord = results["Coord"];
int lat = coord.lat;
int lon = coord.lon;
 

The OptionsArray Class

The OptionsArray class can be used for handling arrays as GISDK options arrays. You can create an instance of this class in several ways:

Create an empty OptionsArray:

    OptionsArray optionsArray = new OptionsArray(); 

Create an OptionsArray from an options array returned by a GISDK function:

    dynamic[] optionsArrayData = dk.SomeGISDKFunction(); // Replace SomeGISDKFunction with the actual function name 

    optionsArray = new OptionsArray(optionsArrayData);

Create an OptionsArray from a .NET dictionary (keys must be strings):

    Dictionary<string, object> dictionaryData = new Dictionary<string, object> { { "key1", value1 }, { "key2", value2 }, .... };      OptionsArray optionsArray = new OptionsArray(dictionaryData);

Create an OptionsArray from a .NET Hashtable (keys must be strings):

    Hashtable hashtableData = new Hashtable { { "key1", value1 }, { "key2", value2 }, // Add more key-value pairs as needed };        OptionsArray optionsArray = new OptionsArray(hashtableData);

You can easily easily get and set option values using a string indexer.

    dynamic this[string key] { set; get; }

OptionsArray Methods

Method	Returns	Description
ToArray()	object[]	Obtain a regular array of arrays representing the options.
ContainsKey(string key)	bool	Check if the OptionsArray contains the specified option (identified by the key).
AddMultiElementOption(string key, params object[] values)	void	Add an option with several values under the specified key.
ToDictionary()	Dictionary<string, object>	Get a .NET dictionary representing the options as keys and values. Note that it throws an InvalidOperationException if it contains any multi-element options.

 OptionsArray Properties

Property	Returns	Description
Keys	ICollection<String>	Returns a list of all the option names
Count	int	Returns the number of options

Accesing your own GISDK classes

With the GISDK you can also access GISDK classes defined in your custom compiled modules. Let's say you compiled a GISDK  module that has the class  MyClass, and it is compiled to the file path/to/my_gisdk_classes.dbd. The class has a method called Zoom to zoom the full extent of a selection set

// Open the gisdk connection

var connection = new CaliperForm.Connection();
connection.Open();
dynamic gisdk = connection.Gisdk;

// Set the working layer to "County" and select all counties in Colorado
gisdk.SetLayer("County");
var set_name = gisdk.Macro("G30 create set", "CO Counties");
int n_selected = gisdk.SelectByQuery(set_name, "Several", "Select * where [State Abbrev] = 'CO' ");

// Invoke your class and exceute the Zoom method
dynamic altGisdk = gisdk.WithAlternateInterface("c:\\temp\\my_ui.dbd");

var myDKObject = altGisdk.CreateObject("MyClass", "County", set_name);
myDKObject.zoom();

Accessing Style Objects

The enumeration CaliperForm.Style and the method GetStyle() of the Connection class allows you to access all of the built-in style objects that can be used as input arguments to the GISDK drawing functions.

All of the built-in style objects are stored in GISDK into arrays. For example, to access the first element of the Color array (white) and the first area fill style, use the following code:

Dim TextColor , AreaFillStyle as Object

TextColor = Gisdk.GetStyle(Style.Color, 1).

AreaFillStyle = Gisdk.GetStyle(Style.FillStyle, 1)

Here are the members of the Style enumeration:

Member	Description
Color	Built-in colors
LineStyle	Built-in line styles
FillStyle	Built-in area fill styles
ColorsPlay	Built-in color sequences for themes
FillsPlay	Built-in area fill sequences for themes
LinesPlay	Built-in line style sequences for themes
QuantileFills	Built-in quantile fill style sequences for themes

Differences between VB.NET and C#

Please refer to Differences between VB.NET and C# for important considerations when handling GISDK objects in C# and VB.NET.

Error Handling

Class CaliperForm.GisdkRuntimeException (inherits from System.Exception)

If there is a macro error encountered when calling a function or macro then an exception of type GisdkRuntimeException will be thrown

Class CaliperForm.GisdkConnectionException (inherits from System.Exception)

If there is a problem communicating with mapt.exe via COM then an exception of type GisdkConnectionException will be thrown

Specific C# Examples

To learn about performing tasks with the CaliperForm.Connection.Gisdk class, see the following C# specific examples:

- Opening a Map

- Opening a Table

- Geocoding Addresses

- Geocoding a table

- Selecting Features By Circle

- Calculating a Route