Lesson 1: A Search Macro and a Test Program

You will start with a macro that does the searching for the nearest points. As your user interface develops, it can continue to call this same macro. By making it a separate macro, you are beginning to build a library of reusable macros. It is also easier to develop and maintain your program this way because you can test the search macro independently from the calling environment.

Later your search macro will be called from a toolbox but, for now, you will see how to create a small test program by calling the search macro from a test macro. In the final add-in the test macro will be replaced with a command on a menu, but it can remain in the code in case you want to use it for maintenance or further development.

These macros are stored in the file named LESSON1.RSC, which was installed in the system’s Documents folder for easy access: C:\Users\[Username]\Documents\Caliper\Maptitude YYYY\CodeSamples, where YYYY is the year of your Maptitude version and  [Username] corresponds to the name assigned to the current user’s account

The test macro name is the same as the file name ("lesson1") to make it easy to remember, but the macro name could be different. Read through the macros carefully to get an idea of what is going on:

// This code is in lesson1.rsc.

Macro 'lesson1'

    // Set up the arguments for the nearest points macro; by setting these

    // in variables it is easier to read the actual RunMacro() call and know

    // what is being passed.

    // Specify a layer name in the current map; layer names are

    // case sensitive.

    layer = 'Place'

    // Use an arbitrary coordinate near Boston for now.  Coordinates are

    // given as integer millionths of degrees, longitude first, then latitude.

    // This coordinate is at -71.123456 degrees longitude and 42.456321

    // degrees latitude.

    clicked_point = Coord(-71123456, 42456321)

    // Set a search distance of 5 miles, based on the current map units.

    current_units = GetMapUnits("Plural")

    distance = 5 * GetUnitSize("Miles", current_units)

    // Call the nearest points macro.

    result = RunMacro("get nearest points", layer, clicked_point, distance)

    // Show the list of nearest points.

    ShowArray(result)

endMacro

// A macro to get the nearest points on the search layer

Macro "get nearest points" (search_layer, subject_point, search_distance)

    // Each macro should have a description at the beginning:

    // Finds points within search_distance units of subject_point on

    // search_layer and returns an array containing a data array for each

    // point, with distance, city and state; the data arrays are in order

    // by distance. This macro is designed to work with the Place layer

    // in c:\users\[your username]\Documents\Caliper\Maptitude 2025\Tutorial\NElayers.wrkz.

    //Open c:\users\[your username]\Documents\Caliper\Maptitude 2025\

    tutorial_folder = RunMacro("G30 Tutorial Folder")

    wrkz = OpenWorkspace(tutorial_folder + "NElayers.wrkz")

    // Store the current layer, then make the specified layer the working layer.

    curr_layer = GetLayer()

    SetLayer(search_layer)

    // Find the nearest points in the working layer and return, in array rhs,

    // the record handles (the string form of the record ID) for the closest

    // records. The last argument, an options array, can be null.

    rhs = LocateNearestRecords(subject_point, search_distance, null)

    // If no points were found then display message and return.

    if rhs = null then do

        ShowMessage('Sorry, no points were within your search distance.')

        // Reset the layer to the stored layer; this is very important when an

        // add-in is working with the standard interface

        SetLayer(curr_layer)

        return()

        end    

    // Dimension an array to the length of the record handles (rhs) array.

    Dim data[rhs.length]

    // Look through the record handles array.

    for i = 1 to rhs.length do

        // Use the record handle to set the current record position on the

        // current view (which in this case is the Place layer).

        SetRecord(, rhs[i])

        // Get the point coordinate for the current record on the current layer,

        // converting the record handle to its numeric equivalent (an ID).

        target_point = GetPoint(rh2id(rhs[i]))

        // Get the distance between the clicked point and the current point.

        distance = GetDistance(subject_point, target_point)

        // Add data to the output array. To add data from a current record for

        // a layer use a "field specification", which is the layer name in

        // a variable + "." + field name, e.g. layer.city, not Place.city.

        data[i]={distance, search_layer.city, search_layer.state, target_point}

        end  // end of record handles loop

    // Reset the layer and return the data array to the calling program

    SetLayer(curr_layer)

    return(data)

EndMacro

If you have done any programming before, the syntax of this language should look familiar. Macros are called like subroutines, with arguments. A For loop is used to loop through a list. Arrays can be dimensioned and referenced with subscripts. The macro calls several functions (LocateNearestRecords(), GetDistance(), etc.) that find records and compute distances.

To Compile the Sample Add-In

1. Make your text editor the current application.
2. Using your text editor, open and examine the contents of the lesson1.rsc file in the gisdk\samples folder.
3. Make Maptitude the current application.
4. Choose Tools >GIS Developer's Kit>GISDK Toolbar to display the GISDK toolbar.
5. Click   on the GISDK toolbar to display the Compile File dialog box.
6. From the gisdk\samples folder, choose the file named lesson1.rsc and click Open.

GISDK compiles the file. The compiler checks the syntax of the statements in the file. If there are any errors, they are displayed, and also written to a file of the same name, but with the extension .err. In this case, there are no errors.

To Run the Sample Add-In

1. Choose File-Open or click on the toolbar, choose Map as the file type, browse to the gisdk\samples folder in your Maptitude program folder, choose c:\users\[your username]\Documents\Caliper\Maptitude 2025\NElayers.wrkz, and click Open to display a map of the Massachusetts, Connecticut and Rhode Island with the Place layer showing city and town points.
2. Click in the GISDK Toolbox to display the Test an Add-In dialog box.
3. Click Macro in the Type of Add-In radio list.
4. Type "lesson1" in the Name text box.
5. Click OK. Maptitude finds the places within 5 miles of the supplied point and displays a dialog box with an array containing the display data. The distances will be in the current map units.
6. Click OK.

Maptitude closes the dialog box. That’s all there is to it! You have compiled and tested your first GISDK program. You can leave the Lessons map open, because you will be using it again in a few minutes.

Go to Lesson 2: Adding a Toolbox.