DEFINE_VAR

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.

Built-in Variables

There are several built-in variable names that you can use to easily insert things like the current date and time. The following variable strings can be used without having to define them:

  • %TIMESTAMP% - inserts current date and time in system format
  • %TIMESTAMP_MS% - inserts current date and time to millisecond resolution in the format 'YYYYMMDD_HHMMSSsss'
  • %DATE% - inserts current date in system format
  • %TIME% - inserts current time in system format
  • %TIME_SINCE_START% - inserts the number of seconds since the script starting running
  • %TIME_SINCE_LAST_LOG% - inserts the number of seconds since the last use of this variable
  • %SCRIPT_FILENAME% - inserts the full path and filename of the running script
  • %SCRIPT_FOLDER% - inserts the full path of the running script/workspace file. This will include a trailing slash. So a script 'C:\path\my_script.gms' would get 'C:\path\' inserted
  • %GM_MAJOR_VER% - inserts the major version of Global Mapper. For example, any Global Mapper v17 build would insert '17'
  • %GM_FULL_VER_W_DATE% - inserts the full version of Global Mapper, including the build date. For v17.0.0 built on Sep 22, 2015, this would be 'v17.0.0 (b092215)'
  • %GM_FULL_VER_NO_DATE% - inserts the full version of Global Mapper. For v17.0.0 this would be 'v17.0.0'
  • %SCRIPT_FILENAME_W_EXT% - the script file name with the extension
  • %SCRIPT_FILENAME_WO_EXT% - the script file name without the extension

