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 The DEFINE_VAR command allows you to define a variable and an associated value. You can then use the defined variable name later wrapped in percent signs to have the defined value replaced in the script. This is useful for things like defining a path or something at the top of a script that you can easily change in just one place later. You can also pass variables on the command line for truly power batch-mode operation. 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