General Overview

Global Mapper script files allow the user to create custom batch processes that make use of the functionality built in to Global Mapper. From a script, one can import data in any of the numerous formats supported by the software, reproject that data if desired or perform analysis on it, and export it to a new file. Scripts can be run from within the application interface using the File> Run Script... option. They can also be automatically run in the background by double clicking the *.gms file or called from the command line on a machine with Global Mapper installed.

Syntax

Global Mapper script files consist of a series of command lines. Each command line begins with a command. A series of parameter/value pairs should follow the command. These pairs should be written as parameter=value. No spaces should exist before or after the equal sign.

Individual parameter/value pairs should be separated by spaces. If a pair requires spaces internal to the value, quotes may be used around the entire value. For example, for a filename with spaces, the pair could look like FILENAME="c:\\my documents\\test.tif". The string designation can be nested by combining single and double quote marks (" and '). For example when specifying a variable inside a formula, like the formula in Normalize a Loaded Terrain Layer sample script.

Parameters and values are case-independent, but by convention, and in this guide, they are written in all uppercase. Commands are uppercase.

Command lines typically consist of one line each. To extend a command to another line, use the backslash character (\) at the end of the line. There are a few exceptions to this, including the DEFINE_PROJ and DEFINE_SHAPE commands and the looping functionality provided by the DIR_LOOP_START and DIR_LOOP_END commands.

Boolean Values

Many parameters in the scripting language are boolean, meaning that they have two states only of either on or off.

The values listed through-out this guide are YES to enable the option and NO to disable it, but there are a number of accepted values to specify the state:

  • YES can be represented by "YES", "Y", "TRUE", "T" , "1" , or no value (see below).
  • NO can be represented by "NO", "N", "FALSE", "F", or "0".

Parameters that expect a value of YES or NO to enable or disable functionality can (starting with v13.1) be enabled with just the parameter name. So rather than saying FLAG_PARAM_NAME=YES, you can just say FLAG_PARAM_NAME to get the same behavior as specifying yes.

Wildcards and variables

Some parameters accept values including wildcard characters.

  • * (an asterisk) represents a wildcard of any length.
  • ? (a question mark) represents a single character wildcard.

Parameters can also except variables as values or parts of values. Variables are delimited by %VARIABLE%. Some variables are built-in but they can also be defined within the script. Custom variables must be defined before they are used in a command (the script is run from top to bottom sequentially). Typically variables are defined at the top of the script for ease of use. If a variable is defined with the same name as a previously defined variable, it is replaced with the new value for the rest of the script.

See DEFINE_VAR for more information.

Predefined and Built-in Variables

The DIR_LOOP_START and LAYER_LOOP_START and DEFINE_VAR commands all contain built-in variables.

Comments

Any lines that begin with the forward slash character (/) are considered comments and are ignored by the script processing engine. This means that you can use C or C++ style comments like // or /* at the start of your line.

Note: For user-created syntax highlight for common text editors and shared example scripts from users see the Global Mapper User Forum