The GAMS Call and Command Line Parameters

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 theses entities as command line parameters and demonstrate its with the gams executable 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
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: >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 Mac OS X. 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. 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: 0
- 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 0. 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 by uploading the gamsconfig.yaml to the GAMS configuration validator or 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:

yaml = YAML(typ="safe")
with open('gamsconfig.yaml') as 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 a couple of options have been introduced. The system directory contains a file gams31config.yaml with default values used by GAMS 31 (and previous versions). Copy this file as gamsconfig.yaml to a location searched by GAMS to continue to work with the older defaults.

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:

SHOT 1001 5 000102030405 1 0 2 MINLP MIQCP
gmsgennt.cmd
gmsgennx.exe
shtcclib64.dll sht 1 1

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:
auditCode: sht
solverInterfaceType: 1
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=BonMin; 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 s 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%


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.locally Optimal% 2 %modelStat.unbounded% 3 %modelStat.infeasible% 4 %modelStat.locallyInfeasible% 5 %modelStat.intermediateInfeasible% 6 %modelStat.feasibleSolution% 7 %modelStat.integerSolution% 8 %modelStat.intermediateNon-Integer% 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.unbounded-NoSolution% 18 %modelStat.infeasible-NoSolution% 19 %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 # 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.

## 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
curDir Current directory
decryptKey Key to decrypt a text file that was encrypted via $encrypt dFormat Date format digit Switch default for "$on/offDigit"
dumpOpt Writes preprocessed input to the file input.dmp
dumpParms GAMS parameter logging
dumpParmsLogPrefix Prefix of lines triggered by DumpParms>1
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)
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 new file names (put, gdx, ref 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 default for "$on/offFiltered" forceWork Force GAMS to process a save file created with a newer GAMS version or with execution errors forLim GAMS looping limit freeEmbeddedPython Free external resources at the end of each embedded Python code blocks 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) 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 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
maxProcDir Maximum number of 225* process directories
MCPRHoldFx Print list of rows that are perpendicular to variables removed due to the holdfixed setting
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
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
pyMultInst GAMS/Python Multiple Instance Interpreter
reference Symbol reference file
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
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 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 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 acceptance 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 integer1..5 Integer communication cells intVarUp Set default upper bound 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 threads 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 that we indicate for each entry the context in which the option is available. Observe that the options are listed in alphabetical order for easy reference. 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 acceptance threshold Available: Command line, Option statement, Attribute statement (use before solve) The value specified for bRatio will cause a basis to be discarded if the number of basic variables is smaller than bRatio times the number of equations. Certain (pivotal) solution procedures can restart from an advanced basis that is constructed automatically. This option is used to specify whether basis information (probably from an earlier solve) will be used. The use of this basis will be rejected if the number of basic variables is smaller than bRatio times the size of the basis. Setting bRatio to 1 will cause all existing basis information to be discarded, which is sometimes needed with nonlinear problems. A bRatio of 0 accepts any basis and forces GAMS to construct a basis using whatever information is available. If bRatio has been set to 0 and there was no previous solve, an all slack (sometimes called all logical) basis will be provided. This option has no effect for most MIP solvers because MIP presolve destroys a basis. 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 via execute, put_utility exec and put_utility shell and an execution error is triggered if it is not 0. So, with checkErrorLevel = 1 the before mentioned statements behave like execute.checkErrorLevel, put_utility exec.checkErrorLevel and put_utility shell.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 and a compilation error is triggered if that is not 0. So, $call behaves like$call.checkErrorLevel and $hiddenCall behaves like$hiddenCall.checkErrorLevel in this case.

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.

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: on 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. The report that is generated in this way is called a memory dump. 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. 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 he 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/30/11 08:43:06 * INPUT = C:\Fred\GAMS options\test\trnsport2.gms * DUMP = C:\Fred\GAMS options\test\trnsport2.dmp * RESTART = C:\Fred\GAMS options\test\trans1.g0? * with time stamp of 11/30/11 08:40:41 * 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)

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

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: ***

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 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 INCLUDE 2 BATINCLUDE 3 LIBINCLUDE 4 SYSINCLUDE 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.

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 new file names (put, gdx, ref etc.)

Available: Command line

This option facilitates modifying the case of file names for files like put files, GDX files, reference files. It only works with new file names. However, note that it won't create trnsport.REF if TRNSPORT.ref already exists.

Default: 0

Value Meaning
0 Causes GAMS to use default casing
1 Causes GAMS to upper case file names
2 Causes GAMS to lower case file names

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 default for "$on/offFiltered" Available: Command line For more info see$on/offFiltered.

Default: on

Value Meaning
off Activate $offFiltered on Activate$onFiltered

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: ∞

freeEmbeddedPython (boolean): Free external resources at the end of each embedded Python code blocks

Available: Command line

