GAMS Return Codes

The most convenient way to embed a GAMS program in a different program (e.g. C#, Java, Python, ...) is the object orient API to GAMS. A much simpler but less powerful way is to make a call to the GAMS executable (gams.exe (Windows) or gams (Unix)) with appropriate parameters from your program. Different languages and operating systems have different ways of accomplishing such a task. A common way to communicate a small piece of information from the GAMS program to the caller program is the exit status or return code (see e.g. https://en.wikipedia.org/wiki/Exit_status). GAMS return codes allow the caller to get some information about the status of the finished GAMS job. Note that return codes do not provide information about a model inside the GAMS job: the model may have been infeasible or may have failed in another way while the return code says all is fine. In fact, there may be multiple solves in a GAMS job, so even conceptually it is not possible to return solution status codes in the return code. The user cannot explicitly set the return code but can trigger action (e.g. abort 'stop';) that result in a specific return code (here execution error (3)).

Note
In general, the value of zero for return codes denotes success and non-zero values denote failure.

We first demonstrate how to access return codes from within GAMS with a self-explanatory example and then list all return codes. GAMS has the ability to call other programs via the $call (compile time) and execute (execution time) commands. Naturally, GAMS can call GAMS in a recursive fashion. There are different methods to access the return code of such a sub-GAMS job:

$onecho > x.gms
set a /1,2,3/;
$offecho

* Compile time access inside to return values

* Example for non-zero return code
$call gams x.gms lo=0 this_causes_a_parameter_error_with_return_code_6=1 > %system.nullfile%

* Check the return code via if [not] errorlevel n
$if not errorlevel 1 $abort expect a errorlevel >= 1

* Access the return code as function value of function errorLevel
$eval MYERRORLEVEL errorLevel
$log %MYERRORLEVEL%

* Example for zero return code
$call gams x.gms lo=0 > %system.nullfile%

* Check the return code via if [not] errorlevel n
$if errorlevel 1 $abort expect a errorlevel <= 0

* Access the return code as function value of function errorLevel
$eval MYERRORLEVEL errorLevel
$log %MYERRORLEVEL%

* Runtime

* Example for non-zero return code
execute 'gams x.gms lo=0 this_causes_a_parameter_error_with_return_code_6=1 > %system.nullfile%';

* Access the return code as function value of function errorLevel
scalar myerrorlevel; 
myerrorlevel = errorlevel;
display 'should be 6:', myerrorlevel;

* Example for zero return code
execute 'gams x.gms lo=0 > %system.nullfile%';

* Access the return code as function value of function errorLevel
myerrorlevel = errorlevel;
display 'should be 0:', myerrorlevel;

Command line interpreters or shells are a powerful way for job control and can naturally also run GAMS jobs. Here are two examples that demonstrate how to access (actually echo) the return code from GAMS in such environments:

Unix shell (e.g. bash):

$ gams mymodel ...
$ echo $?

Here $? is the environment variable that stores the return code from the last run.

Windows (cmd.exe):

C:\tmp> gams mymodel ...
C:\tmp> echo %errorlevel%

Here %errorlevel% is the environment variable that stores the return code from the last run.

Note
On UNIX, return codes are treated modulo 256, so the return code 400 will be 144 on Unix. The return code modulo 256 is given in parenthesis in the table, if different from the return code.

List of the Error/Return Codes

The following table gives the list of the GAMS return codes:

Return Code Description
0 Normal return
1 Solver is to be called, the system should never return this number
2 There was a compilation error
3 There was an execution error
4 System limits were reached
5 There was a file error
6 There was a parameter error
7 There was a licensing error
8 There was a GAMS system error
9 GAMS could not be started
10 Out of memory
11 Out of disk
109 Could not create process/scratch directory
110 Too many process/scratch directories
112 Could not delete the process/scratch directory
113 Could not write the script gamsnext
114 Could not write the parameter file
400 (144) Could not spawn the GAMS language compiler (gamscmex)
401 (145) Current directory (curdir) does not exist
402 (146) Cannot set current directory (curdir)
404 (148) Blank in system directory (UNIX only)
405 (149) Blank in current directory (UNIX only)
406 (150) Blank in scratch extension (scrext)
407 (151) Unexpected cmexRC
408 (152) Could not find the process directory (procdir)
409 (153) CMEX library not be found (experimental)
410 (154) Entry point in CMEX library could not be found (experimental)
411 (155) Blank in process directory (UNIX only)
412 (156) Blank in scratch directory (UNIX only)
909 (141) Cannot add path / unknown UNIX environment / cannot set environment variable
1000 (232) Driver error: incorrect command line parameters for gams
2000 (208) Driver error: internal error: cannot install interrupt handler
3000 (184) Driver error: problems getting current directory
4000 (160) Driver error: internal error: GAMS compile and execute module not found
5000 (126) Driver error: internal error: cannot load option handling library

Note that error 3000 is sometimes caused by specifying the current directory in Microsoft UNC format. The return codes smaller than 100 come from the GAMS compiler and execution system (gamscmex) while the codes above 100 come from the GAMS driver program (gams).