Contents - Index

GetPolygon (function)

GetPolygon(sOptions,sData) : string

The GetPolygon() function is "generic" addition to the other Get...() functions and includes a rich array of options to help deal with random polygon data. Note that the return value of this function is a string because it can do more than just return the number of updated records.

sOptions:

U = update user data
2 = update user data 2
3 = update user data 3
4 = update user data 4
C = update country
Y = update county
S = update state
B = only update if corresponding field is blank or = "nil" or = "none"
F = set user flag if record updated
R = set user flag if matching polygon found (see additional notes)
M = Count the number of waypoints matched only - no updates at all
J = Set macro flag if matching polygon (see additional notes)
K = Set filter on matched waypoints
point=[coordinates] = check a single point to see if inside a polygon. The field update options (u2csfr) have no meaning when this option is used.
update=[name] = force this name to be used rather than the polygon file name.

{CustomField} = Update a custom field. For example you have set up a custom field called "Section". You have set up a polygon in your macro using a variable called $poly. You then want to update the custom field called "Section" with the value of "Grid1" if the cache is in your polygon, but *only* if the custom field "section" is blank. The corresponding macro code would be:

$result = GetPolyGon("B {Section} update=[Grid1]",$poly)
 
 
Options can be entered in any order, sData can be one of three things and GSAK will automatically determine which it is from the contents of the data:

1 - A file path to local polygon file(s)
2 - Polygon data inside a variable
3 - A named "group" supported remotely on the GSAK server.

1 - Use when the polygon file(s) are stored locally on your hard drive. Wild card matching is supported. The corresponding field will be updated the name of the matching polygon file (without the file extension), unless the name is overridden by the update= option
2 - Use this when the coordinates are stored inside a macro variable (which would usually be populated by a <data> variable)
3 - Use for special named groups that will be supported by the GSAK server

Additional notes:

R and K options should not be used with other options. They were added to enable you to flag those waypoints that have matching polygons without actually updating any data in the database. The M option should also be used by itself to just count the number of matching waypoints. The B and F options should not be used alone and must also include at least one of U,S,C,Y,2,3 or 4

Currently we have two supported "named groups":

1 - gsak_Delorme_XX where XX represents the 2 character state abbreviation. Use this named group the retrieve the required Delorme page information from the GSAK server and update your required database field. For example, if we wanted to update the "User Data" field with the Delorme page numbers for the state of Colorado, then the macro code would be:

$updated = GetPolygon("u","gsak_Delorme_CO")

 
2 - GSAK_Catalonia - polygon files Catalonia
 

$updated = GetPolygon("u","GSAK_Catalonia")

 
The point= option uses the generic waypoint grabbing code used in all GSAK coordinate input, so all those formats are supported as well (decimal degrees, decimal minutes, decimal seconds, UTM)

Polygon Data in files or a variable must consist of:

Latitude, then a "delimiter" then longitude then a line break (also referred to as a new line, Carriage return line feed, CrLf, or Chr(13) + Chr(10). The coordinate format must be decimal degrees and the datum must be WGS84.The delimiter can be any one of comma, tab, or space. However, it must be the same for every point in the file. Blank lines are allowed, as are comments which much must have position 1 equal to #.You can also have multiple polygons (islands for example) inside the file or variable. Each distinct polygon must be close (begin and end with the same point). 

There may be times when it is not convenient or you don't want the file name of the polygon to be used as the string to update, but rather something else. By including a comment line in your polygon file you can force GSAK to use this name. Just add the following comment line (position 1 must start with a #)

# GsakName=xxxxxxxxx

Where xxxxxxxx is the name you want to use. The keyword GsakName is not case sensitive, but the = must follow directly after. The same comment line can be used when your polygon data is from a variable rather than a file. This name will then be used if a point is inside the polygon. 


Example code:
 

# Example 1 - Update user data using multiple polygon files stored locally

$data = GetPolygon("u","c:\polygons\parks\*.*")

# Example 2 - Update user data using a single polygon file stored locally

$data = GetPolygon("u","c:\polygons\parks\Central Park.txt")

# Example 3 - Update user data with "Lakes" using a macro variable polygon

$data = GetPolygon("u update=[Lakes]",$polygon)

# Example 4 - Update user data using a special named GSAK group

$data = GetPolygon("u","GSAK_BritishGrid")

# Example 5 - Just count the number of matched waypoints, no file updating

$data = GetPolygon("m","c:\polygons\parks\*.*")
msgok msg=Number matched: $data

# Example 6 - Force the word "Park" into user data, rather than use the matching file name

$data = GetPolygon("u update=[Park]","c:\polygons\parks\*.*")

# Example 6 - Check to see if a coordinate is found in the polygon files (notice the "m" option is added to return the count)

$data = GetPolygon("m point=[S37° 49.222  E144° 56.779]","c:\polygons\parks\*.*")
if $data = "1"
  msgok msg=Point has a match
else
  msgok msg=Point not matched
Endif

# Example 7 - Get the matching file name (without extension) of a single point (notice the "m" option is removed)
$data = GetPolygon("point=[S37° 49.222  E144° 56.779]","c:\polygons\parks\*.*")
if IsEmpty($data)
  msgok msg=Point not matched
else
  msgok msg=Matched name is: $data
endif

# Example 8 - Update user data 2 (but only if blank) and also set the user flag if updated

$data = GetPolygon("2bf","c:\polygons\parks\*.*")

# Example 9 - Just set the user flag for any matched waypoints

$data = GetPolygon("r","c:\polygons\parks\*.*")

<data> Varname=$polygon
40.587500 -95.783330
40.587500 -95.200000
40.304170 -95.200000
40.304170 -95.783330
40.587500 -95.783330
<enddata>


Related: GetCounty() GetState() GetCountry() 

Alpha List         Category List