Auto - Variables

Contents - Index

Variables and Expressions

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

Variables can be declared implicitly "on the fly" (using $x = 1234 type syntax) or explicitly using the Declare command. 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 (although you can elect to hide them using the VarScope parameter on the Macro command). 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, MFILTER, UNTIL 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:

$var1 = 3+4*5+6 => 29
$var1 = (3+4)*5+6 => 41
$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:

$Count = 1
$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.

System Variables:

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

$_AltKey - (Boolean) True if the Alt key is currently held down, otherwise false. Also see the PreProcess command

$_AppData - (String) The full path to the "application data" folder of GSAK

$_CallingMacro - (String) This system variable enables a called macro to determine the name of the macro that called it (it will return an empty string if is the top level macro, that is, if $_MacroLevel = 1)

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

$_CrLf - (String) Same as $_Newline system variable. Included here for programmers more familiar with this term.

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

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

$_CurrentDataPath (String) The fully qualified path (without the trailing back slash) to your current database folder. Particularly handy when wanting to access the GSAK sqlite database from within a macro.

$_DbCount (Number) - This system variable will always return the total number of records in the active table. Useful when a filter is set and you need to know how many records are in the database without having to cancel and restore any filters.

$_DbNotes (String) - This variable allows you to read and write the database notes section.

$_DbPath (String) - This variable returns the fully qualified path of your configured master database folder (without the trailing backslash).
$_Debug (Boolean) - This variable returns the debug status of the macro. Debug is turned on and off via the Debug command

$_Degrees (Number) - Bearing degrees of the current waypoint in relation to the current centre point

$_DualScreen (Boolean) - use to determine if the dual screen is currently active (true) or not (false)

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

$_ExePath - (String) The full path to the gsak.exe Install folder of GSAK (without the terminating back slash). For more information see this link

$_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 optimize 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

$_GcApiError - Boolean Indicates if the last call to the GcApi() function ended in error.

$_GcApiver - (Number) Geocaching.com api version number that GSAK is using.

$_GcCorrect - (Boolean) Status of Geocaching.com date correction option

$_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) Latitude from right mouse click menu option "Run Map Macro" when using Google maps

$_GoogleLon - (String) Latitude from right mouse click menu option "Run Map Macro" when using Google maps

$_ImageClickLeft - (Number) Number of pixels from the left of the image clicked to exit a form (more information)

$_ImageClickTop - (Number) Number of pixels from the top of the image clicked to exit a form (more information)

~~$_Install~~ - (String) Deprecated, but included for backwards compatibility. Use $_AppData instead. The full path to the "application data" folder of GSAK (see "Tools=>Options=>General"), without the terminating back slash. For more information see this link

$_MacroParms - (String) Parameters passed to a macro (more information)

$_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:

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

$_OrderBy (String) - Contains the "Order By" clause used to sort the current grid. It can be used when you want to run a select on the caches table and return the records in the same sequence as the current grid. It can also be used to save and restore your current sort sequence:

$CurrentSort = $_OrderBy
#Change our sort sequence to do some work in our desired sequence
SQLSort OrderBy=Terrain Asc, Difficulty desc
# do some work here
#....
# Now finally restore our current sort sequence
SQLSort OrderBy=$CurrentSort

$_OziColour (String) - Set to allocate colors for OziExplorer via a macro. For more information please see this topic.

$_Pi (Number) - 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

$_PublishID1 - Only applies to the publish logs macro

$_PublishID2 - Only applies to the publish logs macro

$_PublishCode - Only applies to the publish logs macro

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

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

$_RunMode - Determine in what context or mode a macro is running. For all the possible modes see this link

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

$_SortBy - Deprecated, use $_OrderBy instead

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

$_SplitScreen (Boolean) - use to determine if the split screen is currently active (true) or not (false)

$_SQL (String) - Use to return the result of an expression that always has the decimal separator as a period (more information)

$_SqlEol0..$_SqlEol4 - (Boolean) True or False reflecting the status of the last SqlNext command (use via SqlGet() ) Note: As the default handle is 0, $_SqlEol is the same as $_SqlEol0 and the two can be used interchangeably.

$_SqlGrid (String) - returns the syntax for a full optimized query on the caches table to return only the records in the current grid and in the same order. Example, build short list of the grid filter in the current order:

$status = sqlite("sql",$_SqlGrid, "sqlget=yes")
$data = ""
while not($_sqleol)
$data = $data + sqlget("code") + sqlget("name") + sqlget("userdata") + $_Crlf
sqlnext
Endwhile

$_SqlRows (Number) - Return the number of rows produce by the action "SQL" using the sqlite() function (more information) Note: This value is always zero when using SqlGet=Yes

$_StartAlt - (Boolean) True if the Alt key was held down at the very *start* of the macro (even if later the key is released). If you need to know the current status of the Alt key, use $_AltKey instead.

$_StartCtrl (Boolean) True if the Ctrl key was held down at the very *start* of the macro (even if later the key is released). If you need to know the current status of the Ctrl key, use $_CtrlKey instead.

$_StartShift - (Boolean) True if the Shift key was held down at the very *start* of the macro (even if later the key is released). If you need to know the current status of the Shift key, use $_ShiftKey instead.

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

$_Tab (String) - Tab character - same as chr(09)

$_Time (String) - The system time returned as a string in the format HH:MM:SS

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

$_Today (Date) - The current date as per your computer setting

$_Units (String) - fetches user's distance setting, K=Kilometers, M=Miles

$_Version (String) - 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

$_Where (String) - Contains your current "Where" clause (used to select records in the grid). It can be used when you want to run a select on the caches table and return only the records as shown in the grid