There are multiple ways to trigger the run of a GAMS model: Running a model via F9 from GAMS Studio, executing GAMSJob.Run method in the object oriented APIs or calling the gams executable from a command line. In all cases the same GAMS engine runs the user's model. Several options are available to customize the GAMS run. Depending on the particular way GAMS is triggered these options are supplied in different ways. For example, in Studio via the parameter editor in the toolbar, in the object oriented API through the GAMSOptions class, and from the command line via command line arguments. In order to avoid confusion with the often used word option we refer to these entities as command line parameters and demonstrate their use from the command line. Although details will vary with the type of computer and operating system used, the general operating principles are the same on all machines.

In this chapter we will introduce how GAMS is called from the command line and how parameters may be specified on the command line or in other ways. In addition, we will discuss user-defined command line parameters, compile-time variables and compile-time constants, which are GAMS specialties, and environment variables in GAMS. Moreover, most of the chapter is dedicated to the detailed description of all GAMS options (i.e. options available via command line parameters, option statement, and model attribute.

In almost all cases such a run continues from start to end without any user interaction. A GAMS run usually consists of two phases: the compilation and execution phase.

The Generic GAMS Call

The simplest way to start GAMS from a command shell is to enter the following command from the system prompt:

> gams myfile

GAMS will compile and execute the GAMS statements in the file myfile. If a file with this name cannot be found, GAMS will look for a file with the extended name myfile.gms. During the run GAMS will print a log to the console and create a listing file that is written by default to the file myfile.lst. For example, the following statements retrieves and runs the model [TRNSPORT] from the GAMS model library with the responds from the GAMS system:

> gamslib trnsport
Copy ASCII : trnsport.gms
> gams trnsport
--- Job trnsport Start 06/21/17 06:23:45 24.8.4 r60966 WEX-WEI x86 64bit/MS Windows
GAMS 24.8.4   Copyright (C) 1987-2017 GAMS Development. All rights reserved
Licensee: GAMS Development Corporation, Washington, DC   G871201/0000CA-ANY
          Free Demo,  202-342-0180,  sales@gams.com,  www.gams.com   DC0000
--- Starting compilation
--- trnsport.gms(69) 3 Mb
--- Starting execution: elapsed 0:00:00.010
--- trnsport.gms(45) 4 Mb
--- Generating LP model transport
--- trnsport.gms(66) 4 Mb
---   6 rows  7 columns  19 non-zeroes
--- Executing CBC: elapsed 0:00:00.018

COIN-OR CBC      24.8.4 r60966 Released Apr 10, 2017 WEI x86 64bit/MS Windows

COIN-OR Branch and Cut (CBC Library 2.9)
written by J. Forrest

Calling CBC main solution routine...
0  Obj 0 Primal inf 900 (3)
4  Obj 153.675
Optimal - objective value 153.675
Optimal objective 153.675 - 4 iterations time 0.052

Solved to optimality.
--- Restarting execution
--- trnsport.gms(66) 2 Mb
--- Reading solution for model transport
--- trnsport.gms(68) 3 Mb
*** Status: Normal completion
--- Job trnsport.gms Stop 06/21/17 06:23:46 elapsed 0:00:01.249

Note

GAMS can also run source files that have been compressed with Posix utility gzip or have been encrypted with tool ENDECRYPT, for example

> gamslib trnsport
> gzip trnsport.gms
> gams trnsport.gms.gz

results in

• retrieval of the [TRNSPORT] model from the GAMS Model Library
• compression the source file trnsport.gms
• GAMS running the compressed file trnsport.gms.gz.

Observe that some GAMS options may be specified on the command line as part of the GAMS call. In addition, command line parameters may be set by specifying a secondary customization parameter file and by modifying the GAMS system parameter file. As command line parameters may be specified in several different ways, there are rules of precedence in case of conflicting instructions. We will discuss these topics in the next four subsections.

Specifying Options Through the Command Line

GAMS permits certain options to be passed through the command line. The syntax of the simple GAMS call is extended as follows:

> gams myfile key1=value1 key2=value2 ...

Here key1 is the name of the option that is being set on the command line and value1 is the value to which the option is set. Depending on the option, value1 could be a character string, an integer number or a real number. Note that the options that may be set on the command line are called GAMS command line parameters.

For example, consider the following commands to run the transportation model [TRNSPORT]:

> gams trnsport  o myrun.lst  logOption 2
> gams trnsport -o myrun.lst -logOption 2
> gams trnsport /o myrun.lst /logOption 2
> gams trnsport  o=myrun.lst  logOption=2
> gams trnsport -o=myrun.lst -logOption=2
> gams trnsport /o=myrun.lst /logOption=2

All six commands above are equivalent: each directs the output listing to the file myrun.lst. Note that o is the synonym of the command line parameter output and it is set to the value myrun.lst. In addition, the parameter LogOption is set to 2, which has the effect that the log output is redirected to the file trnsport.log. Please also note that the option name can be specified without consideration of the casing of the option. Hence logoption works as well as LogOption or any other casing. The way options are specified can vary with each option. So a mixed alternative, e.g. gams trnsport -o=myrun.lst /logoption 3 is valid too.

In addition to predefined command line parameters, GAMS also allows user-defined command line parameters which work in tandem with compile-time variables. User-defined parameters, also called double dash parameters, and compile-time variables are introduced in section Double Dash Parameters, Compile-Time Variables and Environment Variables below.

Option Values with Spaces

One may want to set string valued options including double dash parameters to an empty string or a string containing spaces, even trailing or leading spaces. All this requires the use of quotes. Quotes may be handled differently, depending on the operating system. Users should be attentive when using such string values. This is also important if GAMS is called from within a GAMS program with $call [=]gams ... and execute [=]gams ... because platform independence might be violated.

A platform independent way to set a string value with spaces is to use the variant that separates the option name and option value by a space, e.g. opt "". The variant without space, e.g. opt="" might cause issues on some Unix shells. Consider the following example where spacy.gms contains only the following line to write the content of the double dash parameter dd to the log:

$log value of dd: >%dd%<

Here is a sequence of GAMS runs with a variety of string values

> gams spacy --dd normal
> gams spacy --dd "normal"
> gams spacy --dd ""
> gams spacy --dd " leading"
> gams spacy --dd "trailing "
> gams spacy --dd " leading and trailing "
> gams spacy --dd "   "

that result on all platforms in the following log output (only relevant part):

value of dd: >normal<
value of dd: >normal<
value of dd: ><
value of dd: > leading<
value of dd: >trailing <
value of dd: > leading and trailing <
value of dd: >   <

An even better way to pass arguments to a GAMS run without the system shell interfering with interpretation of some characters is described in the next section.

Attention

GAMS options specifying file names may also contain leading and trailing blanks. Please be aware that while leading blanks in a file name are significant on all platforms, trailing blanks are only significant on some platforms (e.g. Linux). Hence output "mymodel.lst " and output "mymodel.lst" refer to the same file on Windows and to different files on Linux.

Specifying Options Through a Secondary Parameter File

Command line parameters may also be set by specifying a secondary customization parameter file. For example, we will create a file with the following two lines, call it moreOptions.txt and save it in the current working directory.

limCol=0
limRow=0

Note that setting limcol and limrow to zero will suppress the column listing and equation listing respectively. Moreover, note that we can specify the option in different way in this secondary parameter file, even have multiple options on one line. In the next step we will use the following command to run the transportation model [TRNSPORT]:

> gams trnsport parmFile=moreOptions.txt

Note that this call has the same effect as the following specification:

> gams trnsport limCol=0 limRow=0

Observe that command line parameter include files are particularly useful if modelers wish to use the same set of command line parameters repeatedly.

If options are listed multiple times on the command line, the last specification sets the option. This is important in particular in combination with a secondary parameter file. In the following example, GAMS will operate with limRow=0:

> gams trnsport limRow=10 parmFile=moreOptions.txt

while with the order reversed, GAMS operates with limrow=10:

> gams trnsport parmFile=moreOptions.txt limRow=10

Specifying Options Through the GAMS System Parameter File

A third way to specify command line parameters is by modifying the GAMS system parameter file, which is part of the GAMS system. It has different names depending on the operating system: gmsprmnt.txt for Windows and gmsprmun.txt for UNIX/Linux and macOS. The parameter file may be modified in the following way:

******************************************************************
* GAMS 2.50 default Unix parameter file                          *
* Gams Development Corp.                                         *
* Date : 4 May, 1998                                             *
******************************************************************
* entries required by CMEX, put in by the gams script
* SYSDIR
* SCRDIR
* SCRIPTNEXT
* INPUT
PageWidth 95
ParmFile "c:\some\central\location\moreOptions.txt"

Note that the last two lines were added to the standard GAMS system parameter file. As a consequence, each GAMS run will have a print width of 95 columns on the pages of the listing file. In addition, the command line parameters specified in the file moreOptions.txt will now apply to each GAMS run.

The GAMS Configuration in YAML Format

The GAMS configuration file gamsconfig.yaml written in the YAML format is easy to process by humans and computers. The GAMS Configuration Editor can be used to view and edit the GAMS configuration file but any other text editor can be used as well. This file has three configuration sections: command line parameters (commandLineParameters), operating system environment variables (environmentVariables), and external solver configuration (solverConfig). The latter is only relevant if you need to make a solver available to GAMS that is not shipped with the GAMS distribution. The COIN-OR GAMSlinks project has solver (links), e.g. Couenne, that could be added this way.

The first two sections are most easily described by an example:

commandLineParameters:
  - intVarUp:
      value: 1
  - eolCom:
      value: '//'
      maxVersion: 31
  - eolCom:
      value: '#'
      minVersion: 32
environmentVariables:
  - GDXCOMPRESS:
      value: 1
      maxVersion: 31
  - GDXCOMPRESS:
      value: 0
      minVersion: 32
  - PATH:
      value: /my/path/to/R/bin:/my/path/to/R/site-bin
      minVersion: 31.1.0
      maxVersion: 31.1.0
      pathVariable: True

In this example, the gamsconfig.yaml initializes some command line parameters and some environment variables. It initializes intVarUp unconditionally to 1. It also sets eolCom to the character sequence // for GAMS version 31 and earlier, while it uses the character # for GAMS version 32 and later. The keywords minVersion and maxVersion allow to have different entries for the same command line parameter for different versions. Also the file gamsconfig.yaml allows the repetition of entries. Hence, when GAMS runs it will filter all entries with appropriate minVersion and maxVersion and applies the setting of entries in sequence, so the last entry wins. Similarly, GAMS sets the environment variables GDXCOMPRESS to 0 or 1 depending on the actual version of GAMS. The last entry to set the PATH environment variable will be only applied for the GAMS version 31.1.0. Moreover, the indicator pathVariable set to True will result in prefixing the environment variable PATH with /my/path/to/R/bin:/my/path/to/R/site-bin.

The YAML syntax for the gamsconfig.yaml file is straightforward. Each section starts with a fixed name (commandLineParameters or environmentVariables) and is followed by a list of entries. Each entry starts with - and the name of the command line parameter or the name of the environment variable followed by a colon :. The next lines start with a keyword (value, minVersion, maxVersion and for environment variables also pathVariable) followed by a colon : and a value. The syntax of YAML files is very simple but it is crucial to use a consistent alignment. So all entries of a section must be perfectly aligned. Please be careful when mixing spaces and the tab character. If GAMS complains during the processing of a gamsconfig.yaml file with e.g. System problems in yaml_parser_parse: mapping values are not allowed in this context most likely your alignment is off as in the following erroneous example:

commandLineParameters:
  - eolCom:
      value: '//'
        maxVersion: 31

The lines with value and maxVersion need to start in the same column. There are plenty of online syntax checkers for YAML files. Use your favorite search engine and search for yaml validator (check the popular YAML validator) and copy and paste your problematic gamsconfig.yaml to get more insight into the YAML syntax problem. Moreover, the gamsconfig.yaml file has some required fields and some requirements for the value of some keys. In fact there is a schema file that validates that a syntactically correct gamsconfig.yaml fulfills the GAMS schema for configuration files. The schema file is part of the distribution and can be found in the system directory (gamsconfig_schema.json). One can validate a gamsconfig.yaml against this schema via a Python program (you might need to install additional Python packages jsonschema and ruamel.yaml):

import jsonschema
from ruamel.yaml import YAML
import json

with open('gamsconfig_schema.json') as f:
  schema = json.load(f)

yaml = YAML(typ="safe")
with open('gamsconfig.yaml') as f:
  config = yaml.load(f)

print(jsonschema.validate(instance=config, schema=schema))

Besides the required fields like value the schema also imposes restrictions on some value types (e.g. True and False for pathVariable and a proper release number for minVersion and maxVersion). The form of the release number can be just the major release (e.g. 31), the major and minor release number (e.g. 31.1) or the full detailed release number, e.g. 31.1.0. So if maxVersion is set to e.g. 31 then all releases of 31 fulfill this version requirement.

Some parts of the GAMS system react on environment variables, e.g. the environment variable GMSPYTHONLIB decides about the Python library and installation used for embedded Python code. At the start of a GAMS run environment variables are set to the values given in the gamsconfig.yaml file. This is a convenient way to manage GAMS-related environment variables without utilizing OS-specific ways to set environment variables.

GAMS will process a sequence of gamsconfig.yaml files. It starts with the file in the GAMS system directory and then searches through some system-wide and user-specific standard locations.

Note

With GAMS 32 new defaults for several options were introduced. We have collected these options and their old or legacy default values in the file gamsLegacyConfig.yaml located in the GAMS system directory. Copy this file as gamsconfig.yaml to a location searched by GAMS to continue to work with the legacy defaults. The minVersion keyword in this file indicates when the new default became active.

Adding Solvers via gamsconfig.yaml

The third section in the GAMS configuration file gamsconfig.yaml allows to make a solver not shipped with GAMS available to the GAMS system. For that, an interface between an instantiation of a GAMS model and a solver needs to be implemented by use of libraries GMO and GEV. The COIN-OR GAMSlinks project provides examples of such solver interfaces. For the remainder of this section assume that we want to introduce a new version of the MINLP/MIQCP solver SHOT. GAMS knows about available solvers from the sub-system configuration file gmscmpNT.txt (gmscmpun.txt for non-Windows platforms). Here is a section from this file for the MINLP/MIQCP solver SHOT on Windows:

The gamsconfig.yaml file provides the same information in a more descriptive way:

solverConfig:
  - SHOT2:
      minVersion: 33
      fileType: 1001
      dictType: 5
      licCodes: 000102030405
      defName: optshot.def
      scriptName: gmsgennt.cmd
      executableName: gmsgennx.exe
      library:
        libName: D:\Users\janeDoe\Downloads\gamslink\GamsShot-20.dll
        auditCode: sht
        solverInterfaceType: 1
        threadSafeIndic: True
      modelTypes:
        - MINLP
        - MIQCP

The new solver will be called SHOT2 and has almost the identical information as the solver SHOT that comes with GAMS. We could also use the name SHOT again. This would hide the original solver SHOT and use the one described by gamsconfig.yaml. In addition to the solver information, this section allows the keywords min/maxVersion that instructs whether to include the solver depending on the GAMS version.

The fileType (line 1 second item in the section of gmscmpNT.txt) determines the type of the scratch files that contain the model instance. The one-digit determines binary (1) or text (0) format of the scratch files. The ten-digit determines whether GAMS puts the initial marginal information into the scratch files (1 for writing, 0 for not writing). The scratch file with the constraint matrix is stored column wise, the hundred-digit instructs GAMS to write (if at 1) the row count per column, so the solver can layout memory in advance for storing the constraint matrix. With GAMS' current libraries gmo and gev this information is not used and hence the hundred-digit should be at 0. The thousand-digit is about scaling. A non-zero value instructs GAMS to write the information stored in the .scale/.prior/.stage variable and equation attributes into the scratch files. With a value of 1 this is only done if scaleOpt/priorOpt are on. With a value of 2 this information is written independently of scaleOpt/priorOpt. With a value of 3 for models with variable and matching information (e.g. MCP) the reported marginals will be scaled by GAMS. The ten thousand-digit is always 0 and the hundred thousand-digit (if set to 1) instructs GAMS to write the variable/equation matching information to the scratch files for models that need this information (e.g. MCP). The leading zeros of the value for key fileType should be omitted.

The dictType (line 1 third item in the section of gmscmpNT.txt) decides about the type of the dictionary scratch file that contains the mapping information between the GAMS names and the variable and equation indexes seen by the solver. For example, this helps the solver to form good variable and equation names for error messages. Four values are allowed:

• 0: no dictionary information
• 5: dictionary with all labels that are used in the model instance
• 15: dictionary with all labels that are used in GAMS program
• 25: dictionary with all labels that are used in GAMS model plus an extra GDX file with the entire GAMS database (similar to execute_unload "everything"; prior to the solve statement)

The licCode (line 1 fourth item in the section of gmscmpNT.txt) gives a guess about what license codes are required to run the solver. This is not the actual license information but allows other programs like e.g. "GAMS Studio" to list the solvers available with a particular license. In most cases solvers that are added this way should list the GAMS BASE license codes "000102030405".

The defName (line 2 second item in the section of gmscmpNT.txt) points to a file that contains all the solver options for the solver. This key does not need to be provided (same in gmscmpNT.txt) if the defName is opt + solvername + .def and the file resides in the GAMS system directory. Since we use the name SHOT2 GAMS would expect the solver options to be in optshot2.def. If there were an optshot.def in the GAMS system directory for the original SHOT, we could reuse that file and list optshot.def for the defName key. The defName provided here is used by other programs like "GAMS Studio" that can assist with building solver options files.

The next three items on line 1 in the section of gmscmpNT.txt are for internal purposes and not discussed here in detail. They can be set via gamsconfig.yaml via the keys defaultOkFlag and hiddenFlag with values True or False.

GAMS has different ways of calling a solver controlled by the solveLink option. The scriptName (line 2 in the section of gmscmpNT.txt) contains the name of the script that calls the solver (in case of solveLink=0 (chainScript) or 1 (callScript)). For solvers that are capable of solveLink=5 (loadLibrary) a generic script gmsgennt.cmd (or gmsgenus.run) can be used. The executableName (line 3 in the section of gmscmpNT.txt) provides the name of the solver executable. Again for solvers capable of solveLink=5 (loadLibrary) a generic executable gmsgennx.exe (or gmsgenux.out) can be used.

The section library is necessary only for solvers capable of solveLink=5 (loadLibrary). The libName contains the name of the solver library file (line 3 first item in the section of gmscmpNT.txt). The auditCode (line 3 second item in the section of gmscmpNT.txt) is the prefix of the functions in the solver library (e.g. shtCallSolver). The solverInterfaceType (line 3 third item in the section of gmscmpNT.txt) defines the API implemented by the solver library and loaded by GAMS. Currently, there are only two types: 1 (xyzReadyApi and xyzCallSolver) and 2 (xyzCallSolver only). The threadSafeIndic (line 3 third item in the section of gmscmpNT.txt) indicates whether the solver library is thread-safe and can be used in combination with solveLink=6 (aSyncThreads).

The final section modelTypes is about the model types the solver can handle. This information can be found in line 1 after item 7 in gmscmpNT.txt.

Order of Precedence for Options

The order of precedence for command line parameters including customization specifications in the GAMS IDE is as follows:

1. Command line parameters that are specified on the command line or in the Studio/IDE command line field.
2. Command line specifications in the IDE options window Execute (this is reached through File|Options|Execute).
3. Command line specifications in the specific IDE dialogs, e.g. Output (this is reached through File|Options|...).
4. Entries in the GAMS configuration files gamsconfig.yaml.
5. Entries in the GAMS system parameter file.

Many command line parameters initialize the default for a GAMS Option also accessible inside the GAMS program. For example, the system default for option MIQCP is SBB. If the command line parameter MIQCP has been set, e.g. to DICOPT, DICOPT will be new default MIQCP solver. Inside the GAMS program, one can reset the MIQCP via option MIQCP=SHOT; but setting it back to the default will result in DICOPT (not SBB) being the default solver: option MIQCP=default;.

Double Dash Parameters, Compile-Time Variables and Environment Variables

In this section we will cover double-dash parameters that enable users to set values for specific variables on the command line. These variables are substituted with their respective specified values at compile time. We will also discuss how operating system specific environment variables may be accessed and modified from a GAMS program.

Double Dash Parameters and Compile-Time Variables: A Simple Example

We will introduce double dash parameters and compile-time variables using as an example the well-known transportation model [TRNSPORT]. Assume we wish to explore how the solution changes if the demand assumes various values. To model this, we will introduce the compile-time variable DMULT, a multiplier for the demand b:

$set DMULT 1
...
demand(j) ..   sum(i, x(i,j))  =g=  %DMULT% * b(j) ;

Note that DMULT is defined with the dollar control option $set and its value is set to 1, which corresponds to the base line. Observe that the compile-time variable is referenced in the equation with the %...% notation. %DMULT% will be replaced at compile time by its value, in this case 1. We are now in the position to run the program multiple times by just changing the value of DMULT in the first line, which will automatically change the multiplier in the equation to the respective value.

GAMS offers a more convenient way for setting a compile-time variable like DMULT to a variety of values:

$if not set DMULT $set DMULT 1
...
demand(j) ..   sum(i, x(i,j))  =g=  %DMULT% * b(j) ;

Note that we set a default value for DMULT using conditional compilation. We may change this default on the command line when calling GAMS by specifying DMULT as a double dash parameter as follows:

> gams trnsport.gms --DMULT=0.9

Observe that with the specification –DMULT=0.9 the compile-time variable DMULT is set and therefore the default does not apply. Thus the double dash parameter facilitates changing the value of a compile-time variable directly on the command line as part of the GAMS call while the respective GAMS file remains unchanged.

Assume that the model contains a second compile-time variable called METHOD that acts as a switch for various methods of solving the model and it may take the values 1, 2 and 3. In this case both compile-time variables may be set on the command line as follows:

> gams trnsport.gms --DMULT=1.12 --METHOD=3

In the next two subsections we will discuss double dash parameters and compile-time variables in more detail.

Double Dash Parameters

Double dash parameters are user-defined command line parameters that are used to define scoped compile-time variables or to assign values to scoped compile-time variables. The general syntax is:

> gams myfile --NAME=value

Here NAME is the name of the double dash parameter and value is its assigned value that may be any string. If the string contains spaces or other token terminating characters, the string value should be quoted. Consider the following simple example:

> gams myfile --keycity=Boston --myvalue=7.6 --dothis="display x;"

Suppose that myfile.gms contains the following lines with the scoped compile-time variables keycity, myvalue and dothis:

x("%keycity%")=%myvalue%;
%dothis%

Note that the compile-time variables are referenced using the notation %...%. The GAMS call above has the effect that at compile time the compile-time variables are substituted with the values specified through the double dash parameters resulting in the following:

x("Boston")=7.6;
display x;

GAMS offers three alternative syntax variants for defining double dash parameters:

> gams myfile //NAME=value
> gams myfile /-NAME=value
> gams myfile -/NAME=value

Note that the four syntax variants may be used interchangeably and have the same effect.

Double dash parameters are particularly useful for specifying granularity when modeling a discretization of time and or space. For example, in the model [CHAIN] the problem is to find the chain with minimal potential energy, assuming the chain has uniform density, is suspended between two points and has a given length L. Consider the following code snippet:

$if not set nh $set nh 50 
Set nh / i0*i%nh% /;

The first two lines use conditional compilation to set a default value for the compile-time variable nh. Note that the value of nh determines the cardinality of the set nh, which is used for the discretization. The value of nh may be easily set on the command line to any desired value using nh as a double dash parameter:

> gams chain --nh=100

Note that the double dash functionality supersedes the command line parameters user1, ..., user5 which are accessible in the source file via %gams.user1%, ..., %gams.user5%. The example above would work with user1 in the following way:

$set nh 50 
$if not "%gams.user1"=="" $set nh %gams.user1% 
Set nh / i0*i%nh% /;

The modified code could be called with:

> gams chain user1=100

Note that the double dash parameters facilitate using meaningful names instead of the generic names user1, ..., user5. This is especially useful if there are multiple parameters to pass on to the GAMS program.

Observe that the dollar control option $setDDList may be used to ensure that a model can only be run with the listed double dash parameters:

$setDDList nh
$if not errorFree $log *** Only allowed double dash options is: --nh=value

Compile-Time Variables

Compile-time variables are special variables that are substituted with their values at compile-time. They are not declared and defined with regular declaration statements like standard symbols (sets, parameters, ...), but they are defined with the dollar control option $set and its variants. There are three kinds of compile-time variables that differ in their scope level: local, scoped and global. An overview is given in Table 1.

Scope	Availability	Defined with	Removed from the system with
Local	Available only in the input file where they are defined	$setLocal.	$dropLocal
Scoped	Available in the input file where they are defined and in all include files of the input file.	$set	$drop
Global	Available in the input file where they are defined, in all parent files and in all include files.	$setGlobal	$dropGlobal

Table 1: Scope Levels for Compile-Time Variables in GAMS

Note that scoped compile-time variables may also be defined on the command line with double dash parameters. For example, in the example above the compile-time variable DMULT may be referenced in the equation demand without being defined with the dollar control option $set as long as it is defined and set on the command line. Note further, that global compile-time variables are saved in work files.

While the scope of a compile-time variable cannot be directly changed, but dropping and adding variables in different scopes accomplishes the same. Consider the following example:

$set MYVAR xxx

* From scoped to global
$ifThen set MYVAR
$  setGlobal MYVAR %MYVAR%
$  show
$  drop MYVAR
$  show
$endIf

* From global to local
$ifThen setGlobal MYVAR
$  setLocal MYVAR %MYVAR%
$  show
$  dropGlobal MYVAR
$  show
$endIf

Note that the compile-time variable MYVAR is first defined as a scoped variable with the value xxx. The dollar control option ifThen tests whether MYVAR was defined with $set and since this is TRUE the next four dollar control statements are processed: a new global compile-time variable called MYVAR is defined and is set to the value of the scoped compile-time variable MYVAR, the resulting compile-time variables are shown, the scoped compile-time variable is removed from the system with the option $drop and the resulting compile-time variables are shown again. A similar procedure is followed to change the global compile-time variable MYVAR to a local compile-time variable with the same name and value.

The output generated by the four dollar control options $show follows:

Level SetVal                          Type       Text
-----------------------------------------------------
    0 MYVAR                           SCOPED     xxx
    0 MYVAR                           GLOBAL     xxx

Level SetVal                          Type       Text
-----------------------------------------------------
    0 MYVAR                           GLOBAL     xxx

Level SetVal                          Type       Text
-----------------------------------------------------
    0 MYVAR                           LOCAL      xxx
    0 MYVAR                           GLOBAL     xxx

Level SetVal                          Type       Text
-----------------------------------------------------
    0 MYVAR                           LOCAL      xxx

Observe that this report is called Environment Report. This name is unfortunate, since the variables reported are in fact compile-time variables. Environment variables in GAMS are discussed in section Environment Variables in GAMS below.

Note that if a compile-time variable is referenced with %MYVAR%, it could reference a global, scoped or local compile-time variable called MYVAR. GAMS will always access the compile-time variable MYVAR with the most local scope. Thus if all three scopes are defined, the local compile-time variable is accessed first, then the scoped and then the global, as demonstrated in the following example:

$set XXX scoped
$setLocal XXX local
$setGlobal XXX global
$log %XXX%
$dropLocal XXX
$log %XXX%
$drop XXX
$log %XXX%
$dropGlobal XXX
$log %XXX%

The resulting log output will be:

local
scoped
global
%XXX%

Note that how %XXX% will be handled if no compile-time variable XXX is defined, is determined by the command line parameter stringChk.

For a full list of dollar control options that affect compile-time variables, see section Dollar Control Options for Compile-Time Variables and Environment Variables.

Environment Variables in GAMS

GAMS programs have access to operating system environment variables via %sysEnv.NAME%. Operating system environment variables may be modified or new environment variables may be defined with the dollar control option $setEnv. Consider the following artificial example:

$log %sysEnv.GEORGE%
$setEnv GEORGE Dantzig
$log %sysEnv.GEORGE%
$dropEnv GEORGE
$log %sysEnv.GEORGE%

Note that the dollar control option $dropEnv removes an environment variable. The log output follows:

%sysEnv.GEORGE%
Dantzig
%sysEnv.GEORGE%

The command line parameter compilerPreview allows running the input code through the upcoming fully compatible refactored version of the GAMS compiler and optionally also verifies the new compiler correctly processes the given input by generating a reference save file with the current default compiler. While this option (when used) is active for the specified input, it won't be applied to recursive calls to GAMS for example via a $call to GAMS. For this, one can use the environment variable GAMSPREVIEW which has the same choices (0-4) as compilerPreview but will also globally affect all GAMS invokations as long as the environment variable is set. In case both command line argument compilerPreview and environment variable GAMSPREVIEW are set with different values, the command line argument value is followed.

There are two environment variables in GAMS that are specific to the GDX facility: GDXCONVERT and GDXCOMPRESS. Since GDX is used by utilities and other programs some general customization can be achieved via these environment variables. Their values determine the type of GDX files that are written. These environment variables may be overwritten through the command line parameters gdxConvert and gdxCompress or inside the GAMS file with the dollar control option $setEnv. Consider the following example that uses the latter functionality:

Scalar x /1/;
$log %sysEnv.GDXCONVERT%
$log %sysEnv.GDXCOMPRESS%
$gdxOut x.gdx
$unLoad x
$gdxOut
$call gdxdump x.gdx -v | grep "File format\|Compression"

$setEnv GDXCONVERT v6
$setEnv GDXCOMPRESS 1
$gdxOut x.gdx
$unLoad x
$gdxOut
$call gdxdump x.gdx -v | grep "File format\|Compression"

$setEnv GDXCONVERT v7
$setEnv GDXCOMPRESS 0
$gdxOut x.gdx
$unLoad x
$gdxOut
$call gdxdump x.gdx -v | grep "File format\|Compression"

Note that gdxdump is a GDX utility that writes the contents of a GDX file as a GAMS formatted text file. The switch -v lets gdxdump print the file version information. With the grep utility we filter the lines that contain either File format or Compression. This code is run with the following call that initializes GDXCOMPRESS and GDXCONVERT:

> gams gdxenv.gms gdxCompress=0 gdxConvert=v6 lo=3

The output follows:

--- Starting compilation
v6
0
--- gdxenv.gms(7) 2 Mb
--- call gdxdump x.gdx -v | grep "File format\|Compression"
*  File format    :    6
*  Compression    :    0
--- gdxenv.gms(14) 2 Mb
--- call gdxdump x.gdx -v | grep "File format\|Compression"
*  File format    :    6
*  Compression    :    1
--- gdxenv.gms(21) 2 Mb
--- call gdxdump x.gdx -v | grep "File format\|Compression"
*  File format    :    7
*  Compression    :    0
--- gdxenv.gms(22) 2 Mb
--- Starting execution - empty program

Compile-Time Constants

Compile-time constants are constants that are related to some functions, model attributes or options. They have a fixed value and are referenced as %prefix.constant%. Here prefix is the name of the respective function, model attribute or option and constant is the name of the constant.

For example, the function handleStatus is used in the context of grid computing. Typically, a collection loop may take the following form:

loop(pp$(handleStatus(h(pp)) = 2), ... );

Alternatively, the following formulation may be used:

loop(pp$(handleStatus(h(pp)=%handleStatus.ready%), ... );

Observe that the compile-time constant %handleStatus.ready% equals the value of 2. See the table below for other compile-time constants that are related to the function handleStatus.

Note

Compile-time constants are replaced at compile time and cannot be manipulated or reassigned.

Though compile-time constants are most often used in the context of the function, model attribute or option indicated with the prefix, they are in fact context free and may be used anywhere where an integer is expected. Consider the following example:

Scalar x / %solPrint.on% /; display x;

A complete list of the compile-time constants is given in Table 2.

Table 2: Compile-Time Constants

Compile-Time Constant	value
%handleStatus.unknown%	0
%handleStatus.running%	1
%handleStatus.ready%	2
%handleStatus.failure%	3
%modelStat.optimal%	1
%modelStat.locallyOptimal%	2
%modelStat.unbounded%	3
%modelStat.infeasible%	4
%modelStat.locallyInfeasible%	5
%modelStat.intermediateInfeasible%	6
%modelStat.feasibleSolution%	7
%modelStat.integerSolution%	8
%modelStat.intermediateNonInteger%	9
%modelStat.integerInfeasible%	10
%modelStat.licensingProblem%	11
%modelStat.errorUnknown%	12
%modelStat.errorNoSolution%	13
%modelStat.noSolutionReturned%	14
%modelStat.solvedUnique%	15
%modelStat.solved%	16
%modelStat.solvedSingular%	17
%modelStat.unboundedNoSolution%	18
%modelStat.infeasibleNoSolution%	19
%platformCode.unknown%	0
%platformCode.DEX%	1
%platformCode.LEX%	2
%platformCode.WEX%	3
%platformCode.DAX%	4
%solPrint.off%	0
%solPrint.on%	1
%solPrint.silent%	2
%solPrint.summary% (deprecated)	0
%solPrint.report% (deprecated)	1
%solPrint.quiet% (deprecated)	2
%solveLink.chainScript%	0
%solveLink.callScript%	1
%solveLink.callModule%	2
%solveLink.asyncGrid%	3
%solveLink.asyncSimulate%	4
%solveLink.loadLibrary%	5
%solveLink.aSyncThreads%	6
%solveLink.threadsSimulate%	7
%solveOpt.replace%	0
%solveOpt.merge%	1
%solveOpt.clear%	2
%solveStat.normalCompletion%	1
%solveStat.iterationInterrupt%	2
%solveStat.resourceInterrupt%	3
%solveStat.terminatedBySolver%	4
%solveStat.evaluationInterrupt%	5
%solveStat.capabilityProblems%	6
%solveStat.licensingProblems%	7
%solveStat.userInterrupt%	8
%solveStat.setupFailure%	9
%solveStat.solverFailure%	10
%solveStat.internalSolverFailure%	11
%solveStat.solveProcessingSkipped%	12
%solveStat.systemFailure%	13

Command Line Parameters as Compile-Time Constants

The value of a command line parameter that was passed to the model can be accessed at compile time using the prefix 'gams' and the name of the command line parameter: %gams.parameter%. Example:

 > gams trnsport gdx=output.gdx

Trnsport.gms:

$setNames "%gams.input%" filepath filename fileextension
$log The input file '%filename%' is located in the directory %filepath%
$log All results are written to %gams.gdx%

Which results in the following log output:

The input file 'trnsport' is located in the directory C:\Users\robin\Documents\GAMS\Studio\workspace\
All results are written to C:\Users\robin\Documents\GAMS\Studio\workspace\output.gdx

In addition to compile time, the value of a command line parameter can also be accessed at execution time.

GAMS Compile Time and Execution Time Phase

The GAMS log indicates different phases of a job run in the log file:

...
--- Starting compilation
...
--- Starting execution: elapsed 0:00:00.056
...

During compilation GAMS converts the GAMS user program into lower-level instructions that are executed during execution time. Before the user program is converted into lower-level instructions the compiler processes the input: the compile time variables and macros are substituted and comments are removed. Moreover, during compilation any dollar control option present in the user code is executed. Many of these dollar control options impact the behavior of the compilation phase (e.g. $include instructs the compiler to process a file before continuing processing the remaining part of the current file). The code the compiler actually converts into lower-level instructions is echoed (by default) to the listing file. The compiler also assembles the list of user symbols (sets, parameters, variables, ...) and the list of labels. These lists become immutable after the compiler finishes. So during execution time, for example, no new labels can be added. The only exception from this is during a continued compilation/execution using the save and restart facility. The separation between compile time and execution time is confusing especially for novice users and mistakes as the following are frequent:

file fInput / data.txt /;
scalar iCnt; for (iCnt=1 to 100, put fInput iCnt:0:0 /); putClose fInput;
set i /
$include data.txt
      /;

The intention of the code, that does not work, is clear: The put facility is used to create the input file data.txt that is included via the $include instruction. The problem with this code is that the $include instruction is executed at compile time while the code using the put statement is executed at execution time, i.e. after the compilation phase is over. Hence, the compiler tries to include this file before the put instructions are executed. If the file data.txt is not present, the compiler will terminate with a compilation error, but if a file with name data.txt is present this one will be processed by the $include and a mistake like this might remain undiscovered for a long time.

Most of the time GAMS performs compilation and execution in one GAMS job which makes it even harder to grasp the concept of compile and execution time. The command line parameter action can be used to separate the compilation and execution phase into multiple jobs.

List of Command Line Parameters

In the following two subsections we will present an overview of the command line parameters with brief descriptions. Detailed descriptions of all command line parameters follow in section Detailed Descriptions of All Options below.

Note

The value of a command line parameter that was passed to the model can be accessed at compile time and at execution time.

General Options

Option	Description
action	GAMS processing request
appendExpand	Expand file append option
appendLog	Log file append option
appendOut	Output file append option
asyncSolLst	Print solution listing when asynchronous solve (Grid or Threads) is used
captureModelInstance	Switch to capture all model instances within a run
case	Output case option for LST file
cErr	Compile time error limit
charSet	Character set flag
checkErrorLevel	Check errorLevel automatically after executing external program
compilerPreview	Test current inputs with upcoming version of GAMS compiler and show problems in save file (see The Save and Restart Feature)
connectIn	Specify YAML Connect script file processed at start of GAMS
connectOut	Specify YAML Connect script file processed at end of GAMS
curDir	Current directory
decryptKey	Key to decrypt a text file that was encrypted via $encrypt
dFormat	Date format
digit	Switch default for "$on/offDigit"
docFile	Filename stem for documentation files
dumpOpt	Writes preprocessed input to the file input.dmp
dumpOptGDX	Defines a GDX file name stem created when using DumpOpt
dumpParms	GAMS parameter logging
dumpParmsLogPrefix	Prefix of lines triggered by DumpParms>1
ECImplicitLoad	Allow implicit loading of symbols from embedded code or not
empty	Switch default for "$on/offEmpty"
encryptKey	Key to encrypt a text file using $encrypt
eolCom	Switch default for "$on/offEolCom" and "$eolCom"
eolOnly	Single key-value pairs (immediate switch)
epsToZero	Treat eps as zero when unloading to GDX
errMsg	Placing of compilation error messages
errNam	Name of error message file
error	Force a compilation error with message
errorLog	Max error message lines written to the log for each error
etLim	Elapsed time limit in seconds
execMode	Limits on external programs that are allowed to be executed
expand	Expanded (include) input file name
fdDelta	Step size for finite differences
fdOpt	Options for finite differences
fErr	Alternative error message file
fileCase	Casing of file names and paths (put, gdx, ref, $include, etc.)
fileStem	Sets the file stem for output files which use the input file name as stem by default
fileStemApFromEnv	Append a string read from an environment variable to the "FileStem"
filtered	Switch between filtered and domain-checked read from GDX
forceWork	Force GAMS to process a save file created with a newer GAMS version or with execution errors
forLim	GAMS looping limit
G205	Use GAMS version 2.05 syntax
GDX	GAMS data exchange file name
gdxCompress	Compression of generated GDX file
gdxConvert	Version of GDX files generated (for backward compatibility)
gdxSymbols	Select symbols that get exported when command line parameter GDX is set
gdxUels	Unload labels or UELs to GDX either squeezed or full
gridDir	Grid file directory
gridScript	Grid submission script
heapLimit	Maximum Heap size allowed in MB
IDCGDXInput	GDX file name with data for implicit input
IDCGDXOutput	GDX file name for data for implicit output
IDCGenerateGDX	Specify GDX file name of input and output side of data contract
IDCGenerateGDXInput	Specify GDX file name of input side of data contract
IDCGenerateGDXOutput	Specify GDX file name of output side of data contract
IDCGenerateJSON	Specify JSON file name of data contract
IDCJSON	Specify JSON file name to verify data contract
IDCProtect	Flag to control assignment protection of external input symbols
IDE	Integrated Development Environment flag
implicitAssign	Switch default for "$on/offImplicitAssign"
inlineCom	Switch default for "$on/offInline" and "$inlineCom"
input	Input file
inputDir, inputDir1..40	Input file directories
interactiveSolver	Allow solver to interact via command line input
jobTrace	Job trace string to be written to the trace file at the end of a GAMS job
keep	Controls keeping or deletion of process directory and scratch files
libIncDir	LibInclude directory
license	Use alternative license file
listing	Switch default for "$on/offListing"
logFile	Log file name
logLine	Amount of line tracing to the log file
logOption	Log option
lstTitleLeftAligned	Write title of LST file all left aligned
maxExecError	Execution time error limit
maxGenericFiles	Maximum number of generic file names tried at execution time file creation
maxProcDir	Maximum number of 225* process directories
MCPRHoldFx	Print list of rows that are perpendicular to variables removed due to the holdfixed setting
MIIMode	Model Instance Mode
multi	Switch default for "$on/offMulti[R]"
multiPass	Multipass facility
noNewVarEqu	Triggers a compilation error when new equations or variable symbols are introduced
on115	Generate errors for unknown unique element in an equation
output	Listing file name
pageContr	Output file page control option
pageSize	Output file page size (=0 no paging)
pageWidth	Output file page width
parmFile	Command Line Parameter include file
pLicense	Privacy license file name
prefixLoadPath	Prepend GAMS system directory to library load path
previousWork	Indicator for writing workfile with previous workfile version
procDir	Process Directory
procDirPath	Directory to create process directory in
procTreeMemMonitor	Monitor the memory used by the GAMS process tree
procTreeMemTicks	Set wait interval between memory monitor checks: ticks = milliseconds
profile	Execution profiling
profileFile	Write profile information to this file
profileTol	Minimum time a statement must use to appear in profile generated output
putDir	Put file directory
putND	Number of decimals for put files
putNR	Numeric round format for put files
putPS	Page size for put files
putPW	Page width for put files
reference	Symbol reference file
referenceLineNo	Controls the line numbers written to a reference file
replace	Switch between merge and replace when reading from GDX into non-empty symbol
scrDir	Scratch directory
scrExt	Scratch file extension to be used with temporary files
scrNam	Work file names stem
seed	Random number seed
showOSMemory	Show the memory usage reported by the Operating System instead of the internal counting
stepSum	Summary of computing resources used by job steps
strictSingleton	Error if assignment to singleton set has multiple elements
stringChk	String substitution options
suffixAlgebraVars	Switch default for "$on/offSuffixAlgebraVars"
suffixDLVars	Switch default for "$on/offSuffixDLVars"
suppress	Compiler listing option
symbol	Symbol table file
sys10	Changes rpower to ipower when the exponent is constant and within 1e-12 of an integer
sys11	Dynamic resorting if indices in assignment/data statements are not in natural order
sys12	Pass model with generation errors to solver
sys15	Automatic switching of data structures used in search records
sys16	Disable search record memory (aka execute this as pre-GAMS 24.5)
sys17	Disable sparsity trees growing with permutation (aka execute this as pre-GAMS 24.5)
sys18	Use backward compatible (i.e. pre-GAMS 31) scheme for reading floating-point numbers
sys19	Disable permutation on Column Generation (aka execute this as pre-GAMS 36)
sysDir	GAMS system directory where GAMS executables reside
sysIncDir	SysInclude directory
tabIn	Tab spacing
tFormat	Time format
threadsAsync	Limit on number of threads to be used for asynchronous solves (solveLink=6)
timer	Instruction timer threshold in milli seconds
trace	Trace file name
traceLevel	Modelstat/Solvestat threshold used in conjunction with action=GT
traceOpt	Trace file format option
user1..5	User strings
warnings	Number of warnings permitted before a run terminates
workDir	Working directory
writeOutput	Switch to write output file
zeroRes	The results of certain operations will be set to zero if abs(result) LE ZeroRes
zeroResRep	Report underflow as a warning when abs(results) LE ZeroRes and result set to zero

Solver-Related Options

Option	Description
bRatio	Basis detection threshold
CNS	Constrained Nonlinear Systems - default solver
DNLP	Non-Linear Programming with Discontinuous Derivatives - default solver
domLim	Domain violation limit solver default
EMP	Extended Mathematical Programs - default solver
forceOptFile	Overwrites other option file section mechanism
holdFixed	Treat fixed variables as constants
holdFixedAsync	Allow HoldFixed for models solved asynchronously as well
integer1..5	Integer communication cells
intVarUp	Set mode for default upper bounds on integer variables
iterLim	Iteration limit of solver
limCol	Maximum number of columns listed in one variable block
limRow	Maximum number of rows listed in one equation block
LP	Linear Programming - default solver
MCP	Mixed Complementarity Problems - default solver
MINLP	Mixed-Integer Non-Linear Programming - default solver
MIP	Mixed-Integer Programming - default solver
MIQCP	Mixed Integer Quadratically Constrained Programs - default solver
MPEC	Mathematical Programs with Equilibrium Constraints - default solver
NLP	Non-Linear Programming - default solver
nodLim	Node limit in branch and bound tree
optCA	Absolute Optimality criterion solver default
optCR	Relative Optimality criterion solver default
optDir	Option file directory
optFile	Default option file
QCP	Quadratically Constrained Programs - default solver
resLim	Wall-clock time limit for solver
RMINLP	Relaxed Mixed-Integer Non-Linear Programming - default solver
RMIP	Relaxed Mixed-Integer Programming - default solver
RMIQCP	Relaxed Mixed Integer Quadratically Constrained Programs - default solver
RMPEC	Relaxed Mathematical Programs with Equilibrium Constraints - default solver
savePoint	Save solver point in GDX file
scriptExit	Program or script to be executed at the end of a GAMS run
scriptFrst	First line to be written to GAMSNEXT file.
solPrint	Solution report print option
solveLink	Solver link option
solver	Default solver for all model types that the solver is capable to process
solverCntr	Solver control file name
solverDict	Solver dictionary file name
solverInst	Solver instruction file name
solverMatr	Solver matrix file name
solverSolu	Solver solution file name
solverStat	Solver status file name
subSys	Name of subsystem configuration file
sysOut	Solver Status file reporting option
threads	Number of processors to be used by a solver
workFactor	Memory Estimate multiplier for some solvers
workSpace	Work space for some solvers in MB

Save and Restart Options

Option	Description
fSave	Creates a forced work file, i.e., the file is saved even if execution errors or other errors occured
restart	Name of a restart file, see The Save and Restart Feature
restartNamed	Name of another matching restart file, see Obfuscated Work Files
save	Creates a work file, see The Save and Restart Feature
saveObfuscate	Creates an obfuscated work file, see Obfuscated Work Files
symPrefix	Prefix all symbols encountered during compilation by the specified string in work file
xSave	Creates a compressed work file
xSaveObfuscate	Creates a compressed obfuscated work file

Detailed Descriptions of All Options

In this section we will give detailed descriptions of all options that may be used as command line parameters, in option statements or as model attributes.

Note

• We indicate for each entry the context in which the option is available.
• The options are listed in alphabetical order for easy reference.
• Synonyms apply only to options set via the command line.

action (string): GAMS processing request

Synonym: A

Available: Command line

This option controls the way GAMS processes the input file. In particular GAMS currently processes the input file in multiple phases and this allows one to restrict the phases used. The two phases in order are:

• Compilation During this pass, the file is compiled, and syntax errors are checked for. Data initialization statements like scalar, parameter, and table statements are also processed during this stage.
• Execution During this stage, all execution time statements including assignments, loops, and solves are executed.

The special action GT is related to the creation of trace reports. See also option traceLevel for details.

Default: CE

Value	Meaning
R	Restart After Solve
C	CompileOnly
E	ExecuteOnly
CE	Compile and Execute
GT	Trace Report

appendExpand (boolean): Expand file append option

Synonym: AE

Available: Command line

This option controls the manner of file opening of the option expand.

Default: 1

Value	Meaning
0	Reset expand file
1	Append to expand file

appendLog (boolean): Log file append option

Synonym: AL

Available: Command line

This option is used in conjunction with the setting of logOption to 2 and 4, where the log from the GAMS run is redirected to a file. Setting this option to 1 will ensure that the log file is appended to and not overwritten (replaced).

Default: 0

Value	Meaning
0	Reset log file
1	Append to logfile

appendOut (boolean): Output file append option

Synonym: AO

Available: Command line

Setting this option to 1 will ensure that the listing file is appended to and not overwritten (replaced).

Default: 0

Value	Meaning
0	Reset listing file
1	Append to listing file

asyncSolLst (boolean): Print solution listing when asynchronous solve (Grid or Threads) is used

Available: Command line, Option statement

This option determines whether the solution listing is printed in the listing file when an asynchronous (grid or threads) solve is used and the function handleCollect or command execute_loadHandle successfully collect the results.

Default: 0

Value	Meaning
0	Do not print solution listing into lst file for asynchronous solves
1	Print solution listing into lst file for asynchronous solves

bRatio (real): Basis detection threshold

Available: Command line, Option statement, Attribute statement (use before solve)

The bRatio value is used to detect whether the initial point (levels and marginals) passed to the solver represents a basis suitable for use by the solver.

Certain (pivotal) solution procedures can restart from an advanced basis that is constructed automatically using existing basis information, i.e. they do a warm start. This option is used to influence whether a warm start is done or not. GAMS provides a hint to the solver to suggest whether a basis can or might be extracted from the initial point. The hint is based on the number of rows with nonzero marginals and is computed internally as:

  hint := (0 == bRatio) or (rowsWithNonzeroMarg > nRows * bratio)

Note that setting bRatio to 1 causes the hint to be false, while setting bRatio to 0 causes the hint to be true. Note also that this is only a hint to the solver: some solvers (e.g. barrier methods) do not use this hint value.

Default: 0.25

captureModelInstance (boolean): Switch to capture all model instances within a run

Available: Command line

This option is a debugging option that helps to capture, if set to 1, the model instances that are generated and solved during the execution of the solve commands in a GAMS run. This is particularly important if one needs to make a model instance available to GAMS technical support to investigate a solver failure or analyze poor solver performance. The model instances are stored in separate files with names gamsNNN.gms where NNN is an increasing number. So sorting the files by time or name will correspond to the order in which these instances have been generated and solved. The format of the model instance is the GAMS scalar format and the instance is captured before the instance is solved by the selected solver, hence it contains the starting point but not the solution point.

Another way of capturing model instances becomes useful (and is triggered independent of this option) in case the user model does modularization by calling other GAMS programs that execute a solve statement via the GAMS executable. Since options are not automatically passed on to the GAMS subprocesses one might miss capturing some model instances. Moreover, due to constant folding and rounding in the scalar model format, the run of a scalar model instance might not reproduce a particular problematic issue of the original solve. Hence GAMS can capture the binary scratch files produced by the solve statement when executed under solveLink=0 in a ZIP file. This is activated by setting a system environment variable named ZIPSCRDIR_PGAMS (e.g. set ZIPSCRDIR_PGAMS=mymodel). The content of this environment variable is used as a prefix for the ZIP file names, e.g. mymodelNNN.zip where NNN is an increasing number. Such ZIP files can help GAMS support staff to execute the model and have an increased chance to reproduce a problematic issue.

Note

CaptureModelInstance cannot be used with solveLink=6/7. If this was set, GAMS will reset solveLink to 3/4 automatically.

Default: 0

Value	Meaning
0	Do not capture model instances
1	Capture model instances

case (boolean): Output case option for LST file

Available: Command line

This option controls the case of the text in the listing file.

Default: 0

Value	Meaning
0	Write listing file in mixed case
1	Write listing file in upper case only

cErr (integer): Compile time error limit

Available: Command line

The compilation will be aborted after n errors have occurred. By default, there is no error limit and GAMS compiles the entire input file and collects all the compilation errors that occur. If the file is too long and the compilation process is time consuming, cerr could be used to set to a low value while debugging the input file.

Default: 0

Value	Meaning
0	No error limit (default)
n	Stop after n errors

charSet (boolean): Character set flag

Available: Command line

This option specifies whether foreign language characters are permitted in comments and text items. For a list of standard GAMS characters, see table Legal Characters.

Default: 1

Value	Meaning
0	Use limited GAMS characters set
1	Accept any character in comments and text items (foreign language characters)

cheat (real): Cheat value, i.e. minimum solution improvement threshold

Available: Attribute statement (use before solve)

For a branch-and-bound based solver, each new feasible solution must be at least the value of cheat better than the current best feasible solution. Note that this may speed up the search, but may cause some solutions, including optimal ones, to be missed. If a model has been solved with a nonzero cheat value, then the optimal solution will be within the cheat value or less of the found solution. Observe that the option cheat is specified in absolute terms (like the option optCA), therefore non-negative values are appropriate for both minimization and maximization models. Note that using this option will invalidate any reporting of the dual bound or optimality gaps. Further, certain solver options can override the cheat setting, e.g., the Cplex option objDif, and some solvers may ignore the cheat option.

Default: 0

checkErrorLevel (boolean): Check errorLevel automatically after executing external program

Available: Command line, Option statement

If this option is set to 1, the errorLevel is checked implicitly after executing an external program or via execute, put_utility exec and put_utility shell. The same holds for the execution of a tool from the GAMS tools library via executeTool. An execution error is triggered and the execution is aborted, if it is not 0. So, with checkErrorLevel = 1 the before mentioned statement behave like execute.checkErrorLevel, put_utility exec.checkErrorLevel, put_utility shell.checkErrorLevel, and executeTool.checkErrorLevel, respectively.

Also, if this option is set as a command line parameter it initializes the state of the dollar control option $on/offCheckErrorLevel. So, with checkErrorLevel = 1, the errorLevel is checked implicitly after $call and $hiddenCall. The same holds for calls to a tool from the GAMS tools library via $callTool and $hiddenCallTool. A compilation error is triggered and the compilation is aborted if that is not 0. So, the dollar control options mentioned before behave like $call.checkErrorLevel, $hiddenCall.checkErrorLevel, $callTool.checkErrorLevel, and $hiddenCallTool.checkErrorLevel respectively.

Default: 0

Value	Meaning
0	Do not check errorLevel automatically after execution of external program
1	Check errorLevel automatically after execution of external program

CNS (string): Constrained Nonlinear Systems - default solver

Available: Command line, Option statement

The default solver for models of the type Constrained Nonlinear Systems is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

compilerPreview (integer): Test current inputs with upcoming version of GAMS compiler and show problems in save file (see The Save and Restart Feature)

Synonym: CP

Available: Command line

The GAMS compiler will eventually be replaced by a new fully compatible executable that is based on a refactoring of its codebase. To make sure your models keep compiling correctly with the new GAMS compiler executable, the CompilerPreview option offers multiple modes that run the current reference compiler and the new compiler sequentially (cp values 1 and 2) or in parallel (cp value 3) to produce two workfiles for comparison.

Ideally, the workfiles should be matching bytewise. In case there are any differences, the workfiles are both converted into YAML format and the differences are listed. We encourage users to report these differences to us, so we can investigate where the new compiler breaks compatibility and fix it accordingly.

Alternatively CompilerPreview can be used to only run either

• the current (default) reference compiler (cp value 0) or
• the upcoming "new" compiler (via cp value 4).

While the CompilerPreview option is only locally active in the GAMS call and does not propagate to children processes for example when encountering a $call to GAMS (without option Compiler Preview), the environment variable GAMSPREVIEW follows the same logic as CompilerPreview but is affecting GAMS processes system wide. For more information take a look at environment variables. It is important to note the CompilerPreview option choice always dominates whatever is set in GAMSPREVIEW (in case both are set and have divergent values).

Default: 0

Value	Meaning
0	only use current (default) reference compiler
1	compile input with both compilers (current and upcoming) sequentially and show and abort on save file mismatch
2	compile input with both compilers (current and upcoming) sequentially and show but ignore save file mismatch
3	compile input with both compilers (current and upcoming) in parallel and show and abort on save file mismatch
4	only use upcoming "new" compiler

connectIn (string): Specify YAML Connect script file processed at start of GAMS

Available: Command line

The YAML file provided by this command line parameter is passed to and processed by Connect. This allows Connect to prepare data for import at the beginning of a GAMS job. The GAMS program itself does not need to know where the various data files (CSV, Excel, etc) are located. The supply side of the data contract is encapsulated in the YAML script.

Here is an example. The content of the file p.yaml that is supplied via the option connectIn could look like this:

- ExcelReader:
    file: myworkbook.xlsx
    symbols:
        - name: p
          range: Sheet1!A1
          rowDimension: 1
          columnDimension: 1
- GDXWriter:
    file: input.gdx
    symbols:
        - name: p

The GDX file input.gdx can be loaded at the beginning of a GAMS job using gdxLoad:

Set i, j;
Parameter p(i<,j<);
$gdxLoad input.gdx p
display p;

Alternatively, this can be nicely combined with the IDCGDXInput to load external input symbols. The GDX file input.gdx can be specified as value for IDCGDXInput (gams mymodel connectIn=p.yaml IDCGDXInput=input.gdx):

Set i, j;
$onExternalInput
Parameter p(i<,j<) / i1.j1 1 /;
$offExternalInput
display p;

The YAML code in the connectIn file can also utilize the GAMSReader agent. Normally, there are no symbols to read at the job's start, but in case the job restarts from an existing work file (see command line option restart) the symbols available from the work file can be read into the Connect database with the GAMSReader agent. The YAML code in the connectIn file can utilize the GAMSWriter agent. It will update the symbols and data read from the restart file at the beginning of the GAMS compilation phase.

connectOut (string): Specify YAML Connect script file processed at end of GAMS

Available: Command line

The YAML file provided by this command line parameter is passed to and processed by Connect. This allows Connect to take the GAMS data at the end of the GAMS job and export it to various formats (CSV, Excel, etc) according to the instructions in the YAML file.

Here is an example. The content of the file p.yaml that is supplied via the option connectOut could look like this:

- GDXReader:
    file: output.gdx
    symbols:
        - name: p
- ExcelWriter:
    file: myworkbook.xlsx
    symbols:
        - name: p
          range: Sheet!A1
          columnDimension: 1

The GDX file output.gdx can be written at the end of a GAMS job using execute_unload:

Set i /i1*i10/, j /j1*j10/;
Parameter p(i,j); p(i,j) = uniform(0,1);
execute_unload 'output.gdx', p;

Alternatively, this can be nicely combined with the IDCGDXOutput to process external output symbols. The GDX file output.gdx can be specified as value for IDCGDXOutput (gams mymodel connectOut=p.yaml IDCGDXOutput=output.gdx):

Set i /i1*i10/, j /j1*j10/;
$onExternalOutput
Parameter p(i,j); p(i,j) = uniform(0,1);
$offExternalOutput

The YAML code in the connectOut file can also utilize the GAMSReader agent. This reads directly from GAMS memory (without the detour via GDX) and processes any symbol available at the end of the GAMS run. The YAML code in the connectOut file cannot utilize the GAMSWriter agent.

curDir (string): Current directory

Synonym: CDir

Available: Command line

This option sets the current working directory. It is useful when GAMS is called from an external system like Visual Basic. If it is not specified, it will be set to the directory the GAMS module is called from.

cutOff (real): Cutoff value for branch and bound

Available: Attribute statement (use before solve, reset by solve statement)

Within a branch-and-bound based solver, the parts of the tree with an objective value worse than the cutoff value are ignored. Note that this may speed up the initial phase of the branch and bound algorithm (before the first integer solution is found). However, the true optimum may be beyond the cutoff value. In this case the true optimum will be missed and moreover, no solution will be found.

Observe that this option is specified in absolute terms (like the option optCA).

Default: 0

decimals (integer): Decimal places for display statements

Available: Option statement

This option specifies the number of decimals that will be printed for numeric values that do not have a specific print format attached. The range is [0,8].

Default: 3

decryptKey (string): Key to decrypt a text file that was encrypted via $encrypt

Available: Command line

This option provides a key to decrypt a GAMS input file that has been encrypted with a key provided by encryptKey and $encrypt. For more information, see Encrypting Files.

defPoint (integer): Indicator for passing on default point

Available: Attribute statement (use before solve, reset by solve statement)

This option determines the point that is passed to the solver as a basis. By default, the levels and marginals from the current basis are passed to the solver. In some circumstances (mostly during debugging), it can be useful to pass a standard default input point, i.e. with all levels set to 0 or lower bound.

Value	Meaning
0	Pass user defined levels and marginals to solver
1	Pass default levels and marginals to solver
2	Pass default marginals to solver

dFormat (integer): Date format

Synonym: DF

Available: Command line

This option controls the date format in the listing file. The three date formats correspond to various conventions used around the world. For example, the date December 2, 1996 will be written as 12/02/96 with the default df value of 0, as 02.12.96 with df=1, and as 96-12-02 with df=2.

Default: 0

Value	Meaning
0	Date as mm/dd/yy
1	Date as dd.mm.yy
2	Date as yy-mm-dy

dictFile (real): Force writing of a dictionary file if dictfile > 0

Available: Attribute statement (use before solve, reset by solve statement)

If this option is set to a value that is larger than zero, it will instruct GAMS to make the GAMS names of variables and equations that have been generated by the solve statement available to the solver. In many solver links these names are registered with the solver and hence messages from the solver that involve variables and equations (e.g. an infeasible row or duplicate columns) can be easily interpreted by the user. Consider the following example:

Row 'demand(new-york)' infeasible, all entries at implied bounds.

Duplicate columns x(san-diego.new-york) and x(san-diego.chicago) make problem unbounded.

If we have modelname.dictfile=0 the same messages will read as follows:

Row 'c4' infeasible, all entries at implied bounds.

Duplicate columns x4 and x5 make problem unbounded.

Sometimes a dictionary is required for a successful run. Some solver option use the original GAMS names and need to be matched with the variables 1..n and equations 1..m in the solver. The dictionary file with its API allows to calculate such a mapping. Note that this is done automatically inside the solver links, so users do not need to be concerned with it.

For example, in the indicator constraints implementation a binary indicator variable is matched to a constraint. In the model [INDIC01] from the GAMS test library, this matching is done in the following GAMS/Cplex option file cplex.opt:

indic eq3(dice,f,fp)$comp(dice,f,fp) 1

Observe that if no dictionary is available, we will get an error:

**** Unable to read dictionary file required for indicator constraints

However, the dictionary comes at a price. Generating the names and calculating and storing the map takes time and space. In addition, GAMS names take up space in the solver. Thus, if the user needs very fast generation and does not need names, setting dictFile to zero is a good option.

Further, note that some solvers allow to suppress the loading of names (using the solver option names=no). Suppressing the loading of names facilitates to use the name mapping features required for models like INDIC01 above, but does not load the names into the solver name space for better reporting (and hence saves some space).

digit (string): Switch default for "$on/offDigit"

Available: Command line

For more info see $on/offDigit.

Default: off

Value	Meaning
off	Activate $offDigit
on	Activate $onDigit

dispWidth (integer): Number of characters to be printed in the column labels of all subsequent display statements

Available: Option statement

This option controls the number of characters that are shown for a label in a column in the context of the display statement. Consider the following example:

 Set i / thislabelhas24characters /;
 Parameter p(i,i) / thislabelhas24characters.thislabelhas24characters 2/;
 display p;

 option dispWidth=24;
 display p;

The two display statements in this code will generate the following output:

----      3 PARAMETER p

                          thislabel~

thislabelhas24characters       2.000

----      6 PARAMETER p

                          thislabelhas24characters

thislabelhas24characters                     2.000

Observe that in the first display, the label in the column is cut off after 10 characters, while in the second display it is shown in full.

Note that the default value is 10 and the range is [10,31].

Default: 10

dmpOpt (no value): Debugging option: causes GAMS to echo the runtime option settings

Available: Option statement

This debugging option has the effect that all available option statements and their current values are listed in the listing file.

dmpSym (no value): Debugging option: causes GAMS to echo the symbol table to the listing file

Available: Option statement

This debugging option is especially useful for diagnosing memory problems. It has the effect that GAMS will report the number of elements that are stored for each identifier at the point in the program where this option is inserted together with a memory estimate. The report that is generated in this way is called a memory dump. This is similar to the option dmpUserSym, but prints GAMS internal symbols and information as well. For details, see section Finding the Causes for Excessive Memory Use.

dmpUserSym (no value): Debugging option: causes GAMS to echo the symbol table to the listing file for user defined symbols only

Available: Option statement

This debugging option is especially useful for diagnosing memory problems. It has the effect that GAMS will report the number of elements that are stored for each identifier at the point in the program where this option is inserted together with a memory estimate. The report that is generated in this way is called a memory dump. This is similar to the option dmpSym, but prints user defined symbols only and also leaves out some very technical information which are mostly for internal use. For details, see section Finding the Causes for Excessive Memory Use.

DNLP (string): Non-Linear Programming with Discontinuous Derivatives - default solver

Available: Command line, Option statement

The default solver for models of the type Nonlinear Programs with Discontinuous Derivatives is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

docFile (string): Filename stem for documentation files

Available: Command line

domLim (integer): Domain violation limit solver default

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the maximum number of domain errors (undefined operations like division by zero) a nonlinear solver will perform, while calculating function and derivative values, before it terminates the run and returns solver status 5 EVALUATION ERROR LIMIT. Nonlinear solvers have difficulties recovering after attempting an undefined operation. Note that some solvers operate in a mode where trial function evaluations are performed. These solvers will not move to points at which evaluation errors occur, thus the evaluation errors at trial points are not counted against the limit.

Default: ∞

domUsd (integer): Number of domain violations

Available: Attribute statement (use after solve)

This model attribute returns the number of domain violations after a solve.

dualCheck (integer): Output on the reduced cost condition

Available: Option statement

If this option is set to 1, the reduced cost condition for each variable in the column listing will be evaluated using the equation marginals. The default value is zero, which means that the calculation will be omitted.

Default: 0

dumpOpt (integer): Writes preprocessed input to the file input.dmp

Available: Command line

This option with value larger than 9 creates a GAMS input file of that will reproduce results encapsulating all include files into one GAMS file. If activated, a file will be written containing GAMS source code for the entire problem. The file name is the input file name with the extension dmp. For values smaller than 10, this option tries to encapsulate all the items from a restart file that are needed to execute a solve.

For the values smaller than 10, consider the following example. We will split the transportation model [TRNSPORT] into two files and run them with the save and restart feature. Then we will illustrate the option dumpOpt. The first file called trans1.gms contains the first part of the model up to and including the model statement:

Sets
       i   canning plants   / seattle, san-diego /
       j   markets          / new-york, chicago, topeka / ;

Parameters
       a(i)  capacity of plant i in cases
         /    seattle     350
              san-diego   600  /

       b(j)  demand at market j in cases
         /    new-york    325
              chicago     300
              topeka      275  / ;

Table d(i,j)  distance in thousands of miles
                    new-york       chicago      topeka
      seattle          2.5           1.7          1.8
      san-diego        2.5           1.8          1.4  ;

Scalar f  freight in dollars per case per thousand miles  /90/ ;

Parameter c(i,j) transport cost in thousands of dollars per case ;
c(i,j) = f * d(i,j) / 1000 ;

Variables
    x(i,j)  shipment quantities in cases
    z       total transportation costs in thousands of dollars ;
Positive Variable x ;

Equations
    cost        define objective function
    supply(i)   observe supply limit at plant i
    demand(j)   satisfy demand at market j ;

cost ..        z  =e=  sum((i,j), c(i,j)*x(i,j)) ;
supply(i) ..   sum(j, x(i,j))  =l=  a(i) ;
demand(j) ..   sum(i, x(i,j))  =g=  b(j) ;

model transport /all/ ;

Note that we removed all comments for brevity. The second file called trans2.gms contains the solve statement and the display statement:

solve transport using lp minimizing z ;
display x.l, x.m ;

We run the first file with the command line parameter save and thus generate a work file. For details on work files, see chapter The Save and Restart Feature. Then we run trans2.gms restarting from the saved work file. The result will be equivalent to running the original model [TRNSPORT].

Note

The option dumpOpt can only be used effectively, if the first line in the second file, trans2.gms, is the solve statement.

Now, we will illustrate the use of the option dumpopt, by running the second file with the following command:

   > gams trans2 r=trans dumpopt=1

Here trans is the name of the saved files generated from the file trans1.gms. As a result of this call, a new file will be created. It is called trans2.dmp and has the following content:

* This file was written with DUMPOPT=1 at 11/25/21 15:15:17
*
*      INPUT = C:\tmp\trans2.gms
*       DUMP = C:\tmp\trans2.dmp
*    RESTART = C:\tmp\0.g0?
*
*           with time stamp of 11/16/21 17:18:53
*
* You may have to edit this file and the input file.

* There are 5 labels

Set WorkFileLabelOrder dummy set to establish the proper order /
   seattle,san-diego,new-york,chicago,topeka /;

Model transport;

Variable z 'total transportation costs in thousands of dollars';

Set i(*) 'canning plants' /
   seattle,san-diego /;

Set j(*) 'markets' /
   new-york,chicago,topeka /;

Parameter c(i,j) 'transport cost in thousands of dollars per case' /
   seattle.new-york 0.225,seattle.chicago 0.153,seattle.topeka 0.162,san-diego.new-york 0.225,san-diego.chicago 0.162,san-diego.topeka 0.126 /;

Positive Variable x(i,j) 'shipment quantities in cases';

Parameter a(i) 'capacity of plant i in cases' /
   seattle 350,san-diego 600 /;

Parameter b(j) 'demand at market j in cases' /
   new-york 325,chicago 300,topeka 275 /;

Equation demand(j) 'satisfy demand at market j';

Equation supply(i) 'observe supply limit at plant i';

Equation cost 'define objective function';

*      *** EDITS FOR INPUT FILE ***

*** END OF DUMP ***

Note that all the data that enters the model in the solve statement has been regenerated. Observe that the parameter d has not been regenerated since it does not appear in the model. Changing the value of the parameter dumpopt will have the effect that other names are used for the identifiers in the regenerated file, see table below.

Note

If $onVerbatim is active, DumpOpt = 11 behaves like DumpOpt = 21 (comments are kept)

See also dumpOptGDX.

Default: 0

Value	Meaning
0	No dumpfile
1	Extract referenced data from the restart file using original set element names
2	Extract referenced data from the restart file using new set element names
3	Extract referenced data from the restart file using new set element names and drop symbol text
4	Extract referenced symbol declarations from the restart file
11	Write processed input file without comments
21	Write processed input file with all comments
22	Write processed input with all comments into a separate dump file for each block

dumpOptGDX (string): Defines a GDX file name stem created when using DumpOpt

Available: Command line

This parameter works together with the dumpOpt parameter. If that is set to 1, 11 or 21 while dumpOptGDX is set, GAMS will create a GDX file with the data used in the dump file instead of data statements, and the dump file will load the data from that GDX file. So, with the parameter dumpOptGDX=trns2 the example above would generate the following dump file:

* This file was written with DUMPOPT=1 at 11/25/21 15:14:11
*
*      INPUT = C:\tmp\trans2.gms
*       DUMP = C:\tmp\trans2.dmp
*    RESTART = C:\tmp\0.g0?
* DUMPOPTGDX = trans2
*
*           with time stamp of 11/16/21 17:18:53

$gdxIn trans2.gdx

*
* You may have to edit this file and the input file.

* There are 5 labels

Set WorkFileLabelOrder dummy set to establish the proper order;
$loadDCR WorkFileLabelOrder=*

Model transport;

Variable z 'total transportation costs in thousands of dollars';

Set i(*) 'canning plants';
$loadDCR i

Set j(*) 'markets';
$loadDCR j

Parameter c(i,j) 'transport cost in thousands of dollars per case';
$loadDCR c

Positive Variable x(i,j) 'shipment quantities in cases';

Parameter a(i) 'capacity of plant i in cases';
$loadDCR a

Parameter b(j) 'demand at market j in cases';
$loadDCR b

Equation demand(j) 'satisfy demand at market j';

Equation supply(i) 'observe supply limit at plant i';

Equation cost 'define objective function';

$gdxIn

*      *** EDITS FOR INPUT FILE ***

*** END OF DUMP ***

Note that more than one GDX file could be created with a common file stem defined by this parameter. This will be necessary if the source model has multiple data definitions for the same symbol like in this simple example:

Set       i    / i1*i3/;
Parameter a(i) / i1 1, i2  2/;
$onMulti
Parameter a(i) / i1 0, i3  3/;
Scalar    b    /  7 /;
Scalar    b    / 77 /;

Running this as

   > gams dummy dumpOpt=11 dumpOptGDX=dummyIn

will generate this dump file:

* This file was written with DUMPOPT=11 at 11/25/21 15:26:02
*
*       DUMP = C:\tmp\dummy.dmp
*      INPUT = C:\tmp\dummy.gms
*    RESTART =
* DUMPOPTGDX = dummyIn
*

$gdxIn dummyIn.gdx

Set       i
$loadDCR i
;
Parameter a(i)
$loadDCR a
;
$onMulti
Parameter a(i)
$gdxIn dummyIn_m1.gdx
$loadDCR a
;
Scalar    b
$loadDCR b
;
Scalar    b
$gdxIn dummyIn_m2.gdx
$loadDCR b
;
* *** EXIT       C:\Data\gspTest\dummy.gms

$gdxIn
*** END OF DUMP ***

And this is the data found in the GDX files:

dummyIn.gdx:

Set i(*) /
'i1',
'i2',
'i3' /;

Parameter a(*) /
'i1' 1,
'i2' 2 /;

dummyIn_m1.gdx:

Parameter a(*) /
'i2' 2,
'i3' 3 /;

Scalar b / 7 /;

dummyIn_m2.gdx:

Scalar b / 77 /;

dumpParms (integer): GAMS parameter logging

Synonym: DP

Available: Command line

This option lists the settings of all command line parameters that were changed or set by the user, GAMS or an IDE during the current run. Note that with dp=2 all file operations are listed, including the full path of each file on which any operation is performed.

Default: 0

Value	Meaning
0	No logging
1	Lists accepted/set parameters
2	Log of file operations plus list of accepted/set parameters

dumpParmsLogPrefix (string): Prefix of lines triggered by DumpParms>1

Synonym: DPLP

Available: Command line

This option prefixes in the log file the list of all command line parameters that were changed or set by the user, GAMS or an IDE during the current run. Note that the option dumpParms must be greater than 1 for dumpParmsLogPrefix to have an effect.

Default: ***

ECImplicitLoad (string): Allow implicit loading of symbols from embedded code or not

Available: Command line, Option statement

The command line parameter ECImplicitLoad initializes both, the option ECImplicitLoad and the dollar control option $on/offECImplicitLoad for the compile-time equivalent behavior.

Default: on

Value	Meaning
off	Do not allow implicit loading from embedded code
on	Allow implicit loading from embedded code

eject (no value): Inject a page break into the LST file

Available: Option statement

This option has the effect that a page break is inserted in the listing file.

EMP (string): Extended Mathematical Programs - default solver

Available: Command line, Option statement

The default solver for models of the type Extended Mathematical Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

empty (string): Switch default for "$on/offEmpty"

Available: Command line

For more info see $on/offEmpty.

Default: on

Value	Meaning
off	Activate $offEmpty
on	Activate $onEmpty

encryptKey (string): Key to encrypt a text file using $encrypt

Available: Command line

This option provides a key to encrypt a text file via $encrypt. For more information, see Encrypting Files.

eolCom (string): Switch default for "$on/offEolCom" and "$eolCom"

Available: Command line

If this is set to on on or off it sets the state of $on/offEOLCom. Other strings (with not more than two characters) will set $EOLCom.

Default: off

Value	Meaning
off	Activate $offEolCom
on	Activate $onEolCom using default EOL comment character
other	Activate $onEolCom setting specific EOL comment character(s)

eolOnly (integer): Single key-value pairs (immediate switch)

Synonym: EY

Available: Command line

This option controls formatting of parameters on the command line and is useful in conjunction with the option parmFile.

This option acts as an immediate switch that forces only one option-value pair to be read on a line. Note that by default, any number of option-value pairs may be present on the same line and termination characters and quoting is necessary to determine the end of key/value pair. With this option active the remainder after the key is used as the value independent of quoting or termination characters.

Default: 0

Value	Meaning
0	Any number of keys or values
1	Only one key-value pair on a line

epsToZero (string): Treat eps as zero when unloading to GDX

Available: Command line, Option statement

When this is set to on, EPS values are written as zero when unloading parameters or variable and equation levels to GDX at execution time. The command line parameter EpsToZero initializes both, the option EpsToZero and the dollar control option $on/offEpsToZero for the compile-time equivalent behavior.

Default: off

Value	Meaning
off	Treat Eps as Eps
on	Treat Eps as Zero

errMsg (integer): Placing of compilation error messages

Available: Command line

This option controls the position of the compilation error messages in the listing file. To illustrate the option, consider the following slice of GAMS code:

Set       i     / 1*10 / ;
Set       j(i)  / 10*11 /;
Parameter a(jj) / 12 25.0 / ;

After running this code, the listing file will contain the following lines:

   1  Set       i     / 1*10 / ;
   2  Set       j(i)  / 10*11 /;
****                        $170
   3  Parameter a(jj) / 12 25.0 / ;
****               $120
   4

120  Unknown identifier entered as set
170  Domain violation for element

**** 2 ERROR(S)   0 WARNING(S)

Note that numbers $170 and $120 flag the two errors as they occur, but the errors are explained only at the end of the compilation output. However, if the code is run using the option errmsg=1, the resulting listing file will contains the following:

   1  Set       i     / 1*10 / ;
   2  Set       j(i)  / 10*11 /;
****                        $170
**** 170  Domain violation for element
   3  Parameter a(jj) / 12 25.0 / ;
****               $120
**** 120  Unknown identifier entered as set
   4
**** 2 ERROR(S)   0 WARNING(S)

Observe that the explanation for each error is provided immediately following the error marker.

Default: 1

Value	Meaning
0	Place error messages at the end of compiler listing
1	Place error messages immediately following the line with the error
2	Suppress error messages

errNam (string): Name of error message file

Available: Command line

This option specifies the name of a file defining the internally used compiler error messages. It is used to change the name from the default name gamserrs.txt.

error (string): Force a compilation error with message

Available: Command line

This option forces a parameter error with a specified message. It is useful in the context of incorporating a GAMS file within another batch file where the user needs to have control over the conditions when GAMS is called. See also section Conditional Compilation.

To illustrate, the default GAMS log file from running a model with the option error=Hallo will look as follows:

gams: **** Error: Parameter error(s)
    :             Reading parameter(s) from "command line"
    :             *** Error Hallo
    :             Finished reading from "command line"

errorLog (integer): Max error message lines written to the log for each error

Synonym: ER

Available: Command line

This option controls the number of error message lines that are written to the log file.

Under GAMS Studio, the default is reset to 99.

Default: 2147483647

Value	Meaning
0	No error messages to LOG file
n	Number of lines for each error that will be written to LOG file

etAlg (real): Solver dependent timing information

Available: Attribute statement (use after solve)

Unlike etSolve and etSolver, this attribute is set by the individual solver links. If not set, it defaults to NA. This attribute was intended to allow solvers to return the elapsed time used by the solve algorithm without including any model generation, communication, or setup time. However, solvers are free to adapt this convention and return time-related information (but not necessarily elapsed time) for executing the solve algorithm. Please inspect your solver manual for the actual meaning of the value returned in this attribute.

etLim (real): Elapsed time limit in seconds

Synonym: ETL

Available: Command line

This option controls the time limit for a GAMS job. The system will terminate with a compilation or execution error if the limit is reached. A GAMS job will terminate if the elapsed time in seconds exceeds the value of etLim. If a solve statement gets executed, and the resLim for the model to be solved is greater than etLim - timeElapsed, resLim will be reduced automatically.

Default: ∞

etSolve (real): Elapsed time it took to execute a solve statement in total

Available: Attribute statement (use after solve)

This model attribute returns the elapsed time it took to execute a solve statement in total. This time includes the model generation time, the time to read and write files, the time to create the solution report and the time taken by the actual solve. The time is expressed in seconds of wall-clock time.

etSolver (real): Elapsed time taken by the solver only

Available: Attribute statement (use after solve)

This model attribute returns the elapsed time taken by the solver only. This does not include the GAMS model generation time and the time taken to report and load the solution back into the GAMS database. The time is expressed in seconds of wall-clock time.

execMode (integer): Limits on external programs that are allowed to be executed

Available: Command line

A higher value denotes a more restrictive alternative. If the restriction level n is chosen, then the restriction levels less than n will also be active. For example, if restriction level 3 is chosen, then restrictions 2 and 1 will apply too.

Default: 0

Value	Meaning
0	Everything allowed
1	Interactive shells in $call and execute commands are prohibited
2	Embedded Code and all $call and execute commands are prohibited
3	$echo or put commands can only write to directories in or below the working or scratchdir
4	$echo and put commands are not allowed

expand (string): Expanded (include) input file name

Synonym: EF

Available: Command line

This option generates a file that contains information about all the input files processed during a particular compilation. By default, the names of the input files are composed by completing the name with the current directory.

Consider the following exmaple:

$call rm expfile.txt
$onecho > file1.inc
a = a*2; display a;
$include file2.inc
$offecho
$onecho > file2.inc
a = a+1; display a;
$include file3.inc
$offecho
$onecho > file3.inc
a = a**2; display a ;
$offecho
parameter a / 1 /;
$include file3.inc
$include file2.inc
$include file1.inc

If the model is run with the command line parameter ef=expfile.txt, a file called expfile.txt will be generated. This file will contain the following lines:

     1 INPUT       0     0        0        1       29  C:\GAMS\Examples\expand.gms
     2 CALL        0     1        1        1        1  rm expfile.txt
     3 INCLUDE     1     1       14       14       15  C:\GAMS\Examples\file3.inc
     4 INCLUDE     1     1       15       16       19  C:\GAMS\Examples\file2.inc
     5 INCLUDE     2     4        2       18       19  C:\GAMS\Examples\file3.inc
     6 INCLUDE     1     1       16       20       25  C:\GAMS\Examples\file1.inc
     7 INCLUDE     2     6        2       22       25  C:\GAMS\Examples\file2.inc
     8 INCLUDE     3     7        2       24       25  C:\GAMS\Examples\file3.inc
     9 EXIT        0     1       20       29       29  C:\GAMS\Examples\expand.gms

Note that the first row always refers to the parent file, in this case the file expand.gms. The first column gives the sequence number of the input files that were encountered. The second column refers to the type of file that is referenced. The following file types are possible:

0    INPUT
1    EXIT
2    INCLUDE
3    BATINCLUDE
4    LIBINCLUDE
5    SYSINCLUDE
6    CALL
7    CALL.ASYNC
7    CALLTOOL
8    GDXIN
9    GDXOUT
10    IF EXIST
11    IF DEXIST
12    FUNCLIBIN
13    TERMINATE
14    STOP

Observe that $call is also listed. The third column describes the depth for nested include files. The fourth column provides the sequence number of the parent file for the file being referenced. The fifth column gives the local line number in the parent file where the dollar control option $include appeared. The sixth column gives the global (expanded) line number which contained $include. The seventh column provides the total number of lines in the file after it is processed. The last column provides the name of the file.

Note that the listing in the expand file is similar to the include file summary in the listing file of the model. And like the include file summary, this file will not be written, if $offInclude is set in the model.

fdDelta (real): Step size for finite differences

Available: Command line, Option statement, Attribute statement (use before solve)

This option allows users to control the step size while the numerical Hessian and numerical derivatives are computed in the context of the function suffixes .hessn and .gradn. For functions with one argument, GAMS evaluates the function at f(x-d) and f(x+d) for the numerical gradient. If function values are used for the numerical Hessian, GAMS will evaluate at f(x-2d), f(x) and f(x+2d). For functions with multiple arguments, the same calculations are performed for the components of the input argument vector.

Default: 1.0E-05

fdOpt (integer): Options for finite differences

Available: Command line, Option statement, Attribute statement (use before solve)

This option allows users to control how numerical derivatives are computed. The values provide choice regarding the scaling of steps, Hessian calculation method and the use of numerical first derivatives.

Default: 0

Value	Meaning
0	All derivatives analytically, for numerical Hessian use gradient values, scale delta
1	All derivatives analytically, for numerical Hessian use function values, scale delta
2	Gradient analytically, force Hessian numerically using gradient values, scale delta
3	Gradient analytically, force Hessian numerically using function values, scale delta
4	Force gradient and Hessian numerically, scale delta
10	Same as 0, but no scale of delta
11	Same as 1, but no scale of delta
12	Same as 2, but no scale of delta
13	Same as 3, but no scale of delta
14	Same as 4, but no scale of delta

fErr (string): Alternative error message file

Available: Command line

This option redirects the compilation error messages to a file and names the file. By default, the file name is composed by completing the name with the scratch directory and the scratch extension. Note that under default settings such a file with compilation error messages is not generated. This option can be used when GAMS is being integrated into other environments like Visual Basic. The error messages that are reported in the listing file may be extracted with this option and their display may be controlled from the environment that is calling GAMS.

To illustrate, consider the slice of GAMS code that we used to explain the option errMsg. If we call this code with the command line parameter ferr=myfile.err, a file called myfile.err will be created in the scratch directory. This file will contain the following lines:

    0     0      0      0 D:\GAMS\NEW.LST
    1     1    170     31 D:\GAMS\NEW.GMS
    2     2    120     14 D:\GAMS\NEW.GMS

Note that the first column refers to the global row number of the error in the listing file. The second column refers to the row number of the error in the individual file where the problem occured. This will be different from the first column only if the error occured in an include file. In this case, the second column will contain the line number in the include file where the error occurred, while the first number will contain the global line number (as reported in the listing file) where the error occured. The number in the third column refers to the error number of the compilation error. The fourth number refers to the column number of the error in the source file. The last column contains the individual file in which the error occurred.

fileCase (integer): Casing of file names and paths (put, gdx, ref, $include, etc.)

Available: Command line

This option facilitates modifying the case of file names and paths. It applies to files created by a GAMS Job such as for example put files, GDX files and reference files. Under Windows, the casing of a created file will only be affected if the file does not yet exist, i.e. fileCase=2 won't create trnsport.ref if there is already a file TRNSPORT.ref. It should be noted that fileCase also applies to existing files that are used but not created by a GAMS job such as for example $include files or $batInclude files.

Note that many other file names and paths are affected by this option (e.g. the scratch directory (scrDir) or the GAMS system directory (sysDir)) and that it is recommended to use this option with caution.

Default: 0

Value	Meaning
0	Causes GAMS to use default casing
1	Causes GAMS to upper case file names including path of the file
2	Causes GAMS to lower case file names including path of the file
3	Causes GAMS to upper case file names only (leave the path alone)
4	Causes GAMS to lower case file names only (leave the path alone)

fileStem (string): Sets the file stem for output files which use the input file name as stem by default

Available: Command line

By default, some output files use the input file name as base. If the names of these output files were not set explicitly, then this option may be used to set another name than the input file name as base for these output files. In particular, the names for the following files may be set with fileStem: dump files (see option dumpOpt), GDX files (if the option GDX was set to default), log files (see option logFile), lst files (see option output), reference files (if the option reference was set to default) and trace summary files (see also option trace).

fileStemApFromEnv (string): Append a string read from an environment variable to the "FileStem"

Available: Command line

This option for users that submit GAMS job via mpirun/mpiexec. Such commands will spawn multiple instances of GAMS (the precise number is an argument to mpirun/mpiexec). Each invokation of GAMS will run the identical job and only the contents of an environment variable (PMI_RANK) will differentiate the run. Since GAMS will normally write to modelname.log/lst if we run the GAMS file modelname.gms we will have many jobs writing to the same file. Therefore we use this option to append the content of a particular environment variable (name given by this option) to the default file names (see fileStem). Hence GAMS will create modelname0.log/lst, modelname1.log/lst, and so forth when started with mpirun/mpiexec and fileStemApFromEnv is set to the environment variable that provides the MPI rank of the invokation. We allow to specify the name of the environment variable because different MPI implementations use different variable names (e.g. PMI_RANK or OMPI_COMM_WORLD_RANK).

filtered (string): Switch between filtered and domain-checked read from GDX

Available: Command line, Option statement

The command line parameter Filtered initializes both, the option Filtered to control the behavior of gdxLoad and the dollar control option $on/offFiltered for the compile-time equivalent behavior.

Default: on

Value	Meaning
off	Load domain checked
on	Load filtered

forceOptFile (integer): Overwrites other option file section mechanism

Available: Command line

Default: 0

forceWork (boolean): Force GAMS to process a save file created with a newer GAMS version or with execution errors

Synonym: FW

Available: Command line

Work files generated by GAMS using the command line parameter save are saved in binary format. The information inside these files will change from one GAMS version to another GAMS version. GAMS makes every attempt to be backward compatible and ensure that all new GAMS systems are able to read save files generated by older GAMS systems. However, this cannot be guaranteed the other way around. Thus, GAMS does not allow to process a save file, that was generated by a newer version of GAMS in general. This can be changed by setting forceWork to 1. Also, GAMS does not continue after processing a save while with an execution error by default. This behavior can be changed as well by setting forceWork=1.

Attention

Forcing GAMS to continue after reading a save file from a newer GAMS version or a save file with execution errors may lead to unexpected behavior. If it is about the GAMS version and you can recreate the save file you may write it using GAMS command line parameter previousWork=1.

Default: 0

Value	Meaning
0	No translation
1	Try translation

forLim (integer): GAMS looping limit

Available: Command line, Option statement

This option specifies the maximum number of permitted executions of control structures with a for statement, a while statement or a repeat statement before GAMS signals an execution error and terminates the control structure.

Default: ∞

fSave (boolean): Creates a forced work file, i.e., the file is saved even if execution errors or other errors occured

Available: Command line

This option allows to save a file even in the face of execution or other errors. How it works depends on the command line parameter save.

Note that the option value of 1 is mainly used by solvers that can be interrupted from the terminal.

Default: 0

Value	Meaning
0	Workfile only written to file specified by SAVE if no errors occur
1	Workfile always written to file specified by SAVE or if SAVE is not present to a name made up by GAMS

G205 (integer): Use GAMS version 2.05 syntax

Available: Command line

This option sets the level of the GAMS syntax and is mainly used to ensure backward compatibility. New keywords have been introduced in the GAMS language since Release 2.05. Models developed earlier that use identifiers that have since become keywords will cause errors when they are run with the latest version of GAMS. This option enables users to run such old models.

For example, the word "if" is a keyword in GAMS that was introduced with the first version of Release 2.25. Setting the option g205=1 allows the word "if" to be used as an identifier since it was not a keyword in Release 2.05. As another example, the word "for" is a keyword in GAMS that was introduced with the later versions of Release 2.25. Setting the option g205=2 allows "for" to be used as an identifier since it was not a keyword in the first version of Release 2.25.

Note

If the values 1 or 2 are specified for option g205, then it will not be permitted to use enhancements of the GAMS language that were introduced in later versions.

Default: 0

Value	Meaning
0	Use only latest syntax
1	Allow version 2.05 syntax only
2	Allow version 2.25 syntax only

GDX (string): GAMS data exchange file name

Available: Command line

This option specifies the name of the GAMS data exchange file and causes a GDX file to be written hat contains all data in the model at the end of the job. Setting gdx to the string 'default' causes GAMS to create a GDX file with the gms file root name and a gdx extension. Thus gams the call

   > gams trnsport gdx=default

will cause GAMS to write the GDX file trnsport.gdx.

gdxCompress (boolean): Compression of generated GDX file

Available: Command line

This option specifies whether the GDX files are compressed or not.

Default: 0

Value	Meaning
0	Do not compress GDX files
1	Compress GDX files

gdxConvert (string): Version of GDX files generated (for backward compatibility)

Available: Command line

This option specifies in which format the GDX files will be written.

Default: v7

Value	Meaning
v5	Version 5 GDX file, does not support compression
v6	Version 6 GDX file
v7	Version 7 GDX file

gdxSymbols (string): Select symbols that get exported when command line parameter GDX is set

Available: Command line

This option specifies which symbols get exported when command line parameter GDX is set. By default, all symbols get written to the specified GDX file, but it can be limited to only the ones that were created or updated during the model run, or even to just the ones changed during execution time.

Default: all

Value	Meaning
all	Write all symbols
newOrChanged	Write only symbols that are new or got modified during compile or execution time
assigned	Write only symbols that got modified during execution time

gdxUels (string): Unload labels or UELs to GDX either squeezed or full

Available: Command line, Option statement

This option specifies the UEL export mode. Note that gdxUels only works for execute_unload* statements during execution time and not for the command line parameter GDX or dollar control options $gdxOut/$unload/$gdxUnload.
The UEL table may be written to a GDX file in two different modes. In squeezed mode, only the UELs that are required by the exported symbols are exported. In full mode, all UELs are exported. The following code snippet illustrates the difference:

Set       i    / i1*i5 /;
Parameter p(i) / i3 3 /;

option gdxuels = squeezed;
execute_unload 'squeezed' p;
execute 'gdxdump squeezed UelTable=i';

option gdxuels = full;
execute_unload 'full' p;
execute 'gdxdump full UelTable=i';

The file squeezed.gdx will contain the following lines:

Set i /
  'i3' /;

Parameter p(*) /
'i3' 3 /;

The file full.gdx on the other hand, will contain the following lines:

Set i /
  'i1' ,
  'i2' ,
  'i3' ,
  'i4' ,
  'i5' /;

Parameter p(*) /
'i3' 3 /;

Default: squeezed

Value	Meaning
Squeezed	Write only the UELs to Universe, that are used by the exported symbols
Full	Write all UELs to Universe

gridDir (string): Grid file directory

Synonym: GDir

Available: Command line

This option sets the grid file directory. Note that each GAMS job has only one grid file directory.

gridScript (string): Grid submission script

Synonym: GScript

Available: Command line

This option provides the name of a script file that is used to submit grid computing jobs. If only the file name is given the file is assumed to be located in the system directory. A fully qualified name can be given as well. The script needs to be similar to the file gmsgrid.cmd on Windows machines with arguments that give name and location of the solver executable, the solver control file name and the name of the scratch directory. For an example of such a script, see section The Grid Facility: Architecture and Customization. However, note that advanced knowledge of how GAMS sets up and calls solvers is needed for successful use.

Default: gmsgrid

handle (real): Unique handle number of SOLVE statement

Available: Attribute statement (use after solve)

The model attribute handle contains a unique identification of each submitted solution request and is typically stored in a parameter defined over a set that covers all model instances. The handle number may be used by the functions handleCollect, handleStatus, handleDelete, handleSubmit and readyCollect. For details see chapter The Grid and Multi-Threading Solve Facility.

heapLimit (real): Maximum Heap size allowed in MB

Synonym: HL

Available: Command line

This option allows to limit the amount of memory a GAMS job may use during compilation and execution. If the needed data storage exceeds this limit, the job will be terminated.

Default: ∞

holdFixed (boolean): Treat fixed variables as constants

Available: Command line, Attribute statement (use before solve)

This option facilitates treating fixed variables as constants. Thus the problems size may be reduced.

Default: 0

Value	Meaning
0	Fixed variables are not treated as constants
1	Fixed variables are treated as constants

holdFixedAsync (boolean): Allow HoldFixed for models solved asynchronously as well

Available: Command line, Option statement

By default, holdFixed is automatically deactivated if a model is solved asynchronously, since this could lead to inconsistent solutions otherwise. To allow this anyway, this parameter can be set to 1.

Default: 0

Value	Meaning
0	Ignore HoldFixed setting for async solves
1	Allow HoldFixed for async solves

IDCGDXInput (string): GDX file name with data for implicit input

Available: Command line

Specify the name of a GDX file that is used for implicit loading of input data. Details about this are described with $onExternalInput.

IDCGDXOutput (string): GDX file name for data for implicit output

Available: Command line

Specify the name of a GDX file that is used for implicit writing of output data. Details about this are described with $onExternalOutput.

IDCGenerateGDX (string): Specify GDX file name of input and output side of data contract

Available: Command line

Specify the name of a GDX file that is used to store all symbols that are declared as external input or external output at the end of a GAMS run.

IDCGenerateGDXInput (string): Specify GDX file name of input side of data contract

Available: Command line

Specify the name of a GDX file that is used to store all symbols that are declared as external input at the end of a GAMS run.

IDCGenerateGDXOutput (string): Specify GDX file name of output side of data contract

Available: Command line

Specify the name of a GDX file that is used to store all symbols that are declared as external output at the end of a GAMS run.

IDCGenerateJSON (string): Specify JSON file name of data contract

Available: Command line

Specify the name of a JSON file that is used to store the information (but not the data) about all symbols that are declared as external input or external output at the end of a GAMS run.

IDCJSON (string): Specify JSON file name to verify data contract

Available: Command line

Specify the name of a JSON file that is read and used to verify that the implicit data contract given by the GAMS model by declaring symbols as external input or external output matches the expected symbol information given by this specified file. This is the expected schema of that file:

{

"$schema":"http://json-schema.org/draft-07/schema#",

"title":"Input/Output configuration file schema",

"description":"Configuration file is automatically generated by GAMS and describes the data contract.",

"type":"object",

"definitions": {

"symbolHeader":{

"description":"Symbol header",

"type":"object",

"properties":{

"alias":{

"description":"Explanatory text of the header",

"type":"string",

"minLength":1

},

"type":{

"description":"GAMS input type",

"type":"string",

"enum":[

"string",

"numeric"

]

}

},

"required": ["alias", "type"]

},

"symbol":{

"description": "Symbol definition",

"type": "object",

"properties": {

"alias":{

"description": "Explanatory text of the symbol",

"type":"string",

"minLength":1

},

"symtype":{

"description": "Symbol type",

"type":"string",

"default":"en",

"enum":[

"set",

"parameter",

"variable",

"equation"

]

},

"headers":{

"description":"Symbol headers",

"type":"object",

"minProperties":1,

"additionalProperties":{

"$ref": "#/definitions/symbolHeader"

}

}

},

"required": ["alias", "symtype", "headers"]

},

"scalarSymbol": {

"description": "Scalar symbols that are grouped together in one table",

"type": "object",

"properties": {

"alias":{

"description": "Explanatory text of the symbol",

"type":"string",

"minLength":1

},

"symnames":{

"description": "Symbol names in scalar tables",

"type":"array",

"minItems":1,

"uniqueItems":true,

"items":{

"type":"string",

"minLength":1

}

},

"symtypes":{

"description": "Symbol types in scalar tables",

"type":"array",

"minItems":1,

"items":{

"type":"string",

"enum":[

"set",

"parameter",

"variable",

"equation"

],

"minLength":1

}

},

"symtext":{

"description": "Symbol aliases (exp. text) in scalar tables",

"type":"array",

"minItems":1,

"items":{

"type":"string",

"minLength":1

}

},

"headers":{

"description":"Symbol headers",

"type":"object",

"minProperties":1,

"additionalProperties":{

"$ref": "#/definitions/symbolHeader"

}

}

},

"required": ["alias", "symnames", "symtypes", "symtext", "headers"]

}

},

"additionalProperties":false,

"properties":{

"modelTitle":{

"description":"Title of the model",

"type":"string",

"default":"Unnamed model"

},

"inputSymbols":{

"description":"Name of the symbols to receive data from MIRO. Identifiers are case insensitive (will always be lower case).",

"type":"object",

"additionalProperties":{

"oneOf": [

{ "$ref": "#/definitions/scalarSymbol" },

{ "$ref": "#/definitions/symbol"}

]

}

},

"outputSymbols":{

"description":"Name of the symbols to export to MIRO once computation has finished. Identifiers are case insensitive (will always be lower case).",

"type":"object",

"additionalProperties":{

"oneOf": [

{ "$ref": "#/definitions/scalarSymbol" },

{ "$ref": "#/definitions/symbol"}

]

}

}

},

"required":["modelTitle", "inputSymbols", "outputSymbols"]

}

IDCProtect (boolean): Flag to control assignment protection of external input symbols

Available: Command line, Option statement

By default, it is not allowed to change symbols which are declared as external input at execution time. This parameter allows to ignore this restriction. It sets the initial state for the dollar control options $on/offIDCProtect.

Default: 1

Value	Meaning
0	Allow to change external input symbols at execution time
1	Protect external input symbols from being changed at execution time

IDE (boolean): Integrated Development Environment flag

Available: Command line

This option instructs GAMS to write special instructions to the log file that are in turn read by an IDE.

Default: 0

Value	Meaning
0	Unknown environment
1	Runs under GAMS IDE

implicitAssign (string): Switch default for "$on/offImplicitAssign"

Available: Command line

For more info see $on/offImplicitAssign.

Default: off

Value	Meaning
off	Activate $offImplicitAssign
on	Activate $onImplicitAssign

inlineCom (string): Switch default for "$on/offInline" and "$inlineCom"

Available: Command line

If this is set to on on or off it sets the state of $on/offInline. Other strings (a pair with not more than two characters each) will set $inlineCom.

Default: off

Value	Meaning
off	Activate $offInline
on	Activate $onInline using default inline comment characters
other	Activate $onInline setting specific inline comment characters

input (string): Input file

Synonym: I

Available: Command line

Completing the input file name with the current directory composes the final name. If such a file does not exist and the extension was not specified, the standard input extension will be attached and a second attempt will be made to open an input file.

inputDir, inputDir1..40 (string): Input file directories (searched at compile time)

Synonym: IDIR

Available: Command line

In general, GAMS searches for input and include files in the current working directory only. This option allows the user to specify additional directories for GAMS to search for include and batinclude files as well as GDX file via $gdxIn. A maximum of 40 separate directories may be included. The directories are separated by Operating System specific symbols. For example, on Windows the separator is a semicolon (;) character and under Unix it is the colon (:) character. Note that libinclude and sysinclude files are handled differently. Their paths are specified with the command line parameters libIncDir and sysIncDir respectively.

Consider the following illustration:

   > gams myfile idir \mydir;\mydir2

Note that the search order for the file myfile.gms and all included files on Windows will be as follows: (1) the current directory, (2) the directories specified by inputdir in their respective order (here the directories: \mydir and \mydir2). Under Unix, the corresponding GAMS call will be:

   > gams myfile idir \mydir:\mydir2

Note that the information in the option inputDir may be also transferred to GAMS by entering the individual directories separately. A maximum of 40 directories may be passed on in this manner. The number appended to InputDir is important since the earlier InputDir directories will be searched first.

The example above may alternatively be formulated in the following way:

   > gams myfile idir1 mydir1 idir2 mydir2

Note that in this case the search order will be as follows:

1. current directory
2. mydir1
3. mydir2

Observe that we could modify the command in the following way:

   > gams myfile idir3 \mydir1 idir2 \mydir2

Note that in this case the search order will be as follows:

1. current directory
2. mydir2
3. mydir3

Thus it is not the order in which the directories are specified that matters, but the number of the option inputDir that they have been assigned to.

integer1..5 (integer): Integer communication cell N

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies an integer communication cell that may contain any integer number.

interactiveSolver (boolean): Allow solver to interact via command line input

Available: Command line

Default: 0

Value	Meaning
0	Interaction with solvelink 0 is not supported
1	Interaction with solvelink 0 is supported

intVarUp (integer): Set mode for default upper bounds on integer variables

Available: Command line, Option statement

Default: 0

Value	Meaning
0	Set default upper bound for integer variables to +INF
1	Pass a value of 100 instead of +INF to the solver as upper bound for integer variables
2	Same as 0 but writes a message to the log if the level of an integer variable is greater than 100
3	Same as 2 but issues an execution error if the level of an integer variable is greater than 100

iterLim (integer): Iteration limit of solver

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies the maximum number of permitted solver iterations, before the solver terminates the run. If this limit is reached, the solver will terminate and will return solver status 2 ITERATION INTERRUPT. Note that the definition of what constitutes an interation depends on the solver. For LP solvers, iterlim often refers to the number of simplex iterations (i.e., pivots). For MIP solvers, iterlim often refers to the cumulative number of simplex iterations over all solves of LP relaxations. Observe that iterlim does not apply to all iterations. For example, it might not apply to barrier iterations and major iterations in nonlinear solvers. For these iterations solver-specific options need to be set. Moreover, some solver links might reinterpret the value of this option. For example, if left at default, the solver link might use the default iteration limit of the solver.

Default: 2147483647

iterUsd (integer): Number of iterations used

Available: Attribute statement (use after solve)

This model attribute returns the number of iterations used after a solve.

jobTrace (string): Job trace string to be written to the trace file at the end of a GAMS job

Synonym: JT

Available: Command line

This option specifies a string that is written to the trace file at the end of a GAMS job.

keep (boolean): Controls keeping or deletion of process directory and scratch files

Available: Command line

This option controls whether to keep the process directory. In the process directory the temporary/scratch files are located, unless the options scrDir or procDir were used.

Default: 0

Value	Meaning
0	Delete process directory
1	Keep process directory

libIncDir (string): LibInclude directory

Synonym: LDIR

Available: Command line

This option specifies the name of the directory to be used by GAMS for $libInclude files that do not have a full path specification. An absolute or relative path may be specified. If the option libIncDir is not set, it will be set to the subdirectory inclib in the GAMS standard locations. A relative path is relative to the GAMS system directory.

Note that if the option libIncDir parameter is set, the default library include directories will only be searched, if the libInclude file cannot be found in the specified folder.

Attention

Only one directory may be set with the option libIncDir. Thus the string specified will be treated as one directory. If additional directories are added, errors will be reported.

Consider the following example:

   > gams myfile libIncDir mydir

Note that GAMS will search for any referenced libInclude file in the directory <GAMS System Directory>/mydir first.

license (string): Use alternative license file

Available: Command line

This option specifies the name the file that contains the GAMS license. It may be used to point to an explicit license file rather letting GAMS search for the default gamslice.txt in various locations including the GAMS system directory. The locations ("Data directories") can be printed by running gamsinst -listdirs, see installation notes for details. The license option should only be used by advanced users attempting to override internal license information.

limCol (integer): Maximum number of columns listed in one variable block

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the number of columns that are listed for each variable in the column listing in the listing file. Note that the value of zero will suppress the column listing.

Default: 3

limRow (integer): Maximum number of rows listed in one equation block

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the number of rows that are listed for each equation in the equation listing in the listing file. Note that the value of zero will suppress the equation listing.

Default: 3

line (integer): Line number of last solve of the corresponding model

Available: Attribute statement (use after solve)

This model attribute returns the line number of the last solve of the respective model.

linkUsed (integer): Integer number that indicates the value of SolveLink used for the last solve

Available: Attribute statement (use after solve)

This model attribute returns an integer number that indicates the value of the option solveLink that was used for the last solve.

listing (string): Switch default for "$on/offListing"

Available: Command line

For more info see $on/offListing.

Default: on

Value	Meaning
off	Activate $offListing
on	Activate $onListing

logFile (string): Log file name

Synonym: LF

Available: Command line

This option is used in conjunction with the option logOption or short LO. If lo is set to 2 or 4, this option will specify the name of the log file name. The name provided by the option is completed using the current directory. If no logfile is given, but the value of lo is 2 or 4, then the file name will be the input file name with the extension .log.

Consider the following GAMS call:

   > gams trnsport lo=2 lf=myfile.log

Note that the resulting log file will redirected to the file myfile.log. It will contain the following lines:

--- Starting compilation
--- trnsport.gms(75) 3 Mb
--- Starting execution: elapsed 0:00:00.017
--- trnsport.gms(44) 4 Mb
--- Generating LP model transport
--- trnsport.gms(63) 4 Mb
---   6 rows  7 columns  19 non-zeroes
--- Executing CPLEX: elapsed 0:00:00.072

IBM ILOG CPLEX   24.8.2 r59988 Released Jan  3, 2017 DEG x86 64bit/Mac OS X
Cplex 12.7.0.0

Reading data...
Starting Cplex...
Space for names approximately 0.00 Mb
Use option 'names no' to turn use of names off
Tried aggregator 1 time.
LP Presolve eliminated 1 rows and 1 columns.
Reduced LP has 5 rows, 6 columns, and 12 nonzeros.
Presolve time = 0.01 sec. (0.00 ticks)

Iteration      Dual Objective            In Variable           Out Variable
     1              73.125000    x(Seattle.New-York) demand(New-York) slack
     2             119.025000     x(Seattle.Chicago)  demand(Chicago) slack
     3             153.675000    x(San-Diego.Topeka)   demand(Topeka) slack
     4             153.675000  x(San-Diego.New-York)  supply(Seattle) slack
LP status(1): optimal
Cplex Time: 0.03sec (det. 0.01 ticks)

Optimal solution found.
Objective :         153.675000

--- Restarting execution
--- trnsport.gms(63) 2 Mb
--- Reading solution for model transport
--- trnsport.gms(72) 3 Mb
instructions that will go to the log file
more instructions that will go to the log file
*** Status: Normal completion
--- Job trnsport.gms Stop 02/09/17 14:39:20 elapsed 0:00:00.280

logLine (integer): Amount of line tracing to the log file

Synonym: LL

Available: Command line

This option may be used to limit the number of line tracing sent out to the log file during the compilation phase of a GAMS run. Note that setting this option to zero will cause the line tracing to be suppressed for all phases of the GAMS processing.

The log file that results from running the model [TRNSPORT] with the option ll=0 is shown below.

--- Starting compilation
--- Starting execution: elapsed 0:00:00.018
--- Generating LP model transport
---   6 rows  7 columns  19 non-zeroes
--- Executing CPLEX: elapsed 0:00:00.060

IBM ILOG CPLEX   24.8.2 r59988 Released Jan  3, 2017 DEG x86 64bit/Mac OS X
Cplex 12.7.0.0

Reading data...
Starting Cplex...
Space for names approximately 0.00 Mb
Use option 'names no' to turn use of names off
Tried aggregator 1 time.
LP Presolve eliminated 1 rows and 1 columns.
Reduced LP has 5 rows, 6 columns, and 12 nonzeros.
Presolve time = 0.01 sec. (0.00 ticks)

Iteration      Dual Objective            In Variable           Out Variable
     1              73.125000    x(Seattle.New-York) demand(New-York) slack
     2             119.025000     x(Seattle.Chicago)  demand(Chicago) slack
     3             153.675000    x(San-Diego.Topeka)   demand(Topeka) slack
     4             153.675000  x(San-Diego.New-York)  supply(Seattle) slack
LP status(1): optimal
Cplex Time: 0.03sec (det. 0.01 ticks)

Optimal solution found.
Objective :         153.675000

--- Restarting execution
--- Reading solution for model transport
instructions that will go to the log file
more instructions that will go to the log file
*** Status: Normal completion
--- Job trnsport.gms Stop 02/09/17 15:43:43 elapsed 0:00:00.275

If we compare this output to the output shown in the example of option logFile, we will observe that the line numbers are missing from this log file.

Default: 2

Value	Meaning
0	No line tracing
1	Minimum line tracing
2	Automatic and visually pleasing

logOption (integer): Log option

Synonym: LO

Available: Command line

This option controls the location of the output log of a GAMS run. By default, GAMS directs the log of the run to the standard output. If logOption is set to 2, the log will be redirected to a file. Note that if no file name is provided for the log through the option logFile, the file name will be the input file name with the extension .log. Observe that the settings zero and 2 may be used to permit jobs to run in the background.

To illustrate, consider the following call:

   > gams trnsport lo=2

Note that the resulting log file, trnsport.log, will be identical to the file myfile.log that is shown as part of the description of the option logFile.

Default: 3

Value	Meaning
0	No log output
2	Log output to logfile
3	Log output to standard output
4	Log output to logfile and standard output

LP (string): Linear Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Linear Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

lstTitleLeftAligned (boolean): Write title of LST file all left aligned

Available: Command line

Default: 1

Value	Meaning
0	Split LST title into left and right aligned part
1	Write LST title completely left aligned

marginals (integer): Indicator for marginals present

Available: Attribute statement (use after solve)

maxExecError (integer): Execution time error limit

Synonym: ExecErr

Available: Command line

This option puts an upper limit on the number of errors that may be found during execution or preprocessing associated with a solve statement. If more than maxExecError errors have been found GAMS will abort when hitting the next solve statement. If maxExecError is greater than the number of pending execution errors, the solve will be skipped, but the execution continues afterwards. This value can be overwritten with the function maxExecError.

Default: 0

Value	Meaning
0	No errors allowed limit
n	Max number allowed

maxGenericFiles (integer): Maximum number of generic file names tried at execution time file creation

Available: Command line, Option statement

In case of a failed writing of put files and GDX files via execute_unload (e.g. because the given path is invalid or the file is open by another program), GAMS tries to write to a generic file name instead. The number of file names tried can be specified with this option. To avoid this completely and throw an error right away, if the given name is invalid, set this to 0.

Default: 20

maxInfes (real): Maximum of infeasibilities

Available: Attribute statement (use after solve)

This model attribute returns the maximum number of infeasibilities after a solve.

maxProcDir (integer): Maximum number of 225* process directories

Available: Command line

This option controls the maximum number of work file directories that may be generated by GAMS. By default they are called 225a, 225b, ..., 225aa, 225ab ... Note that the label 225 may be changed with the option procDir.

Default: 700

MCP (string): Mixed Complementarity Problems - default solver

Available: Command line, Option statement

The default solver for models of the type Mixed Complementarity Problems is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

MCPRHoldFx (boolean): Print list of rows that are perpendicular to variables removed due to the holdfixed setting

Available: Command line, Option statement, Attribute statement (use before solve)

If option holdfixed is true, fixed columns in row.column matches are removed from MCP models but the matching rows remain. These rows are ignored by the solver. This option causes a list of such rows to be included in the listing file prior to the solve summary.

Default: 0

meanInfes (real): Mean of infeasibilities

Available: Attribute statement (use after solve)

This model attribute returns the mean of the infeasibilities after a solve.

measure (no value): Output of time and memory use since the last measure statement or the program beginning

Available: Option statement

This option has the effect that three measurements will be displayed: the memory and time usage since the last option statement measure and the total time used. See also the related option profile.

memoryStat (no value): Show memory statistics in the LST file

Available: Option statement

This option has the effect that memory statistics will be shown in the listing file.

MIIMode (string): Model Instance Mode

Available: Command line

This parameter is used in conjunction with the GAMS Model Instance Inspector (MII). The MII needs to have access to the scratch directory and requires a dictionary for the model instance to analyze. So, this parameter forces other parameters to be set:

• Keep is forced to 1.
• DictFile is forced to 1.
• SolveLink is forced to 2 with MIIMode=singleMI and to 4 with MIIMode=multiMI.

Default: off

Value	Meaning
off	Default behavior
singleMI	Setup to inspect a single model instance
multiMI	Setup to inspect multiple model instances from one model

MINLP (string): Mixed-Integer Non-Linear Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Mixed Integer Nonlinear Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

MIP (string): Mixed-Integer Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Mixed Integer Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

MIQCP (string): Mixed Integer Quadratically Constrained Programs - default solver

Available: Command line, Option statement

The default solver for models of the type Mixed Integer Quadratically Constrained Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

modelStat (integer): Integer number that indicates the model status

Available: Attribute statement (use after solve)

This model attribute returns the model status after a solve. Observe that there are compile-time constants that are related to modelStat. Note that additional information to the values given in the table below is provided in section Model Status.

Value	Meaning
1	Optimal
2	Locally Optimal
3	Unbounded
4	Infeasible
5	Locally Infeasible
6	Intermediate Infeasible
7	Feasible Solution
8	Integer Solution
9	Intermediate Non-Integer
10	Integer Infeasible
11	Licensing Problem
12	Error Unknown
13	Error No Solution
14	No Solution Returned
15	Solved Unique
16	Solved
17	Solved Singular
18	Unbounded - No Solution
19	Infeasible - No Solution

MPEC (string): Mathematical Programs with Equilibrium Constraints - default solver

Available: Command line, Option statement

The default solver for models of the type Mathematical Program with Equilibrium Constraints is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

multi (string): Switch default for "$on/offMulti[R]"

Available: Command line

If this is set to on on or off it sets the state of $on/offMulti. The value onR activates $onMultiR.

Default: off

Value	Meaning
off	Activate $offMulti
on	Activate $onMulti
onR	Activate $onMultiR

multiPass (boolean): Multipass facility

Synonym: MP

Available: Command line

This option may be used to instruct GAMS to use a quick syntax checking compilation facility which does not require all items to be declared. This alternative is useful when a large model is assembled from smaller pieces. It allows slices of GAMS code to be independently checked for syntax errors.

Consider the following example:

a(i) = b(i)*5 ;
b(i) = c(j) ;

By default, running a file containing just these two statements will generate the following listing file:

   1  a(i) = b(i)*5 ;
****  $140,120,140
   2  b(i) = c(j) ;
****         $140,120,149

120  Unknown identifier entered as set
140  Unknown symbol
149  Uncontrolled set entered as constant

**** 6 ERROR(S)   0 WARNING(S)

Note that both sets i and j have not been defined or initialized. In addition, the identifiers a, b and c have not been defined either. Further, an assignment cannot be made without the right-hand side of the assignment being known. However, in both assignments there is no data available for the right-hand side. If we run the same two lines with the option mp=1, we will get the following listing file:

   1  a(i) = b(i)*5 ;
   2  b(i) = c(j) ;
****            $149

149  Uncontrolled set entered as constant

**** 1 ERROR(S)   0 WARNING(S)

Observe that the statements have now been processed independently of their context. They are now checked only for consistency. GAMS now assumes that the sets i and j, as well as the identifiers a, b, and c have been defined and, if necessary, initialized elsewhere. The only error that is reported is the inconsistency of indices in the second statement.

Default: 0

Value	Meaning
0	Standard compilation
1	Check-out compilation
2	As 1, and skip $call and ignore missing file errors with $include and $gdxin as well as unknown dimension errors with empty data statements

NLP (string): Non-Linear Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Nonlinear Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

nodLim (integer): Node limit in branch and bound tree

Available: Command line, Attribute statement (use before solve)

This option specifies the maximum number of nodes that are to be processed in the branch and bound tree search for a MIP problem. Note that setting nodLim can stop solutions that are exhibiting "excessive" iterations: if the limit is reached the algorithm will terminate, without obtaining optimality. In this case the solver status will be 4 TERMINATED BY SOLVER. Observe that a value of zero is interpreted as 'not set'.

Default: 0

nodUsd (integer): Number of nodes used by the MIP solver

Available: Attribute statement (use after solve)

This model attribute returns the number of nodes used by the MIP solver after a solve.

noNewVarEqu (integer): Triggers a compilation error when new equations or variable symbols are introduced

Available: Command line

Default: 0

Value	Meaning
0	AllowNewVarEqu
1	DoNotAllowNewVarEqu

number (real): Model instance serial number

Available: Attribute statement (use after solve)

This model attribute returns the model instance serial number. Note that the first model solved is assigned number 1, the second number 2 etc. The user may also set a value n and the next model solved will be assigned the number n+1.

numDepnd (integer): Number of dependencies in a CNS model

Available: Attribute statement (use after solve)

This model attribute returns the number of dependencies identified in a CNS model after a solve.

numDVar (integer): Number of discrete variables

Available: Attribute statement (use after solve)

This model attribute returns the number of discrete variables after a solve.

numEqu (integer): Number of equations

Available: Attribute statement (use after solve)

This model attribute returns the number of equations after a solve.

numInfes (integer): Number of infeasibilities

Available: Attribute statement (use after solve)

This model attribute returns the number of infeasibilities after a solve.

numNLIns (integer): Number of nonlinear instructions

Available: Attribute statement (use after solve)

This model attribute returns the number of nonlinear instructions after a solve.

numNLNZ (integer): Number of nonlinear nonzeros

Available: Attribute statement (use after solve)

This model attribute returns the number of nonlinear nonzeros after a solve.

numNOpt (integer): Number of nonoptimalities

Available: Attribute statement (use after solve)

This model attribute returns the number of nonoptimalities after a solve.

numNZ (integer): Number of nonzero entries in the model coefficient matrix

Available: Attribute statement (use after solve)

This model attribute returns the number of nonzero entries in the model coefficient matrix after a solve.

numRedef (integer): Number of MCP redefinitions

Available: Attribute statement (use after solve)

This model attribute returns the number of MCP equation-type redefinitions after a solve.

numVar (integer): Number of variables

Available: Attribute statement (use after solve)

This model attribute returns the number of variables after a solve.

numVarProj (integer): Number of bound projections during model generation

Available: Attribute statement (use after solve)

This model attribute returns the number of bound projections during model generation.

objEst (real): Estimate of the best possible solution for a mixed-integer model

Available: Attribute statement (use after solve)

This model attribute returns the estimate of the best possible solution for a MIP or other models with discrete variables. The model attribute is mainly used after solve.

Some GAMS solvers implement algorithms (e.g. branch-and-bound) that generate a bound on the objective function value for the best possible solution. Users may access this bound by using the model attribute objEst. Note that this is mainly used for models with discrete variables (e.g. MIP and MINLP), but some global solvers implement spatial branch-and-bound algorithms that also provide such a bound for purely continuous problems. In case the solver does not set the attribute, its value is na.

objVal (real): Objective function value

Available: Attribute statement (use after solve)

This model attribute returns the objective function value after a solve.

on115 (boolean): Generate errors for unknown unique element in an equation

Available: Command line

This option generates errors for unknown unique elements in an equation.

Default: 0

Value	Meaning
0	No error messages
1	Issue error messages

optCA (real): Absolute Optimality criterion solver default

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies an absolute termination tolerance for a global solver. General problems are often extremely difficult to solve and proving that a solution that was found for a nonconvex problem is indeed the best possible solution can use enormous amounts of resources. The absolute gap is defined to be |PB-DB|. Here the primal bound PB is the objective function value of the best feasible solution found thus far and the dual bound DB is the current bound on the optimal value of the problem (i.e., lower bound in case of minimization and upper bound in case of maximization).

If the absolute gap is not greater than optCA, the solver will terminate and return solver status 1 NORMAL COMPLETION and model status 8 INTEGER SOLUTION (for a problem with discrete variables) or 2 LOCAL OPTIMAL or 7 FEASIBLE SOLUTION (for a problem without discrete variables). Note that this is a termination test only; setting this option should not change the global search.

Note

As this is an absolute criterion, setting the value to 100 means that the objective value will be within the 100 units of the true objective value.

Observe that a nonzero value for optCA will reduce solution time. However, it may cause the true integer optimum to be missed. This will be the case if at the time the solution algorithm stops, the value of the true integer optimum is within the tolerance specified by optCA of the best current solution. Therefore the reported solution could be the best, but it is guaranteed only to be within the tolerance of the true optimal solution.

Default: 0

optCR (real): Relative Optimality criterion solver default

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies a relative termination tolerance for a global solver. General problems are often extremely difficult to solve and proving that a solution that was found for a nonconvex problem is indeed the best possible solution can use enormous amounts of resources. The precise definition of optCR depends on the solver. GAMS and some solvers use the following formula to compute the optimality gap:

|PB-DB| / max(|PB|,|DB|)

Here the primal bound PB is the objective function value of the best feasible solution found thus far and the dual bound DB is the current bound on the optimal value of the problem (i.e., lower bound in case of minimization and upper bound in case of maximization). However, two other formulas are also widely used, namely

|PB-DB| / |PB|

and

|PB-DB| / |DB|

Different adjustments when the denominator approaches zero or bounds are of different signs will be applied. The solver will stop as soon as it has found a feasible solution proven to be within optCR of optimal, that is, the optimality gap falls below optCR.

Note

As optCR is specified in proportional terms relative to the objective value, a value of 0.1 means that the objective value will be within 10% of the true objective value.

Observe that the solver will stop after finding a solution proven to be optimal within the tolerance specified with optCR and thus the solution time may be reduced. However, setting this option may cause the true integer optimum to be missed. This will be the case if at the time the solution algorithm stops, the value of the true integer optimum is within the tolerance specified by optCR of the best current solution. Therefore the reported solution could be the best, but it is guaranteed only to be within the tolerance of the true optimal solution.

Default: 1.0E-04

optDir (string): Option file directory

Available: Command line

This option may be used to specify the name of the directory for solver option files. By default, the directory will be set to the current working directory.

optFile (integer): Default option file

Available: Command line, Attribute statement (use before solve)

This option instructs the solver to read an option file. The value of optFile determines which option file is used (see table below). Solver options allow users to manipulate the way solvers work. This may affect various solver functions including the choice of the branch and bound tree handling strategies. Please consult the solver manuals for options for each solver.

Note that this option is availabe as model attribute and command line parameter. Consider the following GAMS call:

   > gams myfile optfile=1

Observe that the value of 1 for optFile means that the option file with the name solverName.opt will be used. Here solverName is the name of the respective solver. For example, if the solver CONOPT is used, the name of the respective option file is conopt.opt.

Note

If optFile is set with the model attribute in the GAMS input file, the value of the model attribute will override any optFile specifications on the command line.

Different values for optFile allow access to different option files for the same solver. Note that the following rule is used: if we specify optfile = n, then solvername.opt will be used for n=1, otherwise solvername.opX, solvername.oXX or solvername.XXX will be used, where X's are the characters representing the value of n, for n > 1. Observe that no option file will be used if the value of optFile is zero.

Default: 0

Value	Meaning
0	No option file will be used
1	The option file solvername.opt will be used
2	The option file solvername.op2 will be used
3	The option file solvername.op3 will be used
15	The option file solvername.o15 will be used
222	The option file solvername.222 will be used
1234	The option file solvername.1234 will be used

output (string): Listing file name

Synonym: OO

Available: Command line

By default, the name of the output file (or listing file) is automatically created by combining the name of the input file with the current directory and applying the standard output file extension .lst. This option may be used to specify an alternative name for the output file. If the value is a file name without an absolute path, the current directory will compose the final name. If the absolute path is included in the file name, then the name is used as specified.

Consider the following examples:

gams trnsport
gams trnsport o=trnsportOut
gams trnsport o=c:\test\trnsport.out

Note that the first call will create an output file called trnsport.lst in the current directory. The second call will create a file called trnsportOut (without extension) in the current directory. The last call will create the file as listed. If the directory c:\test does not exist, GAMS will exit with a parameter error.

Creation of the output file can be suppressed by setting the command line parameter writeOutput to 0.

pageContr (integer): Output file page control option

Synonym: PC

Available: Command line

This option affects the page control in the listing file.

Default: 2

Value	Meaning
0	No page control, with padding
1	FORTRAN style line printer format
2	No page control, no padding
3	Formfeed character for new page

pageSize (integer): Output file page size (=0 no paging)

Synonym: PS

Available: Command line

This option specifies the number of lines that are used on a page for printing the listing file. The lower bound is zero, which is interpreted as +inf. That means that everything is printed to one page.

Default: 0

pageWidth (integer): Output file page width

Synonym: PW

Available: Command line

This option sets the print width on a page in the listing file with a possible range from 72 to 32767. If the value is outside the allowed range, the default value will be used.

Note that .pw is also a put file attribute. In the context of the put writing facility, it may be used to set the page width of a put file. See page width for further details.

Default: 32767

parmFile (string): Command Line Parameter include file

Synonym: PF

Available: Command line

This option specifies the name of a secondary customization parameter file to use. It is used to augment the command line adding more command line parameters from a file. It is read from the current directory unless a path is specified. For an example, see section Specifying Options Through a Secondary Parameter File.

pLicense (string): Privacy license file name

Available: Command line

This option gives the name of a privacy license file that contains file encryption codes. A full path should be used. For more information, see Encrypting Files.

prefixLoadPath (boolean): Prepend GAMS system directory to library load path

Available: Command line

The OS environment variable to locate shared libraries used to be prefixed with the GAMS system directory. The option controls if this done or not. For the Windows platform, setting this option has no impact.

Default: 0

Value	Meaning
0	Do not set GAMS system directory at beginning of library load path
1	Set GAMS system directory at beginning of library load path

previousWork (boolean): Indicator for writing workfile with previous workfile version

Available: Command line

When GAMS creates a workfile (e.g. using command line parameter restart) by default it uses the most recent version of the workfile format. GAMS is backward compatible with respect to workfile formats, i.e. newer GAMS versions can process workfiles generated by older GAMS version. As long as the workfile format has not changed older GAMS versions can even process workfiles generated by newer GAMS versions (using the forceWork=1 command line parameter). This particular command line parameter allows to create a workfile using the previous workfile format with the current GAMS version, so the previous GAMS version (and probably a few more versions back) will properly restart from this workfile even without issueing a warning.

This option is mostly used in combination with submissions to the NEOS server. Setting this option to 1 allows to submit NEOS jobs with a restart file even if the NEOS version is somewhat older than the local GAMS version.

Default: 0

Value	Meaning
0	Write workfile using the current version
1	Write workfile using the previous workfile version

priorOpt (real): Priority option for variable attribute .prior

Available: Attribute statement (use before solve)

Instructs the solver to use the priority branching information passed by GAMS through variable suffix values variable.prior. If and how priorities are used is solver-dependent.

Default: 0

procDir (string): Process Directory

Available: Command line

This option specifies the name of the process directory. If specified, the directory must already exist and it will not be deleted when GAMS cleans up. By default, the process directory name is chosen automatically from the list 225a, 225b, ..., 225aa, 225ab ..., by skipping over existing entries, and the directory will be deleted during cleanup if the option keep is not used. Very little is written to the process directory, but the scratch directory is used more, and the option scrDir takes its default from the process directory.

procDirPath (string): Directory to create process directory in

Available: Command line

This option specifies the directory where the process directory should be created. If specified, the directory must already exist. While the process directory does not get cleaned automatically if the option procDir is set, this is not the case if the option procDirPath is used instead. Thus it allows to conveniently change the location of the process directory without changing the GAMS cleanup behavior. Note that if the location of the process directory is changed, the location of the default scratch directory will be changed accordingly (see option scrDir).

procTreeMemMonitor (boolean): Monitor the memory used by the GAMS process tree

Available: Command line

Setting this option to 1 will cause GAMS to record the high-memory mark for the GAMS process tree (i.e. the gams or gams.exe process and all its children) and note this information in the log just prior to finishing. This is done via a separate thread that runs periodically (use option procTreeMemTicks to control how often) to construct the GAMS process tree and compute the memory usage for each process in it. There is some overhead with this so it is suggested to use this option only when needed and with a procTreeMemTicks value not smaller than the default.

In addition to the memory high-water marks (measured using both the size of the resident set and the virtual set used by each process in the tree) the report indicates the number of times this measurement was taken and any failures during this computation. For details on how to interpret the resident set and virtual set sizes, see showOSMemory.

Default: 0

Value	Meaning
0	Do not monitor memory usage for the GAMS process tree
1	Start a thread to monitor memory usage for the GAMS process tree

procTreeMemTicks (integer): Set wait interval between memory monitor checks: ticks = milliseconds

Available: Command line

Sets the wait interval in milliseconds between checks of the GAMS process tree memory usage: see procTreeMemMonitor for details.

Default: 2000

procUsed (integer): Integer number that indicates the used model type

Available: Attribute statement (use after solve)

Value	Meaning
1	LP
2	MIP
3	RMIP
4	NLP
5	MCP
6	MPEC
7	RMPEC
8	CNS
9	DNLP
10	RMINLP
11	MINLP
12	QCP
13	MIQCP
14	RMIQCP
15	EMP

profile (integer): Execution profiling

Available: Command line, Option statement

The execution profile of a GAMS run contains the individual and cumulative time required to execute the sections of the GAMS model, as well as information on memory use. The option profile controls whether an execution profile will be generated in the listing file. Observe that profile is available as command line parameter and option statement.

Note

The value for profile that is specified with an option statement in the GAMS input file overrides the value of profile that is passed through the command line.

Observe that an execution profile will be generated if the option profile is assigned a value larger than zero (zero is the default). Setting profile to 1 has the effect that execution times for each statement and the number of set elements over which the particular statement is executed will be reported. However, statements in programming flow control structures like loops will be omitted. Information on the execution of these statements will be included in the profile if the value is n, with n > 1. Note that an overview of the values for profile is given in the table at the end of this description.

Consider the following GAMS call:

   > gams trnsport profile=1

This call causes the following additional lines to appear in the listing file:

----      1 InitE                    0.000     0.000 SECS      3 MB
----      1 ExecInit                 0.000     0.000 SECS      3 MB
----     44 Assignment c             0.011     0.011 SECS      4 MB      6
----     63 Assignment transport     0.000     0.011 SECS      4 MB      3
----     65 Solve Init transport     0.000     0.012 SECS      4 MB
----     57 Equation   cost          0.001     0.013 SECS      4 MB      1
----     58 Equation   supply        0.000     0.013 SECS      4 MB      2
----     59 Equation   demand        0.000     0.013 SECS      4 MB      3
----     65 Solve Fini transport     0.009     0.022 SECS      4 MB     19
----     65 GAMS Fini                0.001     0.001 SECS      4 MB
----      1 InitE                    0.000     0.000 SECS      2 MB
----      1 ExecInit                 0.000     0.000 SECS      2 MB
----     65 Solver     transport     0.000     0.000 SECS      2 MB
----     65 Solve Read transport     0.002     0.002 SECS      2 MB
----     67 Display                  0.000     0.002 SECS      3 MB
----     69 Display                  0.000     0.002 SECS      3 MB
----     69 GAMS Fini                0.001     0.001 SECS      3 MB

Observe that the first column provides the line number in the input file of the statement that is executed.

The second column reports the type of the respective statement. For an overview of all GAMS statements, see section Classification of GAMS Statements. In addition, ExecInit denotes the beginning of the execution phase of the GAMS input file and GAMS Fini denotes the end of this phase. Note that as soon as a solve statement is processed, GAMS will pass control to the solver system. Once the solver has completed its task, GAMS will restart. Thus we have two ExecInit/ GAMS Fini pairs in our example. Note that only equations are listed, and not variables. This reflects the fact that GAMS uses an equation based scheme to generate a model.

The third and fourth columns show the individual time needed to execute the statement and the cumulative time taken by the GAMS system so far.

The last column gives the number of assignments that were generated in the specified line.

In addition to the lines above, a profile summary is created at the end of the listing file. This summary contains (up to) ten of the slowest execution steps. The profile summary from trnsport.lst follows:

---- Profile Summary (17 records processed)
     0.011   0.004GB        44 Assignment c (6)
     0.009   0.004GB        65 Solve Fini transport (19)
     0.002   0.002GB        65 Solve Read transport
     0.001   0.004GB        65 GAMS Fini
     0.001   0.004GB        57 Equation   cost (1)
     0.001   0.003GB        69 GAMS Fini

Note that execution profiles and profile summaries are particularly useful for detecting the sources of performance problems. For further details, see section Finding the Causes for Slow Program Execution.

Default: 0

Value	Meaning
0	No profiling
1	Minimum profiling
n	Profiling depth for nested control structures

profileFile (string): Write profile information to this file

Synonym: PFILE

Available: Command line

This option causes profiling information to be written to a file. Note that profiling information is only created with the setting profile=1 or profile=2. For example such a file may have the following conten:

          1         -1        0.000    0.003 ExecInit
         45          6        0.000    0.004 Assignment c
         66         -1        0.000    0.004 Solve Init transport
         58          1        0.000    0.004 Equation   cost
         60          2        0.000    0.004 Equation   supply
         62          3        0.000    0.004 Equation   demand
         66         19        0.015    0.004 Solve Fini transport
         66         -1        0.000    0.004 GAMS Fini
          1         -1        0.000    0.002 ExecInit
         66         -1        0.000    0.002 Solve Read transport
         68         -1        0.000    0.003 Display
         68         -1        0.000    0.003 GAMS Fini

profileTol (real): Minimum time a statement must use to appear in profile generated output

Synonym: PTOL (only available on the command line)

Available: Command line, Option statement

This option sets the profile tolerance in seconds. All statements that take less time to execute than this tolerance are not reported in the listing file. Note that this option is only effective if the value of the option profile is larger than zero.

Default: 0

putDir (string): Put file directory

Synonym: PDir

Available: Command line

By default, put files are generated and saved in the current working directory. This option may be used to specify an alternative directory. Note that this option does not work if an absolute file name is provided through the file statement.

putND (integer): Number of decimals for put files

Available: Command line

This sets the default for the put file attribute .nd.

Default: 2

putNR (integer): Numeric round format for put files

Available: Command line

This sets the default for the put file attribute .nr.

Default: 1

Value	Meaning
0	Item is displayed in F or E format
1	Item is rounded to fit given width and decimals
2	Item is displayed in scientific notation
3	Item is rounded to fit given width
4	Item is displayed in F or E format ignoring given decimals

putPS (integer): Page size for put files

Available: Command line

This sets the default for the put file attribute .ps.

Default: 58

putPW (integer): Page width for put files

Available: Command line

This sets the default for the put file attribute .pw.

Default: 32767

QCP (string): Quadratically Constrained Programs - default solver

Available: Command line, Option statement

The default solver for models of the type Quadratically Constrained Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

real1..5 (real): Real communication cell N

Available: Option statement, Attribute statement (use before solve)

This option specifies a real communication cell that may contain any real number.

reference (string): Symbol reference file

Synonym: RF

Available: Command line

If this option is specified, all symbol references will be written to the specified file. Setting rf or Reference to the string 'default' will cause GAMS to create a reference file with the file root name of the GAMS input file and the extension ref. Thus the call

   > gams trnsport rf=default

will generate the reference file trnsport.ref.

The reference file consists of three sections: The information about the code compiled, the information about the symbols in the GAMS program (also known as symbol table) and a list of all files included.

The information about the code compiled consists of records with 11 fields. The meaning of the fields is:

• record count
• symbol index
• symbol name
  
• symbol type
  
• reference type (available: declared, defined, impl-asn, assigned, ref, control)
  
• global listing line
  
• local line
  
• local column position (due to macros this many not be always 100% correct)
  
• include nesting level
  
• index in the file summary
  
• file name

The symbol table starts with the line that is indicated by a 0 in the record count/first field, followed by the number of records in this symbol table and the text "size of symboltable". The records for the symbol table consists of:

• internal symbol index
  
• symbol name
• symbol type (numerical)
• symbol type (string)
• dimension (0 for functions and models)
• cardinality (0 for functions, card(sym) for regular symbols, and number of equation symbols for models)
• list of length dimension with the internal symbol index of the domain set (0 if universe)
• symbol text

The list of files included starts with the line that is indicated by a 0 in the record count/first field, followed by the number of records in this file list and the text "input files". The records for the following list has the same information as the Include File Summary.

With the reference file viewer, GAMS Studio offers a convenient tool for inspecting the reference file.

referenceLineNo (string): Controls the line numbers written to a reference file

Synonym: RFLN

Available: Command line

Default: actual

Value	Meaning
actual	Actual line number of symbol reference
start	Line number where the statement with the reference starts

reform (integer): Reformulation level

Available: Option statement, Attribute statement (use before solve)

This option triggers an objective function reformulation. The interpretation depends on the solver. The solvers MINOS and SNOPT support this option. Note that the default value is zero and the range is [-2147483647,2147483647 ].

replace (string): Switch between merge and replace when reading from GDX into non-empty symbol

Available: Command line, Option statement

The command line parameter Replace initializes the option Replace to control the behavior of gdxLoad.

Default: on

Value	Meaning
off	Merge into existing data when loading
on	Replace existing data when loading

resCalc (real): Time spent in function and derivative calculations (deprecated)

Available: Attribute statement (use after solve)

resDeriv (real): Time spent in derivative calculations (deprecated)

Available: Attribute statement (use after solve)

resGen (real): Time GAMS took to generate the model in wall-clock seconds

Available: Attribute statement (use after solve)

This model attribute returns the time GAMS took to generate the model in wall-clock seconds.

resIn (real): Time to import model (deprecated)

Available: Attribute statement (use after solve)

resLim (real): Wall-clock time limit for solver

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies the time in seconds that the solver can run before it can terminate and return the solver status 3 RESOURCE INTERRUPT. The solver should start the clock soon after it starts, so the time required to read in the problem and do any reformulations, preprocessing or presolving is included in the time limit. Where possible, the time limit applies to the wall-clock time: this behavior translates well to multi-threaded solves. Moreover, some solver links might reinterpret the value of this option. For example, if left at default (1e+10), the solver link might use the default time limit of the solver.

Note

This value could be automatically reduced, if required because of etLim.

Default: 10000000000

resOut (real): Time to export solution (deprecated)

Available: Attribute statement (use after solve)

restart (string): Name of a restart file, see The Save and Restart Feature

Synonym: R

Available: Command line

This option specifies the name of a work file that was written with the option save that will be used to restart the GAMS program. The work file is also called restart file. For more information including examples, see chapter The Save and Restart Feature.

restartNamed (string): Name of another matching restart file, see Obfuscated Work Files

Synonym: RN

Available: Command line

resUsd (real): Time the solver used to solve the model in seconds

Available: Attribute statement (use after solve)

This model attribute returns the time in seconds used by the solver. Wherever possible, the units used (wall-clock time vs. CPU time) will be the same as used by the reslim option.

RMINLP (string): Relaxed Mixed-Integer Non-Linear Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Relaxed Mixed Integer Nonlinear Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

RMIP (string): Relaxed Mixed-Integer Programming - default solver

Available: Command line, Option statement

The default solver for models of the type Relaxed Mixed Integer Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

RMIQCP (string): Relaxed Mixed Integer Quadratically Constrained Programs - default solver

Available: Command line, Option statement

The default solver for models of the type Relaxed Mixed Integer Quadratically Constrained Programs is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

RMPEC (string): Relaxed Mathematical Programs with Equilibrium Constraints - default solver

Available: Command line, Option statement

The default solver for models of the type Relaxed Mathematical Program with Equilibrium Constraints is set during installation. The user may change this default by setting this option to the desired solver.

Observe that if the solver was changed using an option statement, the default solver may be reset later in the program with another option statement, where the value of the option is set to default.

rngBndMax (real): Maximum absolute non-zero value of bounds passed to the solver (excluding infinity)

Available: Attribute statement (use after solve)

rngBndMin (real): Minimum absolute non-zero value of bounds passed to the solver

Available: Attribute statement (use after solve)

rngMatMax (real): Maximum absolute non-zero value of coefficients in the model matrix passed to the solver (excluding infinity)

Available: Attribute statement (use after solve)

Note

For non-linear models, the value of the coefficients looked at depends on the activity levels of one or more of the variables. More details are described here.

rngMatMin (real): Minimum absolute non-zero value of coefficients in the model matrix passed to the solver

Available: Attribute statement (use after solve)

Note

For non-linear models, the value of the coefficients looked at depends on the activity levels of one or more of the variables. More details are described here.

rngRhsMax (real): Maximum absolute non-zero value of right hand sides passed to the solver (excluding infinity)

Available: Attribute statement (use after solve)

rngRhsMin (real): Minimum absolute non-zero value of right hand sides passed to the solver

Available: Attribute statement (use after solve)

rObj (real): Objective function value from the relaxed solve of a mixed-integer model when the integer solver did not finish

Available: Attribute statement (use after solve)

This model attribute returns the objective function value from the relaxed solve of a MIP when the integer solver did not finish.

save (string): Creates a work file, see The Save and Restart Feature

Synonym: S

Available: Command line

This option specifies the name of a work file to be written. The work file is intended to be used later to restart the GAMS program and it is also frequently referred to as save file or restart file. If no explicit file extension is provided, the default file extension .g00 is used. If no specific file path is provided the work file is created in the current directory.

Note

• The character "?" is not allowed in save file names - that use was intended for old (pre-GAMS 21.7) save files only.
• Save files are platform-independent.

For further information including examples, see chapter The Save and Restart Feature.

saveObfuscate (string): Creates an obfuscated work file, see Obfuscated Work Files

Synonym: SO

Available: Command line

savePoint (integer): Save solver point in GDX file

Synonym: SP (only available on the command line)

Available: Command line, Option statement, Attribute statement (use before solve)

This option instructs GAMS to save a point format GDX file that contains the information on the current solution point.

Default: 0

Value	Meaning
0	No point GDX file is to be saved
1	A point GDX file from the last solve is to be saved
2	A point GDX file from every solve is to be saved
3	A point GDX file from the last solve is to be saved in the scratch directory
4	A point GDX file from every solve is to be saved in the scratch directory

scaleOpt (boolean): Employ user specified variable and equation scaling factors

Available: Attribute statement (use before solve)

This option determines whether GAMS will employ user-specified variable and equation scaling factors. It must be set to a nonzero value if scaling factors are to be used. For more details on scaling, see section Model Scaling - The Scale Option.

Default: 0

scrDir (string): Scratch directory

Synonym: SD

Available: Command line

This option specifies the name of the scratch directory. The scratch directory is used by GAMS for intermediate files that are generated during execution. The scratch directory and all its contents are usually deleted at the end of the GAMS run. By default, the scratch directory takes its value from the process directory that is specified with the option procDir. If neither the scratch directory nor the process directory are specified, the scratch directory will be set to a subdirectory of the current working directory with an internally generated name. If the scratch directory is specified, the respective directory must already exist and neither the content nor the directory itself will be deleted by GAMS at the end of the run.

Note that the option solveLink may be used to reduce or eliminate the need for intermediate files.

scrExt (string): Scratch file extension to be used with temporary files

Synonym: SE

Available: Command line

This option specifies the name of the extension for the temporary files that GAMS is generating during execution.

Default: dat

scriptExit (string): Program or script to be executed at the end of a GAMS run

Available: Command line

By default, GAMS does not call an exit script anymore. If this is required, the option scriptExit has to be set explicitly to the script that should be called after GAMS terminates. Note that an empty template of an exit script is in the GAMS system directory: it is called gmsxitnt.cmd for Windows and gmsxitus.run for Unix.

scriptFrst (string): First line to be written to GAMSNEXT file.

Synonym: SF

Available: Command line

This option specifies the first line written to gamsnext. The default is an empty string and the first line is not written.

scrNam (string): Work file names stem

Synonym: SN

Available: Command line

This option specifies the name stem that is used to complete the names of intermediate work files. Note that the name stem must have at least one '?'. The name will be completed with the scratch directory and the standard scratch name extension.

seed (integer): Random number seed

Available: Command line, Option statement

This option specifies the seed that is used for the pseudo random number generator.

Default: 3141

showOSMemory (integer): Show the memory usage reported by the Operating System instead of the internal counting

Available: Command line

GAMS keeps track of how much dynamic memory it has allocated and shows this in the log file at various points. With this option, memory usage statistics from the operating system can be shown instead. This is useful if the dynamic memory allocation is known or suspected to significantly underestimate the total memory usage of the GAMS process.

The resident set size (RSS) of a process is that part of the process address space actually residing in main memory (RAM). It excludes things like memory allocated but never used, memory that has been swapped out to disk, and parts of the executable that have never been loaded.

The virtual set size (VSS) is a measure of the entire address space used by the process, whether that space resides in physical memory or not. On Linux, it is essentially the RSS plus the items excluded from the RSS, i.e. the parts of the process address space that are not currently in physical memory. On macOS, the VSS seems to be a wild overestimate - we don't recommend using VSS on this platform. On Windows, we take VSS from the PagefileUsage reported by the OS. The PagefileUsage for each process does not include some major contributions to the process address space, such as mapped files. For this reason, the process RSS may be larger than its VSS on Windows, but VSS is still a good measure of dynamic memory allocation done by a process.

Default: 0

Value	Meaning
0	Show memory reported by internal accounting
1	Show resident set size reported by operating system
2	Show virtual set size reported by operating system

solPrint (integer or string): Solution report print option

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the printing of the solution listing to the listing file.

N.B: the command line accepts the string and numeric value, the option statement only the string value, and the attribute statement accepts the numeric value and compile-time constant. The table below offers an overview of the different types of values and a description of the associated meaning.

String Value	Numeric Value	Compile-Time Constant	Meaning
off	0	solprint.Off	Remove solution listings following solves
on	1	solprint.On	Include solution listings following solves
silent	2	solprint.Silent	Suppress all solution information

Default: On

solSlack (boolean): Causes the equation output in the listing file to contain slack variable values instead of level values

Available: Option statement

If the value of this option is set to 1, the equation output in the listing file will contain slack variable values instead of level values.

Default: 0

Value	Meaning
0	includes equation levels in the solution part of the LST file following solves
1	includes equation slacks in the solution part of the LST file following solves

solveLink (integer): Solver link option

Synonym: SL (only available on the command line)

Available: Command line, Option statement, Attribute statement (use before solve)

This option specifies what solver linking conventions are used when GAMS executes a solve statement. Note that values 3 and 6 are relevant for grid computing and multi-threaded solves, respectively. Observe that there are compile-time constants that are associated with this option. When the model instance is saved to the scratch directory (values 0, 1, 2, and 3), the solution produced by the solve is also written to the scratch directory and read in by GAMS when the execution resumes.

Default: 2

Value	Meaning
0	Model instance and entire GAMS state saved to scratch directory, GAMS exits (and vacates memory), and the solver script is called. After the solver terminates, GAMS restarts from the saved state and continues to executing
1	Model instance saved to scratch directory, the solver is called from a shell while GAMS remains open
2	Model instance saved to scratch directory, the solver is called with a spawn (if possible) or a shell (if spawn is not possible) while GAMS remains open - If this is not supported by the selected solver, it gets reset to 1 automatically
3	Model instance saved to scratch directory, the solver starts the solution and GAMS continues
4	Model instance saved to scratch directory, the solver starts the solution and GAMS waits for the solver to come back but uses same submission process as 3 (test mode)
5	The model instance is passed to the solver in-memory - If this is not supported by the selected solver, it gets reset to 2 automatically
6	The model instance is passed to the solver in-memory, the solver starts the solution and GAMS continues
7	The model instance is passed to the solver in-memory, the solver starts the solution and GAMS waits for the solver to come back but uses same submission process as 6 (test mode)

solveOpt (integer or string): Multiple solve management

Available: Command line, Option statement, Attribute statement (use before solve)

This option will instruct GAMS how to manage the model solution if only part of the variables and equations in the particular problem are solved.

Observe that this option is available as model attribute, option statement and command line parameter. The values for model attributes are numeric, while the values for option statements are text strings. The command line parameter accepts both, numeric and text values. In addition, there are compile-time constants that are associated with this option. The first of the two tables below offers an overview of how the different types of values are related and the second table gives the values in numerical terms and a description of the associated meaning.

Numeric Value	String Value	Compile-Time Constant
0	replace	solveOpt.Replace
1	merge	solveOpt.Merge
2	clear	solveOpt.Clear

Default: Merge

Value	Meaning
0	The solution information for all equations appearing in the model is completely replaced by the new model results; variables are only replaced if they appear in the final model
1	The solution information for all equations and variables is merged into the existing solution information
2	The solution information for all equations appearing in the model is completely replaced; in addition, variables appearing in the symbolic equations but removed by conditionals will be removed

solver (string): Default solver for all model types that the solver is capable to process

Available: Command line, Option statement

The command line parameter solver=abc initializes the default solver for the model types the solver "abc" is capable of to abc. This initialization is done before the default solvers of individual model types are set via command line parameters. Consider the following example:

   > gams trnsport lp=conopt solver=soplex

Note that this GAMS call will first set the solver SOPLEX as the solver for the model types LP and RMIP, since these are the model types that SOPLEX can handle. Then Conopt will be reset as the default solver for LPs. Observe that the order of these parameters on the command line is irrelevant. If multiple occurrences of the option solver appear, the last entry will set the value of the option.

In addition, the solver for multiple model types may be set in the GAMS model source code via the following statement:

option solver = abc;

This statement sets the solver for the model types the solver abc can handle to abc. Note that in such an option statement the order of other solver setting options is significant. Consider the following example:

option lp=conopt, solver=soplex;

This statement will first set the solver for LPs to Conopt and in the next step to SOPLEX because SOPLEX is capable of handling the model type LP. In some cases it makes sense to set a solver twice. Consider the following example:

option solver=conopt, solver=cbc;

This option statement has the effect that models of the types CNS, DNLP, NLP, QCP, RMIQCP or RMINLP will be solved with Conopt and models of the types LP, RMIP or MIP will be solved with CBC.

Note that as usual, a specification of a solver through an option statement in the GAMS source takes precedence over a specification on the command line.

solverCntr (string): Solver control file name

Synonym: SCNTR

Available: Command line

This option specifies the solver control file name. Note that the name is completed with the scratch directory and the scratch extension.

solverDict (string): Solver dictionary file name

Synonym: SDICT

Available: Command line

This option specifies the solver dictionary file name. Note that the name completed with the scratch directory and the scratch extension.

solverInst (string): Solver instruction file name

Synonym: SINST

Available: Command line

This option specifies the solver instruction file name. Note that the name is completed with the scratch directory and the scratch extension.

solverMatr (string): Solver matrix file name

Synonym: SMATR

Available: Command line

This option specifies the solver matrix file name. Note that the name is completed with the scratch directory and the scratch extension.

solverSolu (string): Solver solution file name

Synonym: SSOLU

Available: Command line

This option specifies the solver solution file name. Note that the name is completed with the scratch directory and the scratch extension.

solverStat (string): Solver status file name

Synonym: SSTAT

Available: Command line

This option specifies the solver status file name. Note that the name is completed with the scratch directory and the scratch extension.

solveStat (integer): Indicates the solver termination condition

Available: Attribute statement (use after solve)

This model attribute indicates the solver termination condition. Observe that there are compile-time constants that are related to solveStat. Note that additional information to the values given in the table below is provided in section Solver Status.

Value	Meaning
1	Normal Completion
2	Iteration Interrupt
3	Resource Interrupt
4	Terminated By Solver
5	Evaluation Interrupt
6	Capability Problems
7	Licensing Problems
8	User Interrupt
9	Setup Failure
10	Solver Failure
11	Internal Solver Failure
12	Solve Processing Skipped
13	System Failure

stepSum (boolean): Summary of computing resources used by job steps

Available: Command line

This option controls the generation of a step summary of the processing times taken by GAMS during a given run.

For example, the call

   > gams trnsport stepsum=1

will generate the following step summaries in the listing file:

STEP SUMMARY:     0.016       0.016 STARTUP
                  0.005       0.005 COMPILATION
                  0.065       0.065 EXECUTION
                  0.001       0.001 CLOSEDOWN
                  0.087       0.087 TOTAL SECONDS
                  0.089       0.089 ELAPSED SECONDS
                  3.942       3.942 MAX HEAP SIZE (MB)

Note that this step summary will be printed before the model is sent to the solver, thus it may be found before the solve summary. The second step summary will be printed after solution, it will appear at the very end of the listing file:

STEP SUMMARY:     0.004       0.020 STARTUP
                  0.000       0.005 COMPILATION
                  0.003       0.068 EXECUTION
                  0.000       0.001 CLOSEDOWN
                  0.007       0.094 TOTAL SECONDS
                  0.239       0.328 ELAPSED SECONDS
                  2.899       3.942 MAX HEAP SIZE (MB)

Observe that the first column reports the time for the individual section of the run, while the second column reports accumulated times including previous sections.

Default: 0

Value	Meaning
0	No step summary
1	Step summary printed

strictSingleton (boolean): Error if assignment to singleton set has multiple elements

Available: Command line, Option statement

This option affects the behavior of a membership assignment to a singleton set. If the value is set to zero, GAMS will not complain about a singleton set with more than one element, but will take only the first element. However, if the value is set to 1, a singleton set definition with more than one element will cause an error. Also, if this option is set as a command line parameter it initializes the state of the dollar control option $on/offStrictSingleton. So, it influences the singleton set checking at both compile- and execution time.

Default: 1

Value	Meaning
0	Take first record if assignment to singleton set has multiple elements
1	Error if assignment to singleton set has multiple elements

stringChk (integer): String substitution options

Available: Command line

This option affects the result of the check for %xxx% symbols. Note that %xxx% symbols may be environment variables (also at execution time) or compile-time variables.

Default: 0

Value	Meaning
0	No substitution if symbol undefined and no error
1	Error if symbol undefined
2	Remove entire symbol reference if undefined and no error

subSys (string): Name of subsystem configuration file

Available: Command line

This option specifies the name of the configuration file that contains solver defaults and other information. This option should be used only by advanced users who attempt to override internal subsystem information. In case you want to add a solver to your GAMS system, please inspect the section Adding Solvers via gamsconfig.yaml.

subSystems (no value): Lists all solvers available as well as the current default and active solvers in the LST file

Available: Option statement

This option has the effect that all available subsystems will be displayed in the listing file. Note that a solver is considered a subsystem.

suffixAlgebraVars (string): Switch default for "$on/offSuffixAlgebraVars"

Available: Command line

For more info see $on/offSuffixAlgebraVars.

Default: on

Value	Meaning
off	Activate $offSuffixAlgebraVars
on	Activate $onSuffixAlgebraVars

suffixDLVars (string): Switch default for "$on/offSuffixDLVars"

Available: Command line

For more info see $on/offSuffixDLVars.

Default: off

Value	Meaning
off	Activate $offSuffixDLVars
on	Activate $onSuffixDLVars

sumInfes (real): Sum of infeasibilities

Available: Attribute statement (use after solve)

This model attribute returns the sum of infeasibilities after a solve.

suppress (boolean): Compiler listing option

Available: Command line

If set to 1, this option will suppress the echoing of the contents of the input file(s) to the listing file. Note that this option is similar in functionality to the dollar control option $offlisting.

Note

The dollar control options $on/offlisting will affect the echo print in the listing file only if suppress is set to zero. If suppress is set to 1, the input file(s) will not be echoed to the listing file and the dollar control options will not have any effect on the listing file.

Default: 0

Value	Meaning
0	Standard compiler listing
1	Suppress compiler listing

symbol (string): Symbol table file

Available: Command line

This option specifies the name of a partial symbol table that may be written in conjunction with reference files.

symPrefix (string): Prefix all symbols encountered during compilation by the specified string in work file

Available: Command line

sys10 (boolean): Changes rpower to ipower when the exponent is constant and within 1e-12 of an integer

Available: Command line, Option statement

Default: 0

Value	Meaning
0	Disable conversion
1	Enable conversion

sys11 (integer): Dynamic resorting if indices in assignment/data statements are not in natural order

Available: Command line, Option statement

Speed-up for expressions containing constant indices or indices that are not in the natural order at the cost of increased memory use.

Default: 0

Value	Meaning
0	Automatic optimization/restructuring of data
1	No optimization
2	Always optimize/restructure

sys12 (integer): Pass model with generation errors to solver

Synonym: noSolveSkip (only available on the command line)

Available: Command line, Option statement

Default: 0

sys15 (integer): Automatic switching of data structures used in search records

Available: Command line, Option statement

Default: 0

Value	Meaning
0	Automatic switching to dense data structures
1	No switching
2	Always switch
1x	Print additional information in lst file

sys16 (integer): Disable search record memory (aka execute this as pre-GAMS 24.5)

Available: Command line, Option statement

Default: 0

sys17 (integer): Disable sparsity trees growing with permutation (aka execute this as pre-GAMS 24.5)

Available: Command line, Option statement

Default: 0

sys18 (integer): Use backward compatible (i.e. pre-GAMS 31) scheme for reading floating-point numbers

Available: Command line, Option statement

By default GAMS accepts floating-point numbers with arbitrarily many digits and converts them to correctly-rounded double-precision values. This option selects a backward compatible (i.e. pre-GAMS 31) scheme for reading floating-point numbers (see also the offDigit dollar control option).

Default: 0

Value	Meaning
0	Use modern scheme for reading floating-point numbers
1	Use backward compatible (i.e. pre-GAMS 31) scheme for reading floating-point numbers

sys19 (integer): Disable permutation on Column Generation (aka execute this as pre-GAMS 36)

Available: Command line, Option statement

Default: 0

sysDir (string): GAMS system directory where GAMS executables reside

Available: Command line

This option sets the GAMS system directory. It is useful if there are multiple systems installed on the machine or when GAMS is called from an external system like Visual Basic.

sysIdent (real): Solver identification number

Available: Attribute statement (use after solve)

sysIncDir (string): SysInclude directory

Synonym: SDIR

Available: Command line

This option specifies the name of the directory to be used by GAMS for sysinclude files that do not have a full path specification. An absolute or relative path may be specified. If this option is not set, it will be set to the GAMS system directory.

Note that if this option is set, the default system include directory will not be searched.

Attention

Only one directory may be set with the option sDir. Thus the string specified will be treated as one directory. If additional directories are added, errors will be reported.

Consider the following example:

   > gams myfile sdir mydir

Note that GAMS will search for any referenced sysinclude file in the directory mydir.

sysOut (boolean or string): Solver Status file reporting option

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls whether additional solver generated output (the solver status file) is included in the listing file. Note that the contents of the solver status file are useful for debugging or to get additional information about a solver run. Normally, only those messages flagged by the solver as destined for the listing file will be listed. If the solver crashes or encounters any unexpected difficulties, the contents of the solver status file will be automatically sent to the listing file.

Note that the boolean values (off: 0 and off: 1) are deprecated, they are only relevant for backward compatibility. The table below gives the boolean values and the associated meaning.

String Value	Meaning
off	Suppress additional solver generated output
on	Include additional solver generated output

Default: Off

sysVer (real): Solver version

Available: Attribute statement (use after solve)

tabIn (integer): Tab spacing

Available: Command line

This option sets the tab spacing. The default value is 8, which means that the tabs are at columns 1, 9, 17, ... and the intermediate columns are replaced by blanks.

Default: 8

Value	Meaning
0	Tabs are not allowed
1	Tabs are replaced by blanks
n	Tabs are 1, n+1, 2n+1,.. (default: n=8)

tFormat (boolean): Time format

Synonym: TF

Available: Command line

This option controls the time format in the listing file. The three date formats correspond to the various conventions used around the world. For example, the time 7:45~PM will be written as 19:45:00 with the default tf value of zero and as 19.45.00 with tf=1.

Default: 0

Value	Meaning
0	Time as hh:mm:ss
1	Time as hh.mm.ss

threads (integer): Number of processors to be used by a solver

Available: Command line, Option statement, Attribute statement (use before solve)

This option controls the number of processors to be used by a solver, often by using several threads for parallel computations. If the number is greater than the number of available processors, it will be reduced to the number of processors available. A value of zero means that the solver or solver-link will decide on the number of processors to use.

Default: 0

Value	Meaning
0	Solver decides on number of processors to use
n	Use n processors
minus_n	Number of processors to leave free for other tasks

threadsAsync (integer): Limit on number of threads to be used for asynchronous solves (solveLink=6)

Available: Command line, Option statement

Default: -1

Value	Meaning
0	Use number of available processors
n	Use n threads
minus_n	Number of processors to leave free for other tasks

timer (integer): Instruction timer threshold in milli seconds

Available: Command line

This option specifies an instruction timer threshold in milli seconds. That means that only details about internal GAMS intructions that took more than n milli seconds are echoed to the log.

Default: 0

Value	Meaning
0	Interpreted as +inf, no details echoed
n	Echo all details about internal GAMS instructions that took more than n milli seconds to the log

tolInfeas (real): Infeasibility tolerance for an empty row of the form a.. 0*x =e= 0.0001;

Available: Attribute statement (use before solve)

This option specifies the infeasibility tolerance for an empty row of the following form:

a.. 0*x =e= 0.0001;

If the option is not set, a tolerance of 10 times the machine precision will be used. Empty rows that fail this infeasibility check will be flagged with the listing file message Equation infeasible due to rhs value.

tolInfRep (real): This attribute sets the tolerance for marking infeasible in the equation listing

Available: Attribute statement (use before solve)

This option sets the tolerance for marking an equation infeasible in the equation listing. Note that the default value is 1.0e-13.

Default: 1.0E-13

tolProj (real): Tolerance for setting solution values to a nearby bound when reading a solution

Available: Attribute statement (use before solve)

When a solution is returned from a solver, equation and variable level values that are very close to their lower or upper bounds are projected or moved to that bound, and a count of the projections/moves made is included in the solution report's REPORT SUMMARY. This option controls the relative tolerance used in testing for closeness: project if abs(level-bound) < tolproj*(1+abs(level)). For MCP models, this projection is also applied to the variable marginal values. In this case the projection count is not incremented and the test is an absolute and not a relative test: project if abs(marginal) < tolproj.

Default: 0

trace (string): Trace file name

Available: Command line

This option specifies the trace file name and causes a trace file to be written. Note that if a previous trace file of the same name already exists, then all new data output will be appended. Therefore, users should be careful to delete all old versions of the trace file if the a file name is reused and they do wish the new data to be appended.

traceLevel (integer): Modelstat/Solvestat threshold used in conjunction with action=GT

Synonym: TL

Available: Command line

Default: 0

traceOpt (integer): Trace file format option

Available: Command line

This option specifies the format of the trace file. Note that several different types of trace files may be created, depending on what output information is desired.

Default: 0

Value	Meaning
0	Solver and GAMS step trace
1	Solver and GAMS exit trace
2	Solver trace only
3	Solver trace only in format used for GAMS performance world
5	Gams exit trace with all available trace fields

tryInt (real): Whether solver should make use of a partial integer-feasible solution

Available: Attribute statement (use before solve, reset by solve statement)

Signals the solver to make use of a partial or near-integer-feasible solution stored in current variable values to get a quick integer-feasible point. The exact form of implementation depends on the solver and may be partly controlled by solver settings or options. See the solver manuals for details.

tryLinear (real): Examine empirical NLP model to see if there are any NLP terms active. If there are none the default LP solver will be used

Available: Attribute statement (use before solve)

If this option is set to 1, empirical NLP models will be examined to determine if there are any active NLP terms. If there are none, the default LP solver will be used. The procedure also checks to see if QCP and DNLP models can be reduced to an LP; MIQCP and MINLP can be solved as a MIP; RMIQCP and RMINLP can be solved as an RMIP. Note that the default value is zero.

user1..5 (string): User string N

Synonym: U1

Available: Command line

This option permits users to enter a text for up to 5 user-defined options. The double dash parameters supersede these parameters.

warnings (integer): Number of warnings permitted before a run terminates

Available: Command line

This option specifies the maximum number of allowable warnings, before the run terminates.

Default: ∞

workDir (string): Working directory

Synonym: WDir

Available: Command line

This option sets the working directory. This option is useful when GAMS is called from an external system like Visual Basic. If it is not specified, the working directory will be set to the directory curDir.

workFactor (real): Memory Estimate multiplier for some solvers

Available: Command line, Attribute statement (use before solve)

This option instructs the solver how much workspace to allocate for problem solution relative to the solver-computed estimate. For example, setting the value to 2 will double the memory estimate. In cases where a solver allocates memory dynamically as it is needed, this option will have no effect. Note that in cases where both options workfactor and workSpace are specified, the value for workSpace will take precedence.

Default: 1

workSpace (real): Work space for some solvers in MB

Available: Command line, Attribute statement (use before solve)

This option instructs the solver how much workspace in Megabytes to allocate. If it is not speicified by the user, the solver will estimate the size. In cases where a solver allocates memory dynamically as it is needed, this option will have no effect, or it may be used as a memory limit.

writeOutput (boolean): Switch to write output file

Available: Command line

This option controls whether to write the output file.

Default: 1

Value	Meaning
0	Suppress output file creation
1	Write output file

xSave (string): Creates a compressed work file

Synonym: XS

Available: Command line

This option specifies the name of a save file written in ASCII format in older GAMS systems (versions older than 21.7), in order for the save file to be platform independent and may be moved to machines with different operating systems.

In GAMS systems from release 22.3 and newer this option has the effect that compressed save files are written.

xSaveObfuscate (string): Creates a compressed obfuscated work file

Synonym: XSO

Available: Command line

zeroRes (real): The results of certain operations will be set to zero if abs(result) LE ZeroRes

Available: Command line

This option specifies the threshold value for internal rounding to zero in certain operations.

Default: 0

zeroResRep (boolean): Report underflow as a warning when abs(results) LE ZeroRes and result set to zero

Available: Command line

This option causes GAMS to issue warnings whenever a rounding occurs because of the setting of the option zeroRes.

Default: 0

Value	Meaning
0	No warning when a rounding occurs because of ZeroRes
1	Issue warnings whenever a rounding occurs because of ZeroRes

zeroToEps (string): Treat zero as eps

Available: Option statement

When this is set to on, zero values are interpreted as EPS when loading non-scalar parameters from GDX or embedded code at execution time. Also, when deriving a set from a parameter in a GDX file at execution time, set records will be created for parameter records with value 0, if zeroToEps is set to on, but not, if it is off.

See dollar control option $onEps for the compile-time equivalent.

Default: off

Value	Meaning
off	Treat Zero as Zero
on	Treat Zero as Eps

Executing an External Program

External programs may be run during a GAMS job either using the $call, Execute or Put_utility syntax. The $call procedure is executed at the moment that is encountered during compilation. The Execute and Put_utility commands causes the external program to be run during GAMS program execution. The contrast between these statements is important in two ways.

• Influence on results that can be included in a GAMS program – Anything run with $Call can generate files that can be included in the subsequent compilation. On the other hand files generated with Execute and Put_utility cannot be included because $Include operates only at compile time (unless you use Save and Restart).
• Influence on results that can be fed into the external program – Obviously when one is running an external program there is the desire to pass it data depicting results of the GAMS execution. $Call cannot do this as the data passed have to exist at compile time and cannot use the result of any GAMS calculations and solves in the current program. Execute commands on the other hand can use any data generated during a run which arise before the Execute and Put_utility command's position in the file through passage via put files or other mechanisms.

The big difference between the $call and execute is

• $call
  • can generate results to be immediately incorporated back into GAMS
  • cannot use GAMS results generated within this run because the $Call is executed at compile time.
• execute and put_utility
  • can cause a program to be started using results generated by the GAMS program (note such results do have to have been saved in an external file using a command like put)
  • cannot generate results which can be immediately reincluded into the GAMS program because new material can only be added compile time.

Execute

This command uses the syntax

execute[.async[NC]|.checkErrorLevel] "[=]command_to_execute"

to execute a program specified by command_to_execute. The execution occurs during the GAMS execution phase.

• The = will call the program directly, while without the = GAMS calls a shell that executes the program. When a program is executed in a shell, mechanisms like redirection (>) and pipe (|) are available. Simple commands (e.g. rm trnsport.lst) work in many different shells, but more advanced shell syntax (e.g. conditional expressions, loops, parameter expansion) will depend on the specific shell used. On Windows, GAMS will always use the command prompt (cmd.exe), but on non-Windows platforms it depends on the system configuration. If in doubt, run execute "echo $SHELL" in GAMS to detect what shell is being used, and be aware that advanced shell syntax may not be portable.
• The .async suffix makes GAMS go ahead without waiting.
• The .asyncNC option tells the operating system to start the run a new console rather than sharing the console of the parent process allowing use of multiple processors. This is available under Windows only.
• The .checkErrorLevel suffix checks the errorLevel implicitly, raises an execution error and aborts the execution, if that is not 0.
• Since this occurs during execution one cannot use the compile time $Include to incorporate the results of that external run into the GAMS code except through a GAMS from GAMS approach as discussed below or through save and restart use (see the Save Restart chapter).

Asynchronous Execution

The .async variant of $call and execute start a job without waiting for the result. One can continue in the GAMS program and collect the return code of the job later. There are three ways to start a job asynchronously:

• $call.async ... (compile phase)
• execute.async '...'; (execution phase)
• ‘put_utility fx 'exec.async’ / '...'; / put_utility fx 'shell.async' / '...';` (execution phase)

After each of those the function JobHandle can be used to get the Process ID (pid) of the last job started. With jobStatus(pid) one could check for the status of a job. Possible return values are:

• 0: error (input is not a valid PID or access is denied)
• 1: process is still running
• 2: process is finished with return code which could be accessed by errorLevel
• 3: process not running anymore or was never running, no return code available

With jobTerminate(pid) a interrupt signal can be sent to a running job. If this was successful the return value is one, otherwise it is zero.

With jobKill(pid) a kill signal can be sent to a running job. If this was successful the return value is one, otherwise it is zero.

The model [ASYNCEXEC] from the GAMS Test Library demonstrates the use of this feature.

Executing a GAMS Tool

To call tools from the GAMS Tool Library, there are counterparts to the $call and Execute, namely $callTool and ExecuteTool. The behavior is identical to the methods explained in the introduction of Executing an External Program.

ExecuteTool

This command uses the syntax

executeTool[.checkErrorLevel] '[toolCategory.]toolName tool_arguments';

to execute a tool specified by [toolCategory.]toolName together with the arguments tool_arguments. The execution occurs during the GAMS execution phase.

• The .checkErrorLevel suffix checks the errorLevel implicitly, raises an execution error and aborts the execution, if that is not 0.
• Since this occurs during execution one cannot use the compile time $Include to incorporate the results of that external run into the GAMS code except through save and restart use (see the Save Restart chapter).

For examples please refer to the GAMS Tools Library chapter.