Contents - Index

Version 7.5 extra notes 


British OS Grid support.

British Grid coordinates will automatically display in GSAK generated HTML if the waypoint coordinates are in the British grid.

You can also have the coordinates columns display in the grid in this format. Tools=>Options=>Display



Special tags have been added to support this format

%bgMap = the 2 character grid map
%bgEast = the 5 digit easting value
%bgNorth = the 5 digit northing value

All input dialogs and "grab waypoints" support this new coordinate format

The gcalc() function supports the new format via the "FormatBG" action

GPSr transparency

One of the main problems with GSAK and newer GPSr units that communicate via "Mass storage mode" (like the Colorado,Oregon, and Nuvi) is how to send waypoints to them. After all, they are a GPSr, so why can't we just use "GPS=>Send"

GPSr transparency in 7.5 now makes this a reality. Any GPSr unit that is supported by GSAK uses just the one menu option to send waypoints "GPS=>Send waypoints". To simplify the menu, other exports in the "GPS" menu have therefore been removed (you can still access these via "File=>Export" if required)

GPS=>Setup has now changed to ask you for your "Model" of GPSr. From the model, we can get GSAK to transparently determine how it should get waypoints to your unit.

To implement backwards compatibility, your existing settings are converted to one of the "generic" models.

For example, if you currently have a Garmin 60csx, you would have selected Garmin and checked the USB box. In the new system, GSAK should convert this to just show the model as "Generic USB". So in this case, "GPS=>Send" should then work without making any changes. However, as future changes may be made specific to your model, it is best if you update your settings to the correct model name. 

Advanced users may be somewhat disappointed with the new integration and available options, but this change was mainly made for the new and novice users. Advanced users that are familiar with GSAK can always tweak existing exports or use custom macros.

Database conversion to SQLite

The original GSAK database engine is now getting rather old and the vendor no longer update nor support it.

One of my main issues with this engine is that "memo" type fields (long text fields like the cache long description and the log text) are kept in a separate file and the structure of this file is such that it can be vulnerable to corruption. Just having one corruption can often cascade throughout the file and then all the other memo fields then get out of sync. 

Each time you have a power failure or GSAK crashes for what ever reason while doing a database operation, we open up the possibility of corrupting this data.

I have long been searching for a database replacement, but very few match the raw speed of the existing engine and then there are other thorny issues, not least of which is backwards compatibility.

However, it has been on my mind for quite some time and I know one day it has to be replaced.

I have decided that my long term goal for GSAK is to fully replace the current database engine with SQLite. It is fast, state of the art, widely used, and a proven performer. As an added benefit we then also get to use SQL on the "live" database.

Unfortunately it is not as easy as just replacing the engine and away we go.

There are some serious issues that need working through, the two biggest being that it doesn't play nice with the current grid and it would also break many Mfilter statements and other areas of the macro language. The conversion of the database  to SQLite will be broken into two phases. Phase 1 will see the conversion of all memo fields and all tables *except* the caches table to Sqlite. Phase 1 has been completed in 7.5 and this keeps the macro language and grid backwards compatible with previous versions. Phase 2 will require the conversion of the caches table, and working through the other "serious" issues to least impact all users. Phase 2 may even be broken down into sub phases.  

This conversion in 7.5 gives us immediate benefits. The atomic commit of Sqlite is light years ahead of the current database engine and means we can virtually eliminate database corruption. However, I should also point out that this will also mean that the upgrading of your database(s) to the new format means that they will no longer be compatible with older versions of GSAK. When you first install version 7.5 it will take an immediate full backup. You can use this backup to restore to a previous version if required.

Another benefit of Sqlite - the current engine needs to rebuild the file indexes for many operations. Although Sqlite is actually slower in some database operations, there is virtually no operation that demands an index rebuild, and this should improve the overall performance of GSAK, especially when dealing with the logs table. 

Another Sqlite plus is that deletes can be done without having to immediately defrag the database. This means that deleting (allowing for atomic commit) can be done near instantly. Currently just deleting one cache or log in a large database can be a very lengthy process.

Warning: The phase 1 conversion to sqlite in 7.5 should be 100% backwards compatible with both the GUI and the macro language.However, there are some "Gotchas" in the performance areas in the macro language that will need to be addressed.

All macros should still run without code changes and without "crashing", however there is one serious performance issue that I will mention:

One of the main reasons in switching to Sqlite was the stability and integrity of the database via transactions. However when sqlite needs to write data it is very expensive in terms of performance. This is because it tries to make sure that all writes are done directly to the hard disk and not intercepted by any system caching mechanism.

