Contents - Index

Macros (automating GSAK) 

Jump to: Alpha List   Category List  database variables   system variables   Forms

GSAK has automation or macro (or scripting) support in the form of a macro language. Macros comprise of lines of code written to a plain text file. The default extension for a GSAK macro is .gsk. You can create a macro file using a text editor such as GSAK's macro editor. The lines of the  macro can include commands, variables, expressions and internal functions.  

The difference between a command and a function can sometimes be confusing. Basically a command (other languages often refer to this as a "procedure") does not return a value where as a function does. Other properties that help to differ between the two:
1. Functions can be used in expressions (expressions are used in IF, While, Set commands). Commands cannot. 
2. Functions can be nested within each other, commands cannot. Example: alltrim(left(upper('abcd'),2))
3. Functions have fixed parameters and all parameters must be included
4. Function parameters are always enclosed in brackets and separated by commas.
5. Commands have named parameters (some with default values), and can include/exclude optional parameters.
6. Command parameters do not support expressions, only literals and variables.

Nested conditional statements in the form of IF and WHILE (for looping) are also supported, as is the ability to interrogate system variables and database variables as well as being able to update many of them. Variable substitution is also supported. For communication between macros  GSAK also supports persistent variables. The maximum size a string variable can hold is 2gb. 

You can find real world working macros here

Once the lines of text of a macro have been created, these are saved in a plain-text file. It is recommended that you save all your macros in the "Macro" folder of your GSAK [application data] folder (See "Tools=>GSAK folder finder if you do not know your GSAK [application data] folder. Saving them there ensures that they are backed up and restored when using the GSAK backup and restore features.

A macro file can be run from within GSAK (Macro=>Run, or Ctrl-M) or from the command line when starting GSAK. You can also allocate macros to tool buttons for easy execution. You can even have GSAK automatically execute a macro on start up - see Tools=>Options=>Advanced. 

To run a macro when starting GSAK from the command line:

GSAK  "c:\some folder\MyMacro.gsk" /run. 

You can also pass parameters to a macro  (more information)

The file name only needs to be surrounded by quotation marks if the path to the file contains any spaces. The file is just a plain ASCII text file and may contain the commands in any order:

Command Syntax - Parameters are surrounded by <> (do not include these when creating a macro) and items in square brackets([ ])  are optional. Valid options for parameters are separated by | (piping symbol). All commands and parameters are not case sensitive. Blank lines are ignored.  Comments can be inserted by using the # symbol. Having a comment on the same line as a command is also supported but the # symbol must be at the very end of the command. With command parameters, the data following the = (equal sign) is accepted verbatim as the parameter value. The = (equal sign) must follow immediately after the parameter name, only when using an expression can you have optional spaces before and after the = sign. For example:
 

# This macro will do bla, bla
$x = 0
Goto Position=Top
While not($_EOL)  # Loop through the entire file
  $x = $x + 1 # count the number of waypoints
  Goto Position=Next
EndWhile
# Show total number recs
Pause Msg=$x


Command names and mandatory parameters are validated. When GSAK encounters an invalid command or missing parameter the macro will abort with an error message. For example if you used the command DEBUG Statux=on (Notice the parameter has been incorrectly spelt as Statux instead of Status) you would get the following error message. 



You can use GSAK variables in all commands but expressions can only by used in the IF, MFILTER, UNTIL and WHILE commands. For example:
 

$FileName = $_AppData + "\test.GPX"
LOAD File="$FileName"


Is valid, but the following is not, because the contents after File= is an expression. 
 

LOAD File=$_AppData + "\test.GPX"


If you want to use an expressions in a command this manner, then just allocate the expression to a variable first, then use that variable in the command.
__________________________________________________________________________
Examples:
__________________________________________________________________________

The example commands are in uppercase for clarity only. All commands, and parameters are NOT case sensitive.

Keeping it simple, all exports will use the exact same settings as per your last export for that format. 

As we are trying to automate commands with no user interaction, message boxes have been suppressed. This includes warnings about files already existing (they will automatically be overridden) and summary totals when loading a GPX file.

Note: The maximum size a string variable can hold is 2gb

Example 1,  from the command line load a GPX file, export to Ozi, then exit GSAK:
 
GSAK /run c:\temp\clyde.txt

Commands in clyde.txt
 

# Load latest pocket query of my finds into Ozi explorer, then exit GSAK
LOAD file=c:\temp\latest.GPX
FILTER name="Only found caches"
EXPORT Type=Ozi File="c:\temp\test.wpt"
EXIT


Example 2 - Combine the results of multiple filters (enter into a text file, then run via File=>Run Macro)
 

#example of macro to combine the results of 3 different filters
# load first filter
FILTER name="filter1"
# load second filter
FILTER name="filter2" join=or
# load the 3rd filter
FILTER name="filter3" join=or
If $_FilterCount = 0
  Cancel Msg="Sorry, there are no records in your combined filters"
EndIf

 
Example 3 - Send waypoints to GPS with different custom icon overrides. (For this to work you must have set up icon override settings for the various overrides using the "All waypoints" override)
 

# example of macro to send override icons to GPS
#Load first filter condition
FILTER name="Found by my friend Bozo"
EXPORT type=gps settings="set icon to funny face"
# Load second filter condition
FILTER name="Difficulty 5 caches"
EXPORT type=gps settings="set icon to sad face"


Example 4 - For a complete macro that will enable you to do a "Cache Raid" please see the CacheRaid macro 

For real world working macros take a look at user created ones here


Jump to: Alpha List   Category List  database variables   system variables   Forms