Auto - Variables

GSAK (Geocaching Swiss Army Knife)

Variables and Expressions

All GSAK variables start with the $ sign. (all GSAK system variables start with $_ and all Database variables start with $d_)

Variables are declared using the SET command (as of version 6.0 now optional), and are created and typecast on the fly. Variable names can be up to 50 characters long. Variable names are not case sensitive . Variable names can not contain any of the operation symbols +-/*^. Variables are global in scope, meaning that if you declare a variable in Macro A that calls Macro B, that variable is visible and can be used in Macro B. The reverse is also true (declaring a variable in Macro B will be visible in Macro A even after Macro B finishes)

Expressions are limited to 1000 characters (line length of the expression, not the actual string value returned by an expression or function). Expressions support parentheses and any of these functions String variables have a maximum length of 2GB.

Expressions are only valid in IF, SET, MFILTER, and WHILE commands. Prior to version 6.0 you could only access partial database information by using special tags. Special tags are now deprecated (but still supported) in version 6.0. However, I would strongly recommend the use of database variables and functions (to simulate any special tags) as this gives the macro language a more consistent look and their use is easier to understand.

There are 4 variable types, string (character), numeric, date, and Boolean.

All string values must be assigned using double quotes. If you want to include a double quote inside a string variable then use the $_Quote system variable or Quote function.

All numbers must be assigned without double quotes. All numbers must have something before the decimal place (for example 0.45 rather than just .45). All date variables must be surrounded by square brackets. Boolean variables can only be true or false. . For example:

$var1 = 45 (creates a numeric value of 45)
$var2 = "45" (creates a character string "45")
$var3 = "The cat is "nearly" dead" (invalid syntax as it contains double quotes)
$var3 = "The cat is " + quote("nearly dead") # valid syntax for line before

After the above declarations:

$var1 + 5 =>50
$var2 + 5 => invalid expression
$var2 + "5" => "455"
$var2 + " Cats" => "45 Cats"
$var1 + " Cats" => invalid expression
$var2 + $var3 => invalid expression ($var3 not declared yet)

Boolean variables only have a value of true or false (not case sensitive). You create a Boolean variable by assigning true or false to it, for example: $bool = true.Also note that the logical result of an expression can also be assigned to a Boolean variable.
For example: $bool = (%ter > 4) or $bool = FileExists("c:\temp\test.GPX") and $_Count > 400 are both valid.
Boolean variables can be used in IF and WHILE statements all by themselves:

IF $bool
Commands...
ENDIF

Or you can combine them with other expressions:

If $bool and FileExists("c:\temp\test.GPX") and $_count > 400

A date variable is declared by surrounding the date in square brackets. The date must always be in the format YYYYMMDD and contain exactly 8 digits. Date arithmetic and comparisons are supported. For example:

# set the variable $SomeDate to the 31st January, 2005
$SomeDate = [20050131]
# if the Last log date of the current waypoint is more recent then show a message
If $d_LastLog > $SomeDate
Pause msg="Last log is more recent than 31st January, 2005"
EndIf
# We can also do this using a date literal
If $d_LastLog > [20050131]
pause msg="Last log is more recent than 31st January, 2005"
EndIf
# Example of date arithmetic, set $SomeDate to 1 week before the current date
$SomeDate = $_Today - 7

An empty date should be coded as [00000000], this will allow you to test for date columns that have no dates in them. For example:

IF $d_LastLog = [00000000]
PAUSE Msg="This cache has never been logged"
ENDIF

Variable Operands:

String Operators

+ Joins two strings.

Numeric Operators

+ Addition
- Subtraction
* Multiplication
/ Division
^ Exponentiation

Order of evaluation:

operators contained in parentheses
exponentiation
multiplication and division
addition and subtraction

Order of evaluation may be altered with parentheses:

SET $var1 = 3+4*5+6 => 29
SET $var1 = (3+4)*5+6 => 41
SET $var1 = (3+4)*(5+6) => 77

Relational Operators

= Equal to
<> Not equal to
< Less than
> Greater than
<= Less than or equal to
>= Greater than or equal to

Logical Operators

AND both expressions are true
OR   either expression is true
NOT compliment of an expression (surround the expression you want to no. in brackets)
For example:

not($_Count > 500)

Examples:

1. General use

$var1 = "Apples"
$var2 = 4

IF $var2 = 4 =>True
IF $var2 = 4 or $var1 = "apples" =>True
IF $var2 = 4 and $var1 = "apples" =>False (case sensitive)
IF $var2 = 4 and $var1 = "Apples" =>True
IF $var2 = "4" => Invalid expression ($var2 is numeric)
IF $var2 = (2*2) => True
IF $var2 = ($var2 * 1) =>True

2. Take some action on files test1.zip to test10.zip by:

SET $Count = 1
SET $File = "Test"
WHILE $Count <= 10
IF FileExists($File + "$Count" + ".zip")
commands ...
ENDIF
$Count = $Count + 1
ENDWHILE

Notice the use of the "$Count" (using double quotes) in the FileExists expression. By surrounding the Numeric variable $Count in double quotes, you are typecasting it on the fly to a string value. This enables the expression to work because you can't just add a numeric variable to a string variable as in $File + $Count, as this would give you the "Invalid expression" error.

3. Using special tags (deprecated as of version 6.0 - please use database variables)

# take some action if the currently selected waypoint has a terrain level of 5
IF %Ter = 5
commands...
ENDIF
# take some action if the word "boat" is in the current waypoint description (ignoring case)
IF At("BOAT",Upper("%Name")) > 0
commands
ENDIF

System Variables:

Note: Also see the SysInfo() function for other system information your can retrieve

$_Count - (Number) The current number of records for the active table (dynamically updated after EVERY command)

$_CtrlKey - (Boolean) True if the Ctrl key is currently held down, otherwise false. Also see the PreProcess comamnd

$_CurrentDatabase (String) The name of the currently selected database

$_Degrees Bearing degrees of the current waypoint in relation to the current center point

$_EOL - (Boolean) True or False reflecting the status of the last GOTO command (EOL stands for "End of List")

$_FilterActive - (Boolean) Use to determine if a filter is currently active or not. For example (but by no means the only use), if you are planning on using SaveFilter() and RestoreFilter() then these functions are superfluous if there is currently no filter active. By testing for an active filter you can optimise your macro code to make sure it runs at top speed.

$_FilterCount - (Number) the number of waypoints returned from the last FILTER or MFILTER command (only updated after these two commands)

$_FormLeft - (String) For Form support use. Contains the number of pixels from the left of the screen the position of the current form

$_FormTop - (String) For Form support use. Contains the number of pixels from the Top of the screen the position of the current form

$_Global - (String) Set this variable and use to communicate between macros. This variable is persistent for the life of GSAK. That is, it is available to all macros regardless when they start or finish. The variable is only destroyed when GSAK shuts down.

$_GoogleLat - (String) Lattitude from right mouse click menu option ""Run Map Macro" when using Goolgle maps

$_GoggleLon - (String) Lattitude from right mouse click menu option ""Run Map Macro" when using Goolgle maps

$_Install - (String) The full path to the install folder of GSAK (without the terminating back slash)

$_MacroLevel - (Number) Corresponds to the depth of the currently called macro.
For example if Macro A calls macro B that calls macro C, then if you interrogate this variable in
Macro A will return 1, macro B will return 2 and macro C will return 3

$_NewLine - (String) Use to break up text on to multiple lines (also known as "carriage return line feed").
For example, to split a message on to two lines you are about to show using the PAUSE command:

SET $Message = "This part is on line 1" + $_NewLine + "This part is on line 2"
PAUSE Msg="$Message"

$_OziColour - Set to allocate colours for OziExplorers via a macro. For more information please see this topic.

$_Pi - The value of Pi which is 3.14159265

$_Quote - (String) " - Double quote. GSAK string literals use double quotes to denote a string variable. For that reason you can't type that value directly into a string variable. If you need a double quote inside your variable, then use $_Quote

$message = "you da " + $_Quote + "man" + $_Quote + "!"

Will give you this string in $message:
you da "man"!

$_ShiftKey - (Boolean) True if the Shift key is currently held down, otherwise false. Also see the PreProcess comamnd

$_SortBy - This system variable will allow you interrogate/save the current sort sequence.
Useful when you need to restore it later on in the macro, for example:

$Sort = $_SortBy
SORT By="Natural"
GOTO Position=Top
WHILE not($_eol)
.... setting of some database variables
Goto Position="Next"
EndWhile
$SortData = Extract($Sort, "=",1)
$Sequence = Extract($Sort, "=",2)
SORT By=$SortData Sequence=$Sequence

$_Special - used only in conjunction with the %macro special tag

$_Symbol - Set to allocate GPSr symbols via a macro. For more information please see this topic.

$_Timer - Get the time taken to execute a block of code. Only set when using the Timer() function

$_Today - The current date as per your computer setting

$_Version - The full version number of the current instance of GSAK in the form a.b.c.d where a = Whole version number, b=Major release, c=Minor release, d=Build number. For example 6.5.0.57 was the GSAK Final for version 6.5