This is why I have previously stated that if you do any updates or inserts via Sqlite() you must wrap them inside a "transaction" (begin and commit) so the actual write is only done at the very end and not on each individual update.

Database variable updates have been converted over in the macro language to transparently work via the SQL "update" statement. However this means that any time you update a database variable (for the logs or waypoints table) you are doing a write to the hard disk.

Take the following sample code that just keeps replacing the value of the log text 100 times (run this on a test database only)
 

timer status=on
table active=logs scope=parent
$x = 0
While $x < 100
$x = $x + 1
$d_ltext = "xxxx"
endwhile
timer status=off

 


So on my system this takes nearly a whopping 6 seconds!!!

What we need to do is wrap this code (and any other code that updates the database) inside a transaction

So now our code should look like:
 

timer status=on
table active=logs scope=parent
transaction action=begin
$x = 0
While $x < 100
$x = $x + 1
$d_ltext = "xxxx"
endwhile
transaction action=end
timer status=off

 


A huge difference!!!  

Bearing column sort is now clockwise (as per a compass)

When you click on the bearing column heading to sort, bearings will now be sorted in a clockwise direction instead of the current "alpha". Within the cardinal points, waypoints are sorted by distance from your current center point. If you do not see this when you click on the bearing column (it means you already have an index built using the old method), then take the option "Database=>Repair/defrag"

Waypoint=>Highlight now supports $_CurrentDatabase

Previously not supported, but now the system variable $_CurrentDatabase can be used when creating a mfilter expression for highlighting. This enables you to control highlighting according to the database that is currently active.

Primary key to the logs file is now "Parent code + LogId"

This change should make very little difference to the operation of GSAK and the average user. However, for the macro writer that is adding logs (especially for non geocaching.com type data) it should allow greater flexibility and range of logs to be added. For the discussion that prompted this change see this post.

Added support for corrected coordinates in the macro language

The corrected coordinates table is now fully supported in the macro language.

The table name is "Corrected"

In keeping with "Waypoints" and "Logs" I have prefixed the fields with the same letter. As we are already using "c" for Child waypoints, and have use "k" for corrected coordinates.

All before variables are read only as they are updated by the system. You can only change the after variables.

Available fields:

$d_kcode
$d_kBeforeLat
$d_kBeforeLon
$d_kBeforeState
$d_kBeforeCounty
$d_kAfterLat
$d_kAfterLon
$d_kAfterState
$d_kAfterCounty

When using the ADDNEW command it behaves similar to the corrected coordinates dialog. That is, a new corrected coordinate is added with the before and after details being the same as the cache. You would then just change the required after variables.

For example, to add a corrected coordinate that only changes the coordinates (and not the state,county) the code would be:
 

Table Active=Corrected Scope=Parent
Addnew
$d_kAfterLat = "-32.1345"
$d_kAfterLon = "115.7246"

 
Table, Goto, Seek(), MacroDelete are all supported for the new "Corrected" table 

Passing parameters to a macro

Anywhere you call a macro (MACRO command, URI support, %macro= special tag, "Macro=>Run") you can now pass parameters to it. Just add a ? (question mark) at the end of your macro, and then the full parameter information. The parameter information will be stored in the new system variable $_MacroParms

For example, if you saved the following code to your macro library as "ParmTest.gsk":
  

$p1 = extract($_MacroParms,"~",1)
$p2 = extract($_MacroParms,"~",2)
$p3 = extract($_MacroParms,"~",3)
$msg = "p1=$p1" + $_NewLine + "p2=$p2" + $_NewLine + "p3=$p3"
msgok msg=$msg

  
Then the following uri link gsak://%FF/macro/ParmTest?red~white~blue

Should produce:



Note: I have used the abbreviated form in this example to call the macro. That is, GSAK will assume your macro folder if you don't enter a fully qualified path. Also if you don't provide an extension, GSAK will assume ".gsk". This abbreviated form is supported anywhere you can call a macro, and is not version 7.5 specific.

Form definitions are now "pre processed" to validate form properties

All form properties are now checked before a form is loaded into the forms designer. This fixes a problem with "unhelpful" error messages being thrown when you try to access one of the bad properties. This way you get a meaningful error message when the form is first loaded.

Added new columns County, User3, User4

County - Not all countries have "counties". However, this column has been added to allow for the county name to be stored here. Also see the GetCounty() function
User3 - Similar to User2. Any user data can be stored here
User4 - Similar to User2. Any user data can be stored here

Support for these extra columns has been added to "Search=>Filter", "Waypoint=>Edit", "File=>Export=>GPX", Macro command "SORT", and the macro language ( corresponding database field names are $d_County, $d_User3, $d_User4)