The following parameters are required by the DEFINE_VAR command.

  • NAME - specifies the variable name
  • VALUE - specifies the variable value

  • FORMULA - specifies a formula used to calculate the variable's value. The formula is specified similarly to those used in the CALC_ATTR_FORMULA command, except that feature attributes cannot be specified, but instead, other defined variables, including the predefined variables, may be used. See the formula calculator reference documentation for details. Note that if FORMULA is specified, then all other parameters except for NAME will be ignored.

    To use other variables, either user-created or predefined, the delimiting '%' characters should not be used, since variable replacement in the scripting engine is performed in script commands before interpretation, including in the FORMULA parameter, an invalid formula will likely result. For example, use: 

    DEFINE_VAR NAME="TIMEDATE" FORMULA="match(TIME, '\d+:\d+')"

    rather than 

     DEFINE_VAR NAME="TIMEDATE" FORMULA="match(%TIME%, '\d+:\d+')"

    However, you do need the '%' characters if using a variable inside a string parameter. For example,

    DEFINE_VAR name=FNAME_WO_EXT VALUE=4007925_nw_a_naip
    DEFINE_VAR NAME="image_base" FORMULA="search('%FNAME_WO_EXT%.bmp','\d*\_\w\w')" //This is working

    Matching of variable names is performed via a case-sensitive match. If a variable is used in formula, but it doesn't exist, then it will be replaced by an empty string.

  • REPLACE_STR - specifies a text value to replace inside the value with something else. This is typically used inside a DIR_LOOP_START...DIR_LOOP_END loop where the VALUE contains other variables. The format is REPLACE_STR="old_value=new_value". See example below.
  • PROMPT - specifies that the user should be prompted to enter the value for the variable rather than specifying it with the VALUE parameter. Very useful for developing interactive scripts. The following values are recognized:
    • YES - Display prompt with OK and Cancel buttons and a box to enter the value.
    • YES_NO - Display prompt with Yes and No buttons. The value is set to YES or NO depending on what is selected.
    • YES_NO_CANCEL - Display prompt with Yes and No buttons. The value is set to YES or NO depending on what is selected. If Cancel is pressed the operation is cancelled.
    • OK - Display an information message with an OK button.
    • FILE - Prompts the user for a filename. The PROMPT text will be the title of the file open dialog. The VALUE (if any) will be the default filename selection (can be full path to provide a default folder too). You can use the VALUE parameter to provide several defaults, including default folder, default filename, and/or default file extension. If you just want to provide a default folder, use VALUE="C:\PATH_HERE\." where the filename is just a dot.
    • DIR - Prompts the user for a directory/ folder. The PROMPT text will be the title of the folder selection dialog. The VALUE (if any) will be the default folder selection.
  • PROMPT_TEXT - specifies the text to show if a PROMPT parameter is provided
  • ABORT_ON_CANCEL - specifies that if a prompt is cancelled (like for a file) that the entire script should be aborted. Defaults to YES if a cancellable prompt is provided. Use ABORT_ON_CANCEL=NO to not cancel the whole script on cancel of prompt.
  • FILE_MUST_EXIST - specifies that if PROMPT=FILE is specified, the selected file can be a new one and doesn't have to already exists.
    • FILE_MUST_EXIST=YES will pop up a File Open dialog, and the user must select an existing file.
    • FILE_MUST_EXIST=NO will pop up an File Save dialog, and the user can choose an existing file or a new one. This is the current default.
  • VALUE_ATTR - specifies the variable value should come from the features in the specified layer that have a non-empty value for the specified attribute. See VALUE_ATTR_MULTI for how to decide which feature to use. You should provide a FILENAME parameter to indicate which layer(s) to check for the attribute, or none to check all of them. See special Attribute Name parameter details.
  • VALUE_ATTR_MULTI - specifies which attribute to use when multiple features are present for a VALUE_ATTR. The supported values are:
    • FIRST - (default) use the first non-empty value encountered when going through features in the order they are in the file
    • MAX - use the maximum found numeric value
    • MIN - use the minimum found numeric value
  • FILENAME - filename of the layer to get the attribute value from if you use VALUE_ATTR. If an empty value is passed in, all loaded vector layers will be checked. When running the script in the context of the main map view (including loading a workspace) you can also pass in the value 'USER CREATED FEATURES' to have the 'User Created Features' layer updated or 'SELECTED LAYERS' to have any layers selected in the Control Center updated.
  • FILENAME_PIECE - specifies that only a piece of the specified value should be used. Used if the value specifies a full path and filename and you want to define the variable to just a piece of that. So you might use one DEFINE_VAR with a PROMPT=FILE to select a filename, then another DEFINE_VAR with that previous variable value as the value and FILENAME_PIECE added requesting one of the pieces listed below (samples based on 'C:\path\to\my\data\my_file.dem'):
    • DIR - full path to current file (value is 'C:\path\to\my\data\')
    • FNAME - filename of current file (value is 'my_file.dem')
    • FNAME_WO_EXT - filename of current file without extension (value is 'my_file')
    • PARENT_DIR - name of parent directory of file (value is 'data')
    • PARENT_DIRN - name of some level of parent directory, where 'N' is level. For example, PARENT_DIR1 value is 'my' and %PARENT_DIR2% is 'to'.
  • VALUE_TABLE - Provides the name of the table to be queried. See DEFINE_VAR_TABLE command.
  • VALUE_COLUMN - Provides the name of the column that contains the data used to set the value of the parameter. See DEFINE_VAR_TABLE command.
  • COMPARE_STR - Indicates which row to use for setting the value from a value table. See DEFINE_VAR_TABLE command.
  • METADATA_LAYER - identifies the layer from which the metadata will be copied. This is the same value that would be passed to the FILENAME parameter on the IMPORT command used to load the layer.
  • METADATA_ATTR - This is the string used to identify the metadata from which the value will be copied. The complete list of metadata attribute names for a layer can be seen by clicking the Metadata... button on the Control Center, or by running the EXPORT_METADATA command and looking at the result file. Some example metadata attributes are "UPPER LEFT X", "AREA COUNT", "PROJ_DESC", etc.

SAMPLE

Here is an example of a DEFINE_VAR command used to define a directory path for later use and then its subsequent use:

DEFINE_VAR NAME="DATA_DIR" VALUE="c:\temp\export test"
IMPORT FILENAME="%DATA_DIR%\blue_springs.opt"

For example you could use the following inside a directory loop to change the output path: 

DEFINE_VAR NAME="OUT_FNAME" VALUE="%FNAME_W_DIR%" REPLACE_STR="OLD_PATH\=NEW_PATH\SUB_FOLDER\"

Example to define a variable based on the F_CODE attribute of a loaded layer and then use that in the layer description of the layer. 

DEFINE_VAR NAME="LAYER_F_CODE" VALUE_ATTR="F_CODE" \
FILENAME="c:\path_to_layer\my_data.shp"
SET_LAYER_OPTIONS FILENAME="c:\path_to_layer\my_data.shp" \
LAYER_DESC="%LAYER_F_CODE%"

Example to prompt the user for a folder and then a .zip file in that folder (you could have just prompted for the file all at once, but this is for demonstration), then loads it. 

// Prompt for folder to load
DEFINE_VAR NAME="DIR_TO_LOAD" PROMPT="DIR" VALUE="d:\temp\export test\" \
ABORT_ON_CANCEL=NO
// Prompt for .zip file to load in folder. Cancel if nothing selected.
DEFINE_VAR NAME="FILE_TO_LOAD" PROMPT="FILE" VALUE="%DIR_TO_LOAD%.zip" ABORT_ON_CANCEL=YES
// Load the file.
IMPORT FILENAME="%FILE_TO_LOAD%"

Example to prompt the user for a filename, then define new variables that hold pieces of the selected filename. 

// Prompt use for file. Script aborts on cancel
DEFINE_VAR NAME="FULL_FNAME" PROMPT=FILE ABORT_ON_CANCEL=YES
// Define a variable with just the filename, another with parent folder
DEFINE_VAR NAME="FNAME_ONLY" VALUE="%FULL_FNAME%" FILENAME_PIECE="FNAME_WO_EXT"
DEFINE_VAR NAME="FNAME_PARENT_DIR" VALUE="%FULL_FNAME%" FILENAME_PIECE="PARENT_DIR"
DEFINE_VAR NAME="FNAME_PARENT_DIR1" VALUE="%FULL_FNAME%" FILENAME_PIECE="PARENT_DIR1"