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] ( 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:

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