This parameter changes the behavior of $offEmbeddedCode and endEmbeddedCode. When set to 1, internal resources get freed and with the next start of an embedded Python code section, the Python environment has to be reinitialized. This is not the case when this parameter is set to 0. In that case also the interpreter stays "alive", which allows to access Python symbols defined in one embedded code block in a following block. Default: 0 Value Meaning 0 Keep resources to reuse them potentially 1 Free resources 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 gdxUels (string): Unload labels or UELs to GDX either squeezed or full Available: Command line, Option statement This option specifies the UEL export mode. 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 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": {
"type":"object",
"properties":{
"alias":{
"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"
]
},
"type":"object",
"minProperties":1,
"$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"]
}
},
"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",
"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",
"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

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 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 a PC 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 in PC systems 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 default upper bound 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 does not apply to barrier iterations and major iterations in nonlinear solvers. For these iterations solver-specific options need to be set. 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.

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)

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

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

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 screen/console. If logOption is set to 2, the log will be redirected to a file. With logOption=3 all the output goes to the standard output. 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 rhe 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
1 Log output to screen (console)
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. This value can be overwritten with the function maxExecError.

Default: 0

Value Meaning
0 No errors allowed limit
n Max number allowed

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.

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 Intermediate Nonoptimal
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.

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=trnsport.out
gams trnsport o=c:\test\trnsport.out


Note that the first call will create an output file called trnsport.lst (for PC and Unix platforms) in the current directory. The second call will create a file called trnsport.out 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 lst file can be suppressed by setting output to NUL under Windows or to /dev/null on most Unix machines.

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.

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.

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 platforms Windows and AIX setting of 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.

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 Solve Alg  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

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 fields
2 Item is displayed in scientific notation

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

pyMultInst (integer): GAMS/Python Multiple Instance Interpreter

Available: Command line

This options controls the setup of the Python interpreter for use in embedded Python code sections. If this option is set to 1 the embedded Python code can work with multiple independent Python sessions. If pyMultInst is set to 0 there is a single interpreter even with multiple parallel embedded Python sessions that all share the same data space. With pyMultInst set to 0 or 1, the environment variable GMSPYTHONMULTINST is set by GAMS to this value. If the option is not set the value will be taken from the user environment variable GMSPYTHONMULTINST. Note that setting this to 1 might cause problems when using third party modules and packages (e.g. numpy or modules that make use of it) and might also impact the performance.

Default: 0

Value Meaning
0 Use a single-session Python interpreter
1 Use a multi-session Python interpreter

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.

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 ].

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 CPU seconds(deprecated)

Available: Attribute statement (use after solve)

This model attribute returns the time GAMS took to generate the model in CPU 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.

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.

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

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

Default: 0

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

solPrint (int 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.

Note that the numeric values plus some compile-time constants are deprecated (off: 0 andsolprint.Summary, on: 1 and solprint.Report, and silent: 2 and solprint.Quiet) they are only relevant for backward compatibility. Note further, that there are compile-time constants that are associated with this option. The table below offers an overview of the different types of values and a description of the associated meaning.

String Value Compile-Time Constant Meaning
off solprint.Off Remove solution listings following solves
on solprint.On Include solution listings following solves
silent 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

Synonym: SL

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. 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
3 Model instance saved to scratch directory, the solver starts the solution and GAMS continues in a grid computing environment
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
6 The model instance is passed to the solver in-memory, the solver starts the solution and GAMS continues in a grid computing environment
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 (int or string): Multiple solve management

Available: 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 and option statement. The values for model attributes are numeric, while the values for option statements are text strings. 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: 1

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=bdmlp


Note that this GAMS call will first set the solver BDMLP as the solver for the model types LP, RMIP and MIP, since these are the model types that BDMLP 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=bdmlp;


This statement will first set the solver for LPs to Conopt and in the next step to BDMLP because BDMLP 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 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. 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 Available: Command line, Option statement Default: 0 sys15 (integer): Automatic switching of data structures used in search records Available: Command line 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 Default: 0 sys17 (integer): Disable sparsity trees growing with permutation (aka execute this as pre-GAMS 24.5) Available: Command line Default: 0 sys18 (integer): Use backward compatible (i.e. pre-GAMS 31) scheme for reading floating-point numbers Available: Command line 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 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 (bool 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. By default, tabs are not allowed in GAMS. However, the most common setting is 8. As a result, 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 threads to be used by a solver Available: Command line, Option statement, Attribute statement (use before solve) This option controls the number of threads (and thereby the number of processors) to be used by a solver. If the number is greater than the number of available processors, it will be reduced to the number of processors available. Note that a value of zero implies the number of threads used will be equal to the number of processors available. 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 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 a variable level to its bound and filtering marginals when reading a solution Available: Attribute statement (use before solve) This option controls the absolute tolerance for filtering marginals (i.e. setting marginals within the tolerance to zero) and the relative tolerance for projecting levels to the lower or upper bound that are within the tolerance when reading a solution (do projection if abs(level-bound)<tolproj*(1+abs(level))) Default: 1.0E-08 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. 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 dependent 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 (|) will work.
• 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 and raises a execution error, 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.