GAMS [ Home | Downloads | Documentation | Solvers | APIs | Tools | Model Libraries | Resources | Sales | Support | Contact Us | Search ]

Dollar Control Options

Introduction

The Dollar Control Options are used to indicated compiler directives and options. Dollar control options are not part of the GAMS language and must be entered on separate lines recognized by a $ symbol in the first column. A dollar control option line may be placed anywhere within a GAMS program and it is processed during the compilation of the program. The $ symbol is followed by one or more options identified by spaced. Since the dollar control options are not part of the GAMS language, they do not appear on the compiler listing unless an error had been detected. Dollar control option lines are not case sensitive and a continued compilation uses the previous settings.

Syntax

In general, the syntax in GAMS for dollar control options is as follows,

$option_name argument_list {option_name argument_list}

where option_name is the name of the dollar control option, while argument_list is the list of arguments for the option. Depending on the particular option, the number of arguments required can vary from 0 to many.

Attention
  • No blank space is permitted between the $ character and the first option that follows.
  • In most cases, multiple dollar control options can be processed on a line. However, some dollar control options require that they be the first option on a line.
  • The effect of the dollar control option is felt immediately after the option is processed.

An example of a list of dollar control options is shown below,

$title Example to illustrate dollar control options
$onsymxref onsymlist

Note that there is no blank space between the $ character and the option that follows. The first dollar control option $title sets the title of the pages in the listing file to the text that follows the option name. In the second line of the example above, two options are set - $onsymxref and $onsymlist. Both these options turn of the echoing of the symbol reference table and listings to the listing file.

List of Dollar Control Options

The Dollar Control Options are grouped into nine major functional categories affecting

  • input comment format
  • input data format
  • output format
  • reference maps
  • program control
  • GDX operations
  • environment variables
  • macro definitions
  • Compression and encrypting

The following subsections briefly describe the various options in each of the categories. Section Detailed Description of Dollar Control Options contains a reference list of all dollar control options in alphabetical order with detailed description for each.

Non-default settings are reported before the file summary at the end of a GAMS listing as a reminder for future continued compilations. This is only relevant if a restart file has been requested with the GAMS call.

Options affecting input comment format

Option Description
comment set the comment character
eolCom set end-of-line comment character
inlinecom set in line comment character
maxCol set right hand margin of input file
minCol set left hand margin of input file
offEolCom turn off end-of-line comments
offInline turn off in-line comments
offMargin turn off margin marking
offNestComturn off nested comments
offText off text mode
onEolCom turn on end-of-line comments
onInline turn on in-line comments
onMargin turn on margin marking
onNestCom turn on nested comments
onText on text – following lines are comments

Options affecting input data format

Option Description
dollar set the dollar character
offDelim delimited data statement syntax off
offDigit off number precision check
offEmbedded no embedded text or data allowed
offEmpty disallow empty data initialization statements
offEnd disallow alternate program control syntax
offEps disallow interpretation of EPS as 0
offGlobal disallow inheritance of parent file settings
offUNDF do not allow UNDF as input
offWarning do not convert domain errors into warnings
onDelim delimited data statement syntax on
onDigit on number precision check
onEmbedded allow embedded text or data in set and parameter statements
onEmpty allow empty data initialization statements
onEnd allow alternate program control syntax
onEps interpret EPS as 0
onGlobal force inheritance of parent file settings
onUNDF allow UNDF as input
onWarning convert certain domain errors into warnings
use205 Release 2.05 language syntax
use225 Release 2.25 Version 1 language syntax
use999 latest language syntax
version test GAMS compiler version number

Options affecting output format

Option Description
double double-spaced listing follows
echo echo text
echoN echo a string to a file without ending the line
eject advance to next page
hidden ignore text and do not list
lines next number of lines have to fit on page
log send message to the log
offDollar turn the listing of Dollar Control Option lines off
offEcho end of block echo
offInclude turn off listing of include file names
offListing turn off echoing input lines to listing file
offLog turn off line logging
offPut end of block put
offVerbatim stop verbatim copy
onDollar turn the listing of Dollar Control Option lines on
onEcho start of block echo with substitution
onEchoS start of block echo with substitution
onEchoV start of block echo without substitution
onInclude include file name echoed to listing file
onListing input lines echoed to listing file
onLog reset line logging
onPut start of block put without substitution
onPutS start of block put with substitution
onPutV start of block put without substitution
onVerbatim start verbatim copy if dumpopt \(\geq\) 10
remark comment line with suppressed line number
single single-spaced listing follows
stars set "****" characters in listing file
sTitle set subtitle and reset page
title set title, reset subtitle and page

Options affecting listing of reference maps

Option Description
offSymList off symbol list
offSymXRef off symbol cross reference listing
offUElList off unique element listing
offUElXRef off unique element cross reference
onSymList on symbol list
onSymXRef on symbol cross reference listing
onUElList on unique element listing
onUElXRef on unique element cross listing

Options affecting program control

Option Description
abort issue an error message and abort compilation
batInclude include file with substitution arguments
call executes program during compilation
call.Async executes another program asynchronously
clear reset all data for an identifier to its default values
clearError clear compilation errors
clearErrors clear compilation errors
else else clause
elseIf elseIf structure with case sensitive compare
elseIfE elseIf structure with expression evaluation
elseIfI elseIf structure with case insensitive compare
endif closing of ifThen/ifThenE/ifThenI control structure
error issue an error message
exit exit from compilation
funcLibIn load extrinsic function library
goto go to line with given label name
hiddenCall executes another program (hidden)
if conditional processing, case sensitive
ifE if statement with expression evaluation
ifI conditional processing, case insensitive
ifThen ifThen-elseIf structure with case sensitive compare
ifThenE ifThen-elseIf structure with expression evaluation
ifThenI ifThen-elseIf structure with case insensitive compare
include include file
kill kill data connected with identifier
label label name as entry point from $goto
libInclude include file from library directory
offGlobal turns off global options
offMulti turns off redefinition of data
offOrder allow lag and lead operations on dynamic or unordered sets
offRecurse disable recursive include files
offStrictSingleton take first record if data statement for singleton set has multiple elements
onGlobal turns on global options
onMulti turn on redefinition of data
onOrder lag and lead operations on constant and ordered sets only
onRecurse enable recursive include files
onStrictSingleton error if data statement for singleton set has multiple elements
maxGoto maximum number of jumps to the same label
phantom defines a phantom element
shift DOS shift operation
stop stop compilation
sysInclude include file from system directory
terminate terminate compilation and execution
warning issue compilation warning

GDX operations

Option Description
gdxIn open GDX file for input
gdxOut open GDX file for output
load load symbols from GDX file - domain filtered
loadDC load symbols from GDX file - domain checked
loadDCM Load symbols from GDX file - domain checked - merge
loadDCR load symbols from GDX file - domain checked - replace
loadM load symbols from GDX file - domain filtered - merge
loadR load symbols from GDX file - domain filtered - replace
unload unload symbols into GDX file

Environment variables

Option Description
drop drop a scoped environment variable
dropEnv drop an OS environment variable
dropGlobal drop a global environment variable
dropLocal drop a local environment variable
escape define the % escape symbol
eval evaluates and defines a scoped environment variable
evalLocal evaluates and defines a local environment variable
evalGlobal evaluates and defines a global environment variable
prefixPath prefix the path environment variable
set define a scoped environment variable
setArgs define local environment variables using argument list
setComps unpack dotted names into local variables
setDDList check double dash GAMS parameters
setEnv define an OS environment variable
setGlobal define a global environment variable
setLocal define a local environment variable
setNames unpack a filename into local environment variables
show show current GAMS environment variables
splitOption unpack a key/value pair into local environment variables

Macro definitions

Option Description
macro preprocessing macro definition
offDotL do not assume .l for variables in assignments
offExpand do not expand macros when processing macro arguments
offLocal limit .local nesting to one
offMacro do not recognize macros for expansion
onDotL assume .l for variables in assignments
onExpand expand macros when processing macro arguments
onLocal no limit on .local nesting
onMacro recognize macros for expansion

Compression and encrypting of source files

Option Description
compress create compressed GAMS system file
decompress decompress a GAMS system file
encrypt create encrypted GAMS system file
expose remove all access control restrictions
hide hide objects from user
protect protect objects from user modification
purge remove the objects and all associated data

Detailed Description of Dollar Control Options

This section describes each of the dollar control options in detail. The dollar control options are listed in alphabetical order for easy reference. In each of the following dollar control options, the default value, if available, is bracketed.

abort

This option will issue a compilation error and abort the compilation.

Consider the following example,

$if not %system.filesys% == UNIX
$abort We only do UNIX

This attempts to stop compilation if the operating system is not Unix. Running the above example on a non-Unix platform results in the compilation being aborted, and the following listing file,

    2  $abort We only do UNIX
****        $343

Error Messages
343  Abort triggered by above statement

batinclude

The $batinclude facility performs the same task as the $include facility in that it inserts the contents of the specified text file at the location of the call. In addition, however, it also passes on arguments which can be used inside the include file:

$batinclude file arg1 arg2 ...

The $batinclude option can appear in any place the $include option can appear. The name of the batch include file may be quoted or unquoted, while arg1, arg2,.. are arguments that are passed on to the batch include file. These arguments are treated as character strings that are substituted by number inside the included file. These arguments can be single unbroken strings (quoted or unquoted) or quoted multi-part strings.

The syntax has been modeled after the DOS batch facility. Inside the batch file, a parameter substitution is indicated by using the character % followed immediately by an integer value corresponding to the order of parameters on the list where %1 refers to the first argument, %2 to the second argument, and so on. If the integer value is specified that does not correspond to a passed parameter, then the parameter flag is substituted with a null string. The parameter flag %0 is a special case that will substitute a fully expanded file name specification of the current batch included file. The flag %$ is the current $ symbol (see $dollar). Parameters are substituted independent of context, and the entire line is processed before it is passed to the compiler. The exception to this is that parameter flags appearing in comments are not substituted.

Attention
  • GAMS requires that processing the substitutions must result in a line of less than or equal to the maximum input line length (currently 255 characters).
  • The case of the passed parameters is preserved for use in string comparisons.

Consider the following slice of code,

$batinclude "file1.inc" abcd "bbbb" "cccc dddd"

In this case, file1.inc is included with abcd as the first parameter, bbbb as the second parameter, and cccc dddd as the third parameter.

Consider the following slice of code,

parameter a,b,c ;
a = 1 ; b = 0 ; c = 2 ;
$batinclude inc2.inc b a
display b ;
$batinclude inc2.inc b c
display b ;
$batinclude inc2.inc b "a+5"
display b ;

where inc2.inc contains the following line,

%1 = sqr(%2) - %2 ;

the listing file that results is as follows,

 1  parameter a,b,c ;
 2  a = 1 ; b = 0 ; c = 2 ;
BATINCLUDE D:\GAMS\INC2.INC
 4  b = sqr(a) - a ;
 5  display b ;
BATINCLUDE D:\GAMS\INC2.INC
 7  b = sqr(c) - c ;
 8  display b ;
BATINCLUDE D:\GAMS\INC2.INC
 10  b = sqr(a+5) - a+5 ;
 11  display b ;

Note that the three calls to $batinclude with the various arguments lead to GAMS interpreting the contents of batch include file in turn as

b = sqr(a) - a ;
b = sqr(c) - c ;
b = sqr(a+5) - a+5 ;

Note that third call is not interpreted as sqr(a+5)-(a+5), but instead as sqr(a+5)-a+5. The results of the display statement are shown at the end of the listing file,

----      5 PARAMETER B                    =        0.000
----      8 PARAMETER B                    =        2.000
----     11 PARAMETER B                    =       40.000

The third call leads to b = sqr(6)-1+5 which results in b taking a value of 40. If the statement in the batch include file was modified to read as follows,

%1 = sqr(%2) - (%2) ;

the results of the display statement in the listing file would read,

----      5 PARAMETER B                    =        0.000
----      8 PARAMETER B                    =        2.000
----     11 PARAMETER B                    =       30.000

The third call leads to b = sqr(6)-6 which results in b taking a value of 30.

Attention
A $batinclude call without any arguments is equivalent to a $include call.

call

Passes a followed string command to the current operating system command processor and interrupts compilation until the command has been completed. If the command string is empty or omitted, a new interactive command processor will be loaded.

Consider the following slice of code,

$call 'dir'

This command makes a directory listing on a PC.

The command string can be passed to the system and executed directly without using a command processor by prefixing the command with an '=' sign. Compilation errors are issued if the command or the command processor cannot be loaded and executed properly.

$call 'gams trnsport'
$call '=gams trnsport'

The first call runs [TRNSPORT] in a new command shell. The DOS command shell does not send any return codes from the run back to GAMS. Therefore any errors in the run are not reported back. The second call, however, sends the command directly to the system. The return codes from the system are intercepted correctly and available to the GAMS system through the errorlevel DOS batch function.

Attention
Some commands (like copy on a PC and cd in Unix) are shell commands and cannot be spawned off to the system. Using these in a system call will create a compilation error.

Consider the following slice of code,

$call 'copy myfile.txt mycopy.txt'
$call '=copy myfile.txt mycopy.txt'

The first call will work on a PC, but the second will not. The copy command can only be used from a command line shell. The system is not aware of this command (Try this command after clicking Run under the Start menu in Windows. You will find that it does not work).

call.Async

Works like $call but allows asynchronous job handling. This means you can start a job without waiting for the result. You can continue in your model and collect the return code of the job later. 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) an 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.

clear

This option resets all data for an identifier to its default values:

$clear id1 id2 ...

id1, id2, ... are the identifiers whose data is being reset. Note that this is carried out during compile time, and not when the GAMS program executes. Not all data types can be cleared - only set, parameter, equation and variable types can be reset.

Consider the following example,

set i /1*20/ ; scalar a /2/ ;
$clear i a
display i, a ;

The $clear option resets i and a to their default values. The result of the display statement in the listing file shows that i is now an empty set, and a takes a value of 0.

----      3 SET       I
                      (EMPTY)
----      3 PARAMETER A                    =        0.000
Attention
The two-pass processing of a GAMS file can lead to seemingly unexpected results. Both the dollar control options and the data initialization is done in the first pass, and assignments in the second, irrespective of their relative locations. This is an issue particularly with $clear since data can be both initialized and assigned.

Consider the following example,

scalar a /12/ ;
a=5;
$clear a
display a ;

The scalar data initialization statement is processed during compilation and the assignment statement a=5 during execution. In the order that it is processed, the example above is read by GAMS as,

* compilation step
scalar a /12/ ;
$clear a
* execution step
a=5;
display a ;

The example results in a taking a value of 5. The display statement in the resulting listing file is as follows,

----      4 PARAMETER A                    =        5.000

clearError(s)

$clearError and $clearErrors clear GAMS awareness of compiler errors. Consider the following example,

scalar z /11/;
$eval x sqrt(-1)
$clearerror
$log %x%
display z;

Without the use of $clearerror(s) the programm would not continue with the execution.

comment   (*)

This option changes the start-of-line comment to a single character which follows immediately the $comment keyword. This should be used with great care, and one should reset it quickly to the default symbol *.

Attention
The case of the start-of-line comment character does not matter when being used.

Consider the following example,

$comment c
c now we use a FORTRAN style comment symbol
$comment *
* now we are back how it should be

compress

Causes a file to be compressed into a packed file. The syntax is $compress source target where source is the name of the source file to be compressed and target is the name for the resultant compressed file. Consider the following example where the model library file [TRNSPORT] is used,

$call 'gamslib trnsport'
$compress trnsport.gms t2.gms
$include t2.gms

The first command retrieves the transport file and the second command compresses it. Then later the compressed file can be solved as it is treated like any other GAMS input file.

decompress

Causes a compressed file to be decompressed into an unpacked file. The syntax is $decompress source target where source is the name of the compressed file to be decompressed and target is the name for the resultant decompressed file. Consider the following example where the model library file [TRNSPORT] is used,

$call 'gamslib trnsport'
$compress trnsport.gms t2.gms
$decompress t2.gms t3.gms

The first command retrieves the transport file and the second command compresses it. The third command decompresses the compressed file and t3.gms is exactly the same as the original file trnsport.gms.

dollar   ($)

This option changes the current $ symbol to a single character which follows immediately the $dollar keyword. When a include file is inserted, all dollar control options are inherited, and the current $ symbol may not be known. The special %$ substitution symbol can be used to get the correct symbol (see $batinclude ).

Consider the following example,

$dollar #
#hidden now we can use # as the '$' symbol

double

The lines following the $double statement will be echoed double spaced to the listing file.

Consider the following example,

set i /1*2/ ;
scalar a /1/ ;
$double
set j /10*15/ ;
scalar b /2/ ;

The resulting listing file looks as follows,

1  set i /1*2/ ;
2  scalar a /1/ ;

4  set j /10*15/ ;

5  scalar b /2/ ;

Note that lines before the $double option are listed singly spaced, while the lines after the option are listed with double space.

drop

Destroys a variable that was defined with $set. The syntax is $drop varname.

dropEnv

Destroys an operating system envorinment variable. The syntax is $dropenv varname. For detailed infoemation check $setEnv.

dropGlobal

Destroys a variable that was defined with $setGlobal. The syntax is $dropGlobal varname.

dropLocal

Destroys a variable that was defined with $setLocal. The syntax is $dropLocal varname.

echo

The echo option allows to write text to a file:

$echo  'text' > file
$echo  'text' >> file

These options send the message 'text' to the file file. Both the text and the file name can be quoted or unquoted. The file name is expanded using the working directory. The $echo statement tries to minimize file operations by keeping the file open in anticipation of another $echo to be appended to the same file. The file will be closed at the end of the compilation or when a $call or any kind of $include statement is encountered. The redirection symbols > and >> have the usual meaning of starting at the beginning or appending to an existing file.

Consider the following example,

$echo                                                      > echo
$echo  The message written goes from the first non blank  >> echo
$echo 'to the first > or >> symbol unless the text is'    >> echo
$echo "is quoted. The Listing File is %gams.input%. The"  >> echo
$echo 'file name "echo" will be completed with'           >> echo
$echo  %gams.workdir%.                                    >> echo
$echo                                                     >> echo

The contents of the resulting file echo are as follows,

The message written goes from the first non blank
to the first > or >> symbol unless the text is
is quoted. The Listing File is C:\PROGRAM FILES\GAMSIDE\CC.GMS. The
file name "echo" will be completed with
C:\PROGRAM FILES\GAMSIDE\.

echoN

Sends a text message to an external file like $echo but writes no end of line marker so the line is repeatedly appended to by subsequent commands. Consider the following example,

$echoN 'Text to be sent' > 'aaa'
$echoN 'More text' >> aaa
$echoN And more and more and more  >> aaa
$echo This was entered with $echo >> 'aaa'
$echo This too >> aaa

The created file aaa contains,

Text to be sentMore textAnd more and more and moreThis was entered with $echo
This too

The redirection symbols \(>\) and \(>>\) have the usual meaning of starting at the beginning or appending to an existing file.

Note that the text and the file name can be quoted or unquoted. By default the file name will go in the working directory.

eject

Advances the output to the next page.

Consider the following example,

$eject
Set i,j ;
Parameter data(i,j) ;
$eject

This will force the statements between the two $eject calls to be reported on a separated page in the listing file.

else

$else always appears together with an $ifThen[E/I] statement. It is followed by an instruction which is executed if the matching if statement is not true.

elseIf

$elseIf always appears together with an $ifThen[E/I] statement. It is followed by another condition and instruction.

elseIfE

$elseIfE does the same as $elseIf but evaluates numerical values of the control variables.

elseIfI

$elseIfI does the same as $elseIf but is case insensitive.

encrypt

Causes a file to be converted into an encrypted file. The syntax is $encrypt source target where source is the name of the source file to be encrypted and target is the name for the resulting encrypted file. Note that encryption requires a special GAMS license. The use of the Plicense parameter specifies the target license to be used as a user key for decrypting. This must be done with the same license as was used in encryption. Decryption is done when reading the GAMS system files. GAMS recognizes whether a file is compressed or encrypted and will process the files accordingly.

endIf

$endIf must be matched with an $ifThen, $ifThenE or $ifThenI.

eolcom (!!)

This option redefines the end-of-line comment symbol, which can be a one or two character sequence. By default the system is initialized to '!!' but not active. The $oneolcom option is used to activate the end-of-line comment. The $eolcom option sets $oneolcom automatically.

Consider the following example,

$eolcom ->
set i /1*2/ ;     -> set declaration
parameter a(i) ;  -> parameter declaration

The character set -> serves as the end-of-line-comment indicator.

Attention
GAMS requires that one does not reset the $eolcom option to the existing symbol.

The following code is illegal since $eolcom is being reset to the same symbol as it is currently,

$eolcom ->
$eolcom ->

error

This option will issue a compilation error and will continue with the next line.

Consider the following example,

$if not exist myfile
$error File myfile not found - will continue anyway

This checks if the file myfile exists, and if not, it will generate an error with the comment 'File not found - will continue anyway', and then compilation continues with the following line.

escape

Allows one to print out or display the text sequence for the % syntax. It is employed using the syntax $escape symbol. This renders all subsequent commands of the form %symbol to not have parameter substitution done for them and on display or in a put to come out as just a %. One may reverse this action with $escape %. Consider the following example,

$set tt DOIT

file it
put it

display "first %tt%";
display "second %&tt%&";
put "display one ", "%system.date%" /;
put "display two " "%&system.date%&"/;

$escape &
display "third %tt%";
display "fourth %&tt%&";
put "display third ", "%system.date%" /;
put "display fourth " "%&system.date%&"/;

$escape %
display "fifth %tt%";
display "sixth %&tt%&";
put "display fifth ", "%system.date%" /;
put "display sixth " "%&system.date%&"/;

The resulting listing file contains,

----      6 first DOIT

----      7 second %&tt%&

----     12 third DOIT

----     13 fourth %tt%

----     18 fifth DOIT

----     19 sixth %&tt%&

and it.put contains,

display one 08/10/11
display two %&system.date%&
display third 08/10/11
display fourth %system.date%
display fifth 08/10/11
display sixth %&system.date%&

This is really only present to allow one to be able to write GAMS instructions from GAMS as one would not be able to use a put to write the symbols %gams.ps% otherwise.

eval

$eval evaluates a numerical expression at compile time and places it into a scoped control variable. In turn one can use $if and $ife to do numeric testing on the value of this variable. The format is $eval varname expression where the expression must consist of constants, functions or other control variables with numerical values. No whitespace is allowed in the expression. For differences to $evalGlobal and $evalLocal consider the following example,

$evalGlobal Anumber 3**2+2
$evalLocal Bnumber abs(-22)
$eval Cnumber min(33,34)
$ife %Anumber%=11 display "Anumber equals 11"
$ife %Bnumber%=22 display "Bnumber equals 22"
$ife %Cnumber%=33 display "Cnumber equals 33"

$include test.gms

$if %Dnumber%==44 display "Dnumber equals 44"
$if NOT %Dnumber%==44 display "Dnumber does NOT equal 44"
$if %Enumber%==55 display "Enumber equals 55"
$if NOT %Enumber%==55 display "Enumber does NOT equal 55"
$if %Fnumber%==66 display "Fnumber equals 66"
$if NOT %Fnumber%==66 display "Fnumber does NOT equal 66"

where test.gms is

$if %Anumber%==11 display "Anumber equals 11 in test.gms"
$if NOT %Anumber%==11 display "Anumber does NOT equal 11 in test.gms"
$if %Bnumber%==22 display "Bnumber equals 22 in test.gms"
$if NOT %Bnumber%==22 display "Bnumber does NOT equal 22 in test.gms"
$if %Cnumber%==33 display "Cnumber equals 33 in test.gms"
$if NOT %Cnumber%==33 display "Cnumber does NOT equal 33 in test.gms"

$evalGlobal Dnumber 44
$evalLocal Enumber 55
$eval Fnumber 66

The resulting listing file contains,

----      4 Anumber equals 11

----      5 Bnumber equals 22

----      6 Cnumber equals 33

----      9 Anumber equals 11 in test.gms

----     12 Bnumber does NOT equal 22 in test.gms

----     13 Cnumber equals 33 in test.gms

----     20 Dnumber equals 44

----     23 Enumber does NOT equal 55

----     25 Fnumber does NOT equal 66

Note that GAMS allows one to define scoped, local and global variables with the same name and has to prioritize under some cases. Consider the following slice of code,

$evalglobal notunique 11
$evallocal notunique 22
$eval notunique 33
$log %notunique%

$log will echo 22, the current value of notunique, to the log file.

evalGlobal

$evalGlobal evaluates a numerical expression at compile time and places it into a global control variable. In turn one can use $if and $ife to do numeric testing on the value of this variable. The format is $evalGlobal varname expression where the expression must consist of constants, functions or other control variables with numerical values. No whitespace is allowed in the expression.

For differences to $eval and $evalLocal check the example in the description of $eval.

Note that GAMS allows one to define scoped, local and global variables with the same name and has to prioritize under some cases. Consider the following slice of code,

$evalglobal notunique 11
$evallocal notunique 22
$eval notunique 33
$log %notunique%

$log will echo 22, the current value of notunique, to the log file.

evalLocal

$evalLocal evaluates a numerical expression at compile time and places it into a local control variable. In turn one can use $if and $ife to do numeric testing on the value of this variable. The format is $evalLocal varname expression where the expression must consist of constants, functions or other control variables with numerical values. No whitespace is allowed in the expression.

For differences to $eval and $evalGlobal check the example in the description of $eval . Note that GAMS allows one to define scoped, local and global variables with the same name and has to prioritize under some cases. Consider the following slice of code,

$evalglobal notunique 11
$evallocal notunique 22
$eval notunique 33
$log %notunique%

$log will echo 22, the current value of notunique, to the log file.

exit

This option will cause the compiler to exit (stop reading) from the current file. This is equivalent to having reached the end of file.

Consider the following example,

scalar a ; a = 5 ;
display a ;
$exit
a = a+5 ; display a ;

The lines following the $exit will not be compiled.

Note that there is a difference to $stop. If you have only one input file $stop and $exit will do the same thing. If you are in an include file, $exit acts like an end-of file on the include file. However, if you encounter a $stop in an include file, GAMS will stop reading all input.

expose

removes all privacy restrictions from the named item or items. The syntax is

$expose item1 item2 ...

or

$expose all

In the first case the privacy restrictions are removed only for the listed items and in the second case they are removed for all items. One can set these privacy restrictions with $hide or $protect.

Note that a special license file is needed for this feature to work and that the expose only takes effect in subsequent restart files.

funcLibIn

Function libraries are made available to a model using the compiler directive:

$FuncLibIn <InternalLibName> <ExternalLibName>

Similar to sets, parameters, variables, and equations, functions must be declared before they can be used:

Function <InternalFuncName> /<InternalLibName>.<FuncName>/;

gdxIn

This dollar command is used in a sequence to load specified items from a GDX file. It is employed using the syntax $gdxIn filename where filename gives the name of the GDX file (with or without the extension GDX) and the command opens the specified GDX file for reading.

The next use of $gdxIn closes the specified GDX file. The command must be used in conjunction with the command $load .

gdxOut

This dollar command is used in a sequence to unload specified items from a GDX file. It is employed using the syntax $gdxOut filename where filename gives the name of the GDX file (with or without the extension GDX) and the command opens the specified GDX file for writing. The next use of $gdxOut closes the specified GDX file. The command must be used in conjunction with the command $unload.

goto    id

This option will cause GAMS to search for a line starting with '$label id' and then continue reading from there. This option can be used to skip over or repeat sections of the input files. In batch include files, the target labels or label arguments can be passed as parameters because of the manner in which parameter substitution occurs in such files. In order to avoid infinite loops, one can only jump a maximum of 100 times to the same label.

Consider the following example,

scalar a ; a = 5;
display a ;
$goto next
a = a+5 ; display a ;
$label next
a = a+10 ; display a ;

On reaching the $goto next option, GAMS continues from $label next. All lines in between are ignored. On running the example, a finally takes a value of 15.

Attention
The $goto and $label have to be in the same file. If the target label is not found in the current file, and error is issued.

hidden

This line will be ignored and will not be echoed to the listing file. This option is used to enter information only relevant to the person manipulating the file.

Consider the following example,

$hidden You need to edit the following lines if you want to:
$hidden
$hidden     1. Change form a to b
$hidden     2. Expand the set

The lines above serve as comments to the person who wrote the file. However, these comments will not be visible in the listing file, and are therefore hidden from view.

hiddenCall

$hiddenCall does the same as $call but makes sure that the statement is neither shown on the log nor the listing file.

hide

hides the named items so they cannot be displayed or computed but still allows them to be used in model calculations (.. commands when the solve statement is executed). The syntax is

$hide item1 item2 ...

or

$hide all

In the first case the listed items are hidden and in the second case all items are hidden. These restrictions can be removed with $expose or $purge.

Note that special license file is needed for this feature to work.

if

The $if dollar control option provides the greatest amount of control over conditional processing of the input file(s). The syntax is similar to the IF statement of the DOS Batch language:

  $if [not] <conditional expression> new_input_line

The syntax allows for negating the conditional with a not operator followed by a conditional expressions. The <conditional expression> can be: acrtype, decla_ok, declared, defined, dexist, dimension, equtype, errorfree, errorlevel, eval, evalglobal, evallocal, exist, filtype, funtype, gamsversion, mactype, modtype, partype, pretype, protype, putopen, readable, set, setenv, setglobal, setlocal, settype, solver, vartype, warnings, xxxtype, as well as, a string comparison.

The result of the conditional test is used to determine whether to read the remainder of the line, which can be any valid GAMS input line.

New_input_line is the remainder of the line containing the $if option, and could be any valid GAMS input line.

Attention
The first non-blank character on the line following the conditional expression is considered to be the first column position of the GAMS input line. Therefore, if the first character encountered is a comment character the rest of the line is treated as a comment line. Likewise if the first character encountered is the dollar control character, the line is treated as a dollar control line.

An alternative to placing new_input_line on the same line as the conditional is to leave the remainder of the line blank and place new_input_line on the line immediately following the if line. If the conditional is found to be false, either the remainder of the line (if any) is skipped or the next line is not read.

In the following some of the alternatives are explained in more detail:

The exist file operator can be used to check for the existence of the given file name specification. The string compare consists of two strings (quoted or unquoted) for which the comparison result is true only if the strings match exactly. Null (empty) strings can be indicated by an empty quote: ""

Attention
  • The case of the strings provided either explicitly or, more likely, through a parameter substitution, is preserved and therefore will effect the string comparison.
  • Quoted strings with leading and trailing blanks are not trimmed and the blanks are considered part of the string.
  • If the string to be compared is a possibly empty parameter, the parameter operator must be quoted.

Consider the following example,

$if exist myfile.dat $include myfile.dat

The statement above includes the file myfile.dat if the file exists. Note that the $ character at the beginning of the $include option is the first non-blank character after the conditional expression, if exist myfile.dat and is therefore treated as the first column position. The above statement can also be written as

$if exist myfile.dat
$include myfile.dat

Consider the following additional examples,

$if not "%1a" == a $goto labelname
$if not exist "%1" display "file %1 not found" ;

The first statement illustrates the use of the $if option inside a batch include file where parameters are passed through the $batinclude call from the parent file. The $if condition checks if the parameter is empty, and if not processes the $goto option. Note that the string comparison attempted, "\%1a" == a, can also be done using %1 == "".

The second statement illustrates using standard GAMS statements if the conditional is valid. If the file name passed as a parameter through the $batinclude call does not exist, the GAMS display statement is processed.

Attention
In line and end of line comments are stripped out of the input file before processing for new_input_line. If either of these forms of comments appears, it will be treated as blanks.

Consider the following example,

parameter a ; a=10 ;
$eolcom ! inlinecom /*  */
$if exist myfile.dat  /* in line comments */  ! end of line comments
a = 4 ;
display a;

The comments on line 3 is ignored and the fourth line involving an assignment setting a to 4 will be treated as the result of the conditional. So the result of the display statement would be the listing of a with a value of 4 if the file myfile.dat exists, and a value of 10 if the file does not exist.

Attention
It is suggested that a $label not appear as part of the conditional input line. The result is that if the $label appears on the $if line, a $goto to this label will re-scan the entire line thus causing a reevaluation of the conditional expression. On the other hand, if the $label appears on the next line, the condition will not be reevaluated on subsequent gotos to the label.

The following example illustrates how an unknown number of file specifications can be passed on to a batch include file that will include each of them if they exist. The batch include file could look as follows,

/* Batch Include File - inclproc.bch */
/* Process and INCLUDE an unknown number of input files */
$label nextfile
$if "%1a" == a  $goto end
$if exist "%1"  $include "%1"    /* name might have blanks */
$shift  goto nextfile
$label end

The call to this file in the parent file could look like:

$batinclude inclproc.bch  fil1.inc  fil2.inc  fil3.inc fil4.inc

The following example illustrates how to perform a errorlevel test.

$if errorlevel 1 $abort one or more errors encountered

The errorlevel is retrieved from the previous system call, i.e. $call statement. The conditional statement "errorlevel 1" is true ,if the returned errorlevel is >=1 and, if so, the GAMS program is aborted immediately at compilation time.

The next example shows how to test if a named item is defined.

set i /seattle/;
$if defined i $log set i is defined

The conditional expression "defined i" is true because a label, namely seattle, has been defined in set i.

The following example illustrates how to check if a solver exists.

$if solver badname

The conditional expression is false because no solver named badname exists in the GAMS System.

ifE

The $ifE dollar control option does the same as $if but allows constant expression evaluation. There are two different forms of that statement.

$ife  expr1 == expr2   true if (expr1-expr2)/(1+abs(expr2)) < 1e-12
$ife  expr             true if expr1 <> 0

Consider the following example,

scalar a;
$ife (log2(16)^2)=16  a=0; display a;
$ife log2(16)^2 == 16  a=1; display a;
$ife NOT round(log2(16)^2-16)  a=2; display a;
$ife round(log2(16)^2-16)  a=3; display a;
$ife round(log2(16)^2-17)  a=4; display a;

This will create the following ouput,

----      2 PARAMETER a                    =        1.000

----      3 PARAMETER a                    =        2.000

----      5 PARAMETER a                    =        4.000

ifI

$ifI statement is working like the $if statement. The only difference is that $if makes comparisons involving text in a case sensitive fashion while $ifI is case insensitive.

ifThen

is a form of an $if that controls whether a number of statements are active. The syntax for the condition is generally the same as for the $if statement. The $ifThen and $elseIf have a few variants and attributes that should be mentioned:

  • $ifThen is used to do case sensitive comparisons. It must be matched with an $endIf.
  • $ifThenE is used to do numerical comparisons. It must be matched with an $endIf.
  • $ifThenI is used to do case insensitive comparisons. It must be matched with an $endIf.
  • $endIf must be matched with an $ifThen, $ifThenE, or $ifThenI.
  • $else is followed by an instruction which is executed if the matching $ifThen statement is not true.
  • $elseIf has another comparison behind it.
  • $elseIfI is a case insensitive variant of $elseIf.
  • $elseIfE is a numerical value evaluating variant of $elseIf.
  • The statements following directly an $ifThen, $elseIf or $else on the same line can be a sequence of other dollar control statements or contain proper GAMS syntax. The statements following directly a $endIf can only contain another dollar control statement.
  • A NOT may be used in the commands.
  • One may add a tag to the $ifThen and $endIf. Then for example $ifThen.tagone has to match with $endif.tagone as shown below.

Consider the following example which illustrates the use of $ifThen and $elseIf.

$set x a
$label two
$ifthen %x% == a $set x 'c' $log $ifthen   with x=%x%
$elseif %x% == b $set x 'k' $log $elseif 1 with x=%x%
$elseif %x% == c $set x 'b' $log $elseif 2 with x=%x%
$else            $set x 'e' $log $else     with x=%x%
$endif $if NOT %x% == e $goto two

the resulting log file contains

$ifthen   with x=a
$elseif 2 with x=c
$elseif 1 with x=b
$else     with x=k

The next examples illustrates the use of tags

$ifThen.one x == y
display "it1";
$elseIf.one a == a
display "it2";
$ifThen.two c == c
display "it3";
$endIf.two
$elseIf.one b == b
display "it4";
$endIf.one

The resulting listing file contains

----      2 it2

----      4 it3

because the first condition (x == y) is obviously not true and the fourth condition (b == b) is not tested because the second one (a == a) was already true.

ifThenE

$ifThenE does the same as $ifThen but evaluates numerical values of the control variables.

ifThenI

$ifThenI does the same as $ifThen but is case insensitive.

include

The $include option inserts the contents of a specified text file at the location of the call. The name of the file to be included which follows immediately the keyword include may be quoted or unquoted. Include files can be nested.

The include file names are processed in the same way as the input file is handled. The names are expanded using the working directory. If the file cannot be found and no extension is given, the standard GAMS input extension is tried. However, if an incomplete path is given, the file name is completed using the include directory. By default, the library include directory is set to the working directory. The default directory can be reset with the idir command line parameter.

The start of the include file is marked in the compiler listing. This reference to the include file can be omitted by using the $offinclude option.

The following example illustrates the use of an include statement,

$include myfile
$include "myfile"

Both statements above are equivalent, and the search order for the include file is as follows:

  1. myfile in current working directory
  2. myfile.gms in current working directory
  3. myfile and myfile.gms (in that order) in directories specified by idir parameter.
Attention
The current settings of the dollar control options are passed on to the lower level include files. However, the dollar control options set in the lower level include file are passed on to the parent file only if the $onglobal option is set.

Compiler errors in include files have additional information about the name of the include file and the local line number.

At the end of the compiler listing, an include file summary shows the context and type of include files. The line number where an include file has been called is given. For example, in the Include File Summary below we see that:

SEQ   GLOBAL TYPE      PARENT   LOCAL   FILENAME

1          1 INPUT          0       0   C:\TEST\TEST1.GMS
2          1 INCLUDE        1       1  .C:\TEST\FILE1.INC
3          6 INCLUDE        1       4  .C:\TEST\FILE2.INC

The first column named SEQ gives the sequence number of the input files encountered. The first row always refers the parent file called by the GAMS call. The second column named GLOBAL gives the global (expanded) line number which contained the $include statement. The third column named TYPE refers to the type of file being referenced. The various types of files are INPUT, INCLUDE, BATINCLUDE, LIBINCLUDE, and SYSINCLUDE. The fourth column named PARENT provides the sequence number of the parent file for the file being referenced. The fifth column named LOCAL gives the local line number in the parent file where the $include appeared. In the example listed above, the include files file1.inc and file2.inc were included on lines 1 and 4 of the parent file test1.gms.

inlinecom ( \(/* ~~ */\))

This option redefines the in-line comment symbols, which are a pair of one or two character sequence. By default, the system is initialized to ' \(/*\)' and ' \(*/\)', but is not active. The $oninline option is used to activate the in-line comments. The $inlinecom option sets the $oninline automatically.

Consider the following example,

$inlinecom {{ }}
set {{ this is an inline comment }} i /1*2/ ;

The character pair {{ }} serves as the indicator for in-line comments.

Attention
GAMS requires that one not reset the $inlinecom option to an existing symbol.

The following code is illegal since $inlinecom is being reset to the same symbol as it is currently,

$inlinecom {{  }}
$inlinecom {{  }}
Attention
The $onnestcom enables the use of nested comments.

kill

Removes all data for an identifier and resets the identifier, only the type and dimension are retained. Note that this is carried out during compile time, and not when the GAMS program executes. Not all data types can be killed - only set, parameter, equation and variable types can be reset.

Consider the following example,

set i / 1*20 /; scalar a /2/
$kill i a

Note that this is different from $clear in the case that after setting $kill, i and a are treated as though they have been only defined and have not been initialized or assigned. The result of the $kill statement above is equivalent to i and a being defined as follows,

set i ; scalar a ;

Unlike the $clear, a display statement for i and a after they are killed will trigger an error.

label    id

This option marks a line to be jumped to by a $goto statement. Any number of labels can be used in files and not all of them need to be referenced. Re-declaration of a label identifier will not generate an error, and only the first occurrence encountered by the GAMS compiler will be used for future $goto references.

Consider the following example,

scalar a ; a = 5 ;
display a ;
$goto next
a = a+5 ; display a ;
$label next
a = a+10 ; display a ;

On reaching the $goto next option, GAMS continues from $label next. All lines in between are ignored. On running the example, a finally takes a value of 15.

Attention
The $label statement has to be the first dollar control option of multiple dollar control options that appear on the same line.

libinclude

Equivalent to $batinclude:

$libinclude file arg1 arg2 ...

However, if an incomplete path is given, the file name is completed using the library include directory. By default, the library include directory is set to the inclib directory in the GAMS system directory. The default directory can be reset with the ldir command line parameter.

Consider the following example,

$libinclude abc x y

This call first looks for the include file [GAMS System Directory]/inclib/abc, and if this file does not exist, GAMS looks for the file [GAMS System Directory]/inclib/abc.gms. The arguments x and y are passed on to the include file to interpret as explained for the $batinclude option.

Consider the following example,

$libinclude c:\abc\myinc.inc x y

This call first looks specifically for the include file c:\abc\myfile.inc. The arguments x and y are passed on to the include file to interpret as explained for the $batinclude option.

lines    n

This option starts a new page in the listing file if less than n lines are available on the current page.

Consider the following example,

$hidden Never split the first few lines of the following table
$lines 5
table io(i,j) Transaction matrix

This will ensure that if there are less than five lines available on the current page in the listing file before the next statement (in this case, the table statement) is echoed to it, the contents of this statement are echoed to a new page.

load

This dollar command loads specified items from a GDX file. It is employed using the syntax $load item1 item2 ... but must be used in conjunction with the command $gdxIn.

  • $load must be preceded and succeeded by a $gdxIn. The preceding $gdxIn specifies the GDX file name and opens the file. The succeeding $gdxIn closes the file. More than one $load can appear in between.
  • When $load is not followed by arguments this causes a listing of the GDX file contents to be generated.
  • If the same symbol names as in the underlying GDX file should be used, the symbols are listed as arguments after $load, e.g. $load i j.
  • Symbols can also be loaded with a new name, e.g. $load i_new=i j_new=j.
  • The universal set can be loaded using $load uni=*.

Consider the following example, where transsol is the GDX file of the model [TRNSPORT] which can be found in the GAMS Model Library.

$gdxin transsol
Sets i, jj, uni;
$load i jj=j
Parameters a(i), bb(jj);
$load a
$load bb=b
Scalar f;
$load f uni=*
$gdxin
display i, jj, a, bb, f, uni;

The resulting listing file contains,

----     11 SET i  canning plants

seattle  ,    san-diego


----     11 SET jj  markets

new-york,    chicago ,    topeka


----     11 PARAMETER a  capacity of plant i in cases

seattle   350.000,    san-diego 600.000


----     11 PARAMETER bb  demand at market j in cases

new-york 325.000,    chicago  300.000,    topeka   275.000


----     11 PARAMETER f                    =       90.000  freight in dollars pe
                                                           r case per thousand m
                                                           iles

----     11 SET uni  Universe

seattle  ,    san-diego,    new-york ,    chicago  ,    topeka

loadDC

$loadDC is an alternative form of $load but checks to see if the set element names being loaded are in the associated sets (i.e. checks the domain). Any domain violations will be reported and flagged as compilation errors. All other features are the same as discussed under $load .

Consider the following example where transsol is the GDX file of the model [TRNSPORT] which can be found in the GAMS Model Library

set i,j;
parameter b(i),a(j);
$gdxin transsol
$load i b
$loadDC j a
$gdxin transsol

Note that in transsol a depends on i and b depends on j in contrast to this example. While $load i b works and b is just empty after that line $loadDC j a triggers a domain violation error because in transsol a depends on i.

loadDCM

$loadDCM does the same as $loadM plus domain checking like $loadDC .

loadDCR

$loadDCR does the same as $loadR plus domain checking like $loadDC.

loadM

$loadM is an alternative form of $load. Instead of replacing an item or causing a domain violation error if the item was already initialized it merges the contents. Consider the following example where transsol is the GDX file of the model [TRNSPORT] which can be found in the GAMS Model Library.

set j /1*5/;
$gdxin transsol
$loadm j
display j;
$gdxin transsol

The resulting listing file contains

----      4 SET j  markets

1       ,    2       ,    3       ,    4       ,    5       ,    new-york
chicago ,    topeka

loadR

$loadR item1 item2 ... will replace the parameters or sets item1 item2 ... by the data stored in the current GDX file. It must be used in conjunction with the command $gdxIn. Consider the following example, where transsol is the GDX file of the model [TRNSPORT] which can be found in the GAMS Model Library.

sets    i   / 1*3 /
    j   / 1*2 /;
$gdxin transsol
$loadr i j
$gdxin
display i,j;

The resulting listing file contains,

----      6 SET i  canning plants

seattle  ,    san-diego


----      6 SET j  markets

new-york,    chicago ,    topeka

log

This option will send a message to the log file. By default, the log file is the console. The default log file can be reset with the lo and lf command line parameters.

Attention
  • Leading blanks are ignored when the text is written out to the log file using the $log option.
  • All special % symbols will be substituted out before the text passed through the $log option is sent to the log file.

Consider the following example,

$log
$log       The following message will be written to the log file
$log  with leading blanks ignored. All special % symbols will
$log  be substituted out before this text is sent to the log file.
$log  This was line %system.incline% of file %system.incname%
$log

The log file that results by running the lines above looks as follows,

--- Starting compilation
--- CC.GMS(0) 138 Kb

The following message will be written to the log file
with leading blanks ignored. All special `%` symbols will
be substituted out before this text is sent to the log file.
This was line 5 of file C:\PROGRAM FILES\GAMSIDE\CC.GMS

--- CC.GMS(7) 138 Kb
--- Starting execution - empty program
*** Status: Normal completion

Note that %system.incline% has been replaced by 5 which is the line number where the string replacement was requested. Also note that %system.incname% has been substituted by the name of the file completed with the absolute path. Also note that the leading blanks on the second line of the example are ignored.

macro

GAMS includes the ability to define macros as of version 22.9. The definition takes the form $macro name(arg1,arg2,arg3,...) body where name is the name of the macro which has to be unique, arg1,arg2,arg3,... are the arguments and body defines what the macro should do. Consider the following example,

scalar x1 /2/, x2 /3/, y;

$macro oneoverit(y) 1/y
y = oneoverit(x1);
display y;

$macro ratio(a,b) a/b
y = ratio(x2,x1);
display y;

The resulting listing file contains,

----      5 PARAMETER y                    =        0.500

----      9 PARAMETER y                    =        1.500

Macros can also be included within macros,

$macro product(a,b) a*b
$macro addup(i,x,z) sum(i,product(x(i),z))

when called with

z = addup(j,a1,x1);

will expand into:

z = sum(j,a1(j)*x1);

The recognition of macros and expansion of arguments can be more carefully controlled by the use of ampersands (&) in the macro body. Ordinarily the macro will only substitute for full words thus the macro group

$macro  f(i)  sum(j, x(i,j))
$macro equh(q)  equation equ_q(i); equ_q(i).. q =e= 0;
equh(f(i))

which would expand to become

equation equ_q(i); equ_q(i).. sum(j, x(i,j)) =e= 0;

Note this contains q in a number of other places. If one wished to replace some of them as well one could use

$macro  f2(r,i)  sum(j, r(i,j))
$macro equ2(z,d,q)  equation equ2_&z&d; equ2_&z&d.. z*q =e= 0;
equ2(1,(i),f2(x,i))
equ2(2,(k),f2(r,k))

which would expand to become

equation equ2_1(i); equ2_1(i).. 1*sum(j, x(i,j)) =e= 0;
equation equ2_2(k); equ2_2(k).. 2*sum(j, r(k,j)) =e= 0;

where the &z and &d are replaced.

One can also include expressions with spaces, commas and unbalanced parentheses using && which includes an expression removing the outer set of quotes.

$macro d(q) display &&q;
$macro ss(q) &&q)
d('"hereit is" , i,k')
d('"(zz"')
z=ss('sum(j,a1(j)');
z=ss('prod(j,a1(j)');

Note that the d expressions contain quotes, spaces and commas and the ss expression has unbalanced parentheses within the quoted parts. In turn these expand to become

display "hereit is" , i,k;
display "(zz";
z=sum(j,a1(j));
z=prod(j,a1(j));

Nested macro use can result in an expansion of infinite length. For example:

$macro a  b,a
display a;

will expand into:

display b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,...

Another feature of macros is the implicit use of the .L suffix in report writing and other data manipulation statements. This allows using the same algebra in model definitions and assignment statements. The following code illustrates this feature,

$macro sumit(i,term) sum(i,term)
  cost ..        z  =e=  sumit((i,j), (c(i,j)*x(i,j))) ;
  supply(i) ..   sumit(j, x(i,j))  =l=  a(i) ;
  demand(j) ..   sumit(i, x(i,j))  =g=  b(j) ;
  Model transport /all/ ;
  Solve transport using lp minimizing z ;
$onDotL
parameter tsupply(i) total demand for report
          tdemand(j) total demand for report;
          tsupply(i)=sumit(j, x(i,j));
          tdemand(j)=sumit(i, x(i,j));

which will expand to:

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/ ;
Solve transport using lp minimizing z ;
parameter tsupply(i) total demand for report
tdemand(j) total demand for report;
tsupply(i)=sum(j,x.L(i,j));
tdemand(j)=sum(i,x.L(i,j));

The $onDotL enables the implicit .L suffix for variables. This feature was introduced to make macros more useful and is not limited to be used in macro bodies. The matching $offDotL will disable this feature.

maxcol n    (80000)

Sets the right margin for the input file. All valid data is before and including column n in the input file. All text after column n is treated as comment and ignored.

Consider the following example,

$maxcol 30
set i /vienna, rome/          set definition
scalar a /2.3/ ;              scalar definition

The text strings definition and scalar definition are treated as comments and ignored since they begin on or after column 31.

Any changes in the margins via maxcol or mincol will be reported in the listing file with the message that gives the valid range of input columns. For example, the dollar control option $mincol 20 maxcol 110 will trigger the message:

NEW MARGIN = 20-110
Attention
  • GAMS requires that the right margin set by $maxcol is greater than 15.
  • GAMS requires that the right margin set by $maxcol is greater than the left margin set by $mincol.

maxGoto    100

Sets the maximum number of jumps to the same label. Once the maximum number is reached an error is triggered. Consider the following example,

scalar a / 1 /;
$maxgoto 5
$label label1
a = a+10;
display a ;
$goto label1

When $goto label1 is called for the fifth time an error is triggered.

mincol n    (1)

Sets the left margin for the input file. All valid data is after and including column n in the input file. All text before column n is treated as comment and ignored.

Consider the following example,

$mincol 30
set definition               set i /vienna, rome/
scalar definition            scalar a /2.3/ ;

The text strings set definition and scalar definition are treated as comments and ignored since they begin before column 30.

Any changes in the margins via $maxcol or $mincol will be reported in the listing file with the message that gives the valid range of input columns. For example, the dollar control option $mincol 20 maxcol 110 will trigger the message:

NEW MARGIN = 20-110
Attention
GAMS requires that the left margin set by $mincol is smaller than the right margin set by $maxcol.

[on][off]Delim    ($offDelim)

Controls whether data in table statements are in comma delimited format. Consider running the following slice of code,

SETS
   PLANT  PLANT LOCATIONS /NEWYORK,CHICAGO,LOSANGLS /
   MARKET DEMANDS  /MIAMI,HOUSTON, PORTLAND/

table dist(plant,market)
$ondelim
,MIAMI,HOUSTON,PORTLAND
NEWYORK,1300,1800,1100
CHICAGO,2200,1300,700
LOSANGLS,3700,2400,2500
$offdelim
display dist;

The resulting listing file contains,

----     12 PARAMETER dist

               MIAMI     HOUSTON    PORTLAND

NEWYORK     1300.000    1800.000    1100.000
CHICAGO     2200.000    1300.000     700.000
LOSANGLS    3700.000    2400.000    2500.000

[on][off]Digit    ($onDigit)

Controls the precision check on numbers. Computers work with different internal precision. Sometimes a GAMS problem has to be moved from a machine with higher precision to one with lower precision. Instead of changing numbers with too much precision the $offdigit tells GAMS to use as much precision as possible and ignore the rest of the number. If the stated precision of a number exceeds the machine precision an error will be reported. For most machines, the precision is 16 digits.

Consider running the following slice of code,

parameter y(*)   / toolarge 12345678901234.5678
$offdigit
                   ignored  12345678901234.5678  /

The resulting listing file contains,

    1  parameter y(*)   / toolarge 12345678901234.5678
****                                                $103
    3                     ignored  12345678901234.5678  /
Error Messages
103  Too many digits in number
     ($offdigit can be used to ignore trailing digits)

Note that the error occurs in the 17th significant digit of y("toolarge"). However, after the $offdigit line, y("ignored") is accepted without any errors even though there are more than 16 significant digits.

[on][off]Dollar    ($offDollar)

This option controls the echoing of dollar control option lines in the listing file.

Consider running the following slice of code,

$hidden this line will not be displayed
$ondollar
$hidden this line will be displayed
$offdollar
$hidden this line will not be displayed

The listing file that results looks like,

2  $ondollar
3  $hidden this line will be displayed

Note that all lines between the $ondollar and $offdollar are echoed in the listing file. Also note that this action of this option is immediate, i.e. the $ondollar line is itself echoed on the listing file, while the $offdollar line is not.

[on][off]DotL    ($offDotL)

Activates or deactivates the automatic addition of .L to variables on the right hand side of calculations as described at $macro.

[on][off]Echo

Sends multiple subsequent lines to an external file. These commands are used employing the syntax

$Onecho  > externalfile1
line 1 to send
line 2 to send
$Offecho

or

$Onecho  >> externalfile2
line 1 to send
line 2 to send
$Offecho

In both cases the created file contains

line 1 to send
line 2 to send

The redirection symbols \(>\) and \(>>\) have the usual meaning of starting at the beginning or appending to an existing file. There is also a variant $onEchoS that permits parameter substitution as $onEcho also does and another variant $onEchoV that forbids parameter substitution. Consider the following example,

$set it TEST
$OnechoS  > externalfile1
send %it% to external file
line 2 to send
$Offecho

The created file contains

send TEST to external file
line 2 to send

while the file created by

$set it TEST
$OnechoV  > externalfile1
send %it% to external file
line 2 to send
$Offecho

contains

send %it% to external file
line 2 to send

In contrast to the second case in the first case %it% is substituded by TEST. Note that when there is no path included the file by default will be placed in the working directory.

[on][off]Embedded    ($offEmbedded)

Enables or disables the use of embedded values in parameter and set data statements. For sets, the final text is concatenated with blank separators. For example, the element texts for the set i and j will be identical:

set k /a,b/
    l /a/;
set i(k,l) / a.a 'aaaa cccc dddd', b.a 'bbbb cccc dddd' /
$onEmbedded
set j(k,l) / (a aaaa, b bbbb).(a cccc) dddd /

[on][off]Empty    ($offEmpty)

This option allows empty data statements for list or table formats. By default, data statements cannot be empty.

Consider running the following slice of code,

set i /1,2,3/ ;
set j(i) /  / ;
parameter x(i) empty parameter /  / ;
table y(i,i) headers only
     1   2   3
;
$onempty
set k(i) /  / ;
parameter xx(i) empty parameter /  / ;
table yy(i,i)
     1   2   3
;

The listing file that results looks like,

    1  set i /1,2,3/ ;
    2  set j(i) /  / ;
****               $460
    3  parameter x(i) empty parameter /  / ;
****                                     $460
    4  table y(i,i) headers only
    5       1   2   3
    6  ;
****   $462
    8  set k(i) /  / ;
    9  parameter xx(i) empty parameter /  / ;
   10  table yy(i,i)
   11       1   2   3
   12  ;

Error Messages

460  Empty data statements not allowed. You may want to use $ON/OFFEMPTY
462  The row section in the previous table is missing

Note that empty data statements are not allowed for sets, parameters or tables. These are most likely to occur when data is being entered into the GAMS model by an external program. Using the $onempty dollar control option allows one to overcome this problem.

Attention
The empty data statement can only be used with symbols, which have a known dimension. If the dimension is also derived from the data, the $phantom dollar control option should be used to generate 'phantom' set elements.

[on][off]End    ($offEnd)

Offers alternative syntax for flow control statements. Endloop, endif, endfor, and endwhile are introduced as key-words with the use of the $onend option that then serves the purpose of closing the loop, if, for, and while language constructs respectively.

The following example provides the alternate syntax for the four language constructs mentioned above (standard syntax as eolcomment).

set i/1*3/ ; scalar cond /0/;
parameter a(i)/1 1.23, 2 2.65, 3 1.34/;
$maxcol 40
$onend
loop i do                                loop (i,
  display a;                               display a;
endloop;                                 );

if (cond) then                           if (cond,
  display a;                               display a;
else                                     else
  a(i) = a(i)/2;                           a(i) = a(i)/2;
  display a;                               display a;
endif;                                   );

for cond = 1 to 5 do                     for (cond = 1 to 5,
  a(i) = 2 * a(i);                         a(i) = 2 * a(i);
endfor;                                  );

while cond < 2 do                        while (cond < 2,
  a(i) = a(i) / 2;                         a(i) = a(i) / 2;
endwhile;                                );

Note that the alternate syntax is more in line with syntax used in some of the popular programming languages.

Attention
Both forms of the syntax will never be valid simultaneously. Setting the $onend option will make the alternate syntax valid, but makes the standard syntax invalid.

[on][off]EolCom ($offEolCom)

Switch to control the use of end-of-line comments. By default, the end-of-line comment symbol is set to '!!' but the processing is disabled.

Consider running the following slice of code,

$oneolcom
set i /1*2/ ;     !! set declaration
parameter a(i) ;  !! parameter declaration

Note that comments can now be entered on the same line as GAMS code.

Attention
$eolcom automatically sets $oneolcom.

Consider the following example,

$eolcom ->
set i /1*2/ ;     -> set declaration
parameter a(i) ;  -> parameter declaration

The character set -> serves as the end-of-line-comment indicator.

[on][off]Eps    ($offEps)

This option is used to treat a zero as an EPS in a parameter or table data statement. This can be useful if one overloads the value zero with existence interpolation.

Consider running the following slice of code,

set i/one,two,three,four/ ;
parameter a(i) /
$oneps
      one     0
$offeps
      two     0
      three   EPS   /;
display a ;

The result of the display statement in the listing file is as follows,

----      8 PARAMETER A

one   EPS,    three EPS

Note that only those entries specifically entered as 0 are treated as EPS.

[on][off]Expand    ($offExpand)

Changes the processing of macros appearing in the arguments of a macro call. The default operation is not to expand macros in the arguments. The switch $onExpand enables the recognition and expansion of macros in the macro argument list and $offexpand will restore the default behavior.

[on][off]Global    ($offGlobal)

When an include file is inserted, it inherits the dollar control options from the higher level file. However, the dollar control option settings specified in the include file do not affect the higher level file. This convention is common among most scripting languages or command processing shells. In some cases, it may be desirable to break this convention. This option allows an include file to change options of the parent file as well.

Consider running the following slice of code,

$include 'inc.inc'
$hidden after first call to include file
$onglobal
$include 'inc.inc'
$hidden after second call to include file

where the file inc.inc contains the lines,

$ondollar
$hidden text inside include file

The resulting listing file is as follows,

INCLUDE    D:\GAMS\INC.INC
    2  $ondollar
    3  $hidden text inside include file
INCLUDE    D:\GAMS\INC.INC
    7  $ondollar
    8  $hidden text inside include file
    9  $hidden after second call to include file

Note that the effect of the $ondollar dollar control option inside the include file does not affect the parent file until $onglobal is turned on. The $hidden text is then echoed to the listing file.

[on][off]Include    ($onInclude)

Controls the listing of the expanded include file name in the listing file.

Consider running the following slice of code,

$include 'inc.inc'
$offinclude
$include 'inc.inc'

where the file inc.inc contains the line,

$ondollar
$hidden text inside include file

The resulting listing file is as follows,

INCLUDE    D:\GAMS\INC.INC
   2  $ondollar
   3  $hidden text inside include file
   6  $ondollar
   7  $hidden text inside include file

Note that the include file name is echoed the first time the include file is used. However, the include file name is not echoed after $offinclude is set.

[on][off]Inline    ($offInline)

Switch to control the use of in-line comments. By default, the in-line comment symbols are set to the two character pairs \(/*\) and \(*/\) but the processing is disabled. These comments can span lines till the end-of-comment characters are encountered.

Consider running the following slice of code,

$oninline
/* the default comment symbols are now
   active. These comments can continue
   to additional lines till the closing
   comments are found  */
Attention
$inlinecom automatically sets $oninline.

Consider running the following slice of code,

$inlinecom << >>
<< the in-line comment characters have been
   changed from the default. >>
Attention
Nested in-line comments are illegal unless $onnestcom is set.

[on][off]Listing    ($onListing)

Controls the echoing of input lines to the listing file. Note that suppressed input lines do not generate entries in the symbol and reference sections appearing at the end of the compilation listing. Lines with errors will always be listed.

Consider running the following slice of code,

set i /0234*0237/
    j /a,b,c/     ;
table x(i,j) very long table
        a   b   c
 0234   1   2   3
$offlisting
 0235   4   5   6
 0236   5   6   7
$onlisting
 0237   1   1   1

The resulting listing file looks as follows,

    1  set i /0234*0237/
    2      j /a,b,c/     ;
    3  table x(i,j) very long table
    4          a   b   c
    5   0234   1   2   3
   10   0237   1   1   1

Note that the lines in the source file between the $offlisting and $onlisting settings are not echoed to the listing file.

[on][off]Local    ($onLocal)

$onLocal allows unlimited use of .local on the same symbol in one control stack while $offLocal limits the use to one. Consider the following example,

set i /1*3/; alias(i,j);
parameter xxx(i,j) / 1.1 1, 2.2 2, 3.3 3, 1.3 13, 3.1 31 /;
display xxx;
parameter g(i,i);
g(i.local-1,i.local) = xxx(i,i);   display g;
$offlocal
g(i.local-1,i.local) = xxx(i,i)+1; display g;

The use of $offlocal causes a compilation error in the following line because .local is used twice on the same symbol in one control stack.

[on][off]Log    ($onLog)

Turns on/off line logging for information about the line number and memory consumption during compilation. This is scoped like the $on/offListing applying only to included files and any subsequent included files but reverting to $onlog in the parent files i.e. when file1 includes file 2 and file 2 contains $offlog then subsequent lines in file 2 will not be logged but lines in file 1 will be.

[on][off]Macro    ($onMacro)

Enables or disables the expansion of $macros. For example

$macro oneoverit(y) 1/y
$offmacro
y = oneoverit(x1);
display y;

causes an error because the macro oneoverit can not be expanded in line 3.

[on][off]Margin    ($offMargin)

Controls the margin marking. The margins are set with $mincol and $maxcol.

Consider running the following slice of code,

$onmargin mincol 20 maxcol 45
Now we have         set i plant /US, UK/     This defines I
turned on the       scalar x / 3.145 /       A scalar example.
margin marking.     parameter a, b;          Define some
                                             parameters.
$offmargin

Any statements between columns 1 and 19, and anything beyond column 45 are treated as comments.

[on][off]Multi    ($offMulti)

Controls multiple data statements or tables. By default, GAMS does not allow data statements to be redefined. If this option is enabled, the second or subsequent data statements are merged with entries of the previous ones. Note that all multiple data statements are executed before any other statement is executed.

Consider running the following slice of code,

$eolcom !
set i / 1*10 /;
parameter x(i) / 1*3  1 /   ! 1=1,2=1,3=1
$onmulti
parameter x(i) / 7*9  2 /   ! 1=1,2=1,3=1,7=2,8=2,9=2
parameter x(i) / 2*6  3 /   ! 1=1,2=3,3=3,4=3,5=3,6=3,7=2,8=2,9=2
parameter x(i) / 3*5  0 /   ! 1=1,2=3,6=3,7=2,8=2,9=2
display x;

This would have been illegal without the presence of the $onmulti option. The result of the display statement in the listing file is as follows,

----      8 PARAMETER X

1 1.000,    2 3.000,    6 3.000,    7 2.000,    8 2.000,    9 2.000

Note that x("1") has a value of 1 after the first data statement since none of the subsequent data statements affect it. x("2") on the other hand is reset to 3 by the third data statement.

Attention
The two-pass processing of a GAMS file can lead to seemingly unexpected results. Both the dollar control options and the data initialization is done in the first pass, and assignments in the second, irrespective of their relative locations. This is an issue particularly with $onmulti since it allows data initializations to be performed more than once.

Consider the following example,

scalar a /12/ ;
a=a+1;
$onmulti
scalar a /20/ ;
display a ;

The two scalar data initialization statements and the $onmulti option are processed before the assignment statement a=a+1. In the order that it is processed, the example above is read by GAMS as,

* compilation step
scalar a /12/ ;
$onmulti
scalar a /20/ ;
* execution step
a=a+1;
display a ;

The example results in a taking a value of 21. The display statement in the resulting listing file is as follows,

----      5 PARAMETER A                    =       21.000

[on][off]NestCom    ($offNestCom)

Controls nested in-line comments. Make sure that the open-comment and close-comment characters have to match.

Consider running the following slice of code,

$inlinecom { } onnestcom
{ nesting is now possible in comments { braces
  have to match } }

[on][off]Order    ($onOrder)

Lag and lead operations require the reference set to be ordered and constant. In some special cases one would want to use those operation on dynamic and/or unordered sets. The option $on/offOrder has been added to locally relax the default requirements. The use of this option comes with a price, the system will not be able to diagnose odd and incorrect formulations and data sets.

[on][off]Put

Causes a block of text to be placed in a put file. These commands are used employing the syntax

file putfile
put putfile
$onPut
Line 1 of text
Line 2 of text

Line 3 of text
Line 4 of text
$offPut

The resulting file putfile.put contains

Line 1 of text
Line 2 of text

Line 3 of text
Line 4 of text

There is also a variant $onPutS that permits parameter substitution and another variant onPutV that forbids parameter substitution as onPut also does. Consider the following example,

$set it TEST
file putfile
put putfile
$onPutS
Line 1 of text "%it%"
Line 2 of text %it%
$offPut

The created putfile contains

Line 1 of text "TEST"
Line 2 of text TEST

while the putfile created by

$set it TEST
file putfile
put putfile
$onPutV
Line 1 of text "%it%"
Line 2 of text %it%
$offPu

contains

Line 1 of text "%it%"
Line 2 of text %it%

In contrast to the second case in the first case %it% is substituded by TEST.

[on][off]Recurse    ($offRecurse)

Allows a file to include itself. For example a file called file1.gms can contain

$onrecurse
$include file1

Note that the maximum include nesting level is 40 and if it is exceeded an error is triggered.

[on][off]StrictSingleton    ($onStrict Singleton)

With $offStrictSingleton GAMS does not complain about a data statement for a singleton set with more than one element but takes the first one. With $onStrictSingleton such a data statement creates an error.

[on][off]SymList    ($offSymList)

Controls the complete listing of all symbols that have been defined and their text, including pre-defined functions and symbols, in alphabetical order grouped by symbol type.

The symbol listing in the listing file generated by running [TRNSPORT] with $onsymlist is as follows,

Symbol Listing

SETS
I           canning plants
J           markets

PARAMETERS
A           capacity of plant i in cases
B           demand at market j in cases
C           transport cost in thousands of dollars per case
D           distance in thousands of miles
F           freight in dollars per case per thousand miles

VARIABLES
X           shipment quantities in cases
Z           total transportation costs in thousands of dollars

EQUATIONS
COST        define objective function
DEMAND      satisfy demand at market j
SUPPLY      observe supply limit at plant i

MODELS
TRANSPORT

FILES
FILE        Current file name for FILE.xxx use

PREDEFINED
DIAG
SAMEAS

This serves as a simple description of the symbols used in a model, and can be used in reports and other documentation.

[on][off]SymXRef    ($offSymXRef)

This option controls the following,

  • Collection of cross references for identifiers like sets, parameters, and variables.
  • Cross-reference report of all collected symbols in listing file
  • Listing of all referenced symbols and their explanatory text by symbol type in listing file. This is also reported by using $onsymlist.

Consider the following slice of code,

$onsymxref
set i / 1*6/,k;
$offsymxref
set j(i) will not show / 1*3 /
display i;
$onsymxref
k('1') = yes;

The resulting listing file will contain the following unique element reference reports,

SYMBOL      TYPE   REFERENCES

i            SET   declared        2  defined        2
k            SET   declared        2 assigned        7

SETS

i
k

[on][off]Text

The $onText - $offText pair encloses comment lines. Line numbers in the compiler listing are suppressed to mark skipped lines.

Consider the following,

* standard comment line
$ontext
Everything here is a comment
until we encounter the closing $offtext
like the one below
$offtext
* another standard comment line

The resulting listing file is as follows,

    1  * standard comment line
       Everything here is a comment
       until we encounter the closing $offtext
       like the one below
    7  * another standard comment line
Attention
GAMS requires that every $ontext has a matching $offtext, and vice versa.

[on][off]UElList ($offUElList)

This option controls the complete listing of all set elements that have been entered, in the listing file.

The unique element listing in the listing file generated by running [TRNSPORT] with $onUElList is as follows,

Unique Element Listing

Unique Elements in Entry Order
1   SEATTLE     SAN-DIEGO   NEW-YORK    CHICAGO     TOPEKA
Unique Elements in Sorted Order
1   CHICAGO     NEW-YORK    SAN-DIEGO   SEATTLE     TOPEKA

Note that the sorted order is not the same as the entry order. This is explained in Section Assigning Membership to Dynamic Sets .

[on][off]UElXRef ($offUElXRef)

This option controls the collection and listing (in the listing file) of cross references of set elements.

Consider the following slice of code,

$onuelxref
set i this is set declaration / one, two, three /, k(i)
$offuelxref
set j(i) will not show / two /;
$onuelxref
k('one') = yes;

The resulting listing file will contain the following unique element reference reports,

ELEMENT            REFERENCES
ONE          DECLARED        2    INDEX        6
THREE        DECLARED        2
TWO          DECLARED        2

[on][off]UNDF    ($offUNDF)

Controls the use of the special value UNDF which indicates a result is undefined. A user may not use this in an assignment unless the $onUNDF command has been used. The following slice of code

scalar x;
$onUNDF
x=UNDF;
display x;

creates the following part at the listing file

4 PARAMETER x                    =         UNDF

Without the use of $onUndf an error would be triggered. The use of $offUNDF will disallow the usage of UNDF in assignments.

[on][off]Verbatim

These commands are used in conjunction with the GAMS parameter DUMPOPT to suppress the input preprocessing for input lines that are copied to the dmp file. This feature is mainly used to maintain different versions of related models in a central environment.

The $on/offVerbatim commands are only recognized for DUMPOPT \(\geq\) 10 and apply only to lines in the file the commands appeared.

The use of $goto and $on/offVerbatim are incompatible and may produce unexpected results. Consider the following example,

$set f 123
$log %f%
$onVerbatim
$log %f%
$offverbatim
$log %f%

The corresponding dmp file contains

$log 123
$onVerbatim
$log %f%
$offVerbatim
$log 123

[on][off]Warning    ($$offWarning)

Switch for data domain checking. In some cases it may be useful to accept domain errors in data statements that are imported from other systems and report warnings instead of errors. Data will be accepted and stored, even though it is outside the domain.

Attention
  • This switch effects three types of domain errors usually referred to as error numbers 116, 170 and 171.
  • This can have serious side affects and one has to exercise great care when using this feature.

Consider the following slice of code,

set i     / one,two,three /
$onwarning
    j(i)  / four, five /
    k     / zero /;
parameter x(i) Messed up Data / one 1.0, five 2.0 /;
x('six') = 6; x(j) = 10; x('two') = x('seven');
j(k) = yes;
$offwarning
display i,j,x;

Note that the set j, although specified as a subset of i, contains elements not belonging to its domain. Similarly, the parameter x contains data elements outside its domain. The skeleton listing file that results from running this code is as follows,

 1  set i     / one,two,three /
   3      j(i)  / four, five /
****                 $170  $170
   4      k     / zero /;
   5  parameter x(i) Messed up Data / one 1.0, five 2.0 /;
****                                              $170
   6  x('six') = 6; x(j) = 10; x('two') = x('seven');
****        $170                                  $116,170
   7  j(k) = yes;
****     $171
   9  display i,j,x;

 Error Messages

116  Label is unknown
170  Domain violation for element
171  Domain violation for set

**** 0 ERROR(S)   7 WARNING(S)

E x e c u t i o n


----      9 SET i
one  ,    two  ,    three


----      9 SET j
four,    five,    zero


----      9 PARAMETER x  Messed up Data
one   1.000,    four 10.000,    five 10.000,    six   6.000

The domain violations are marked like normal compilation errors but are only treated as warnings and one can execute the code.

phantom   id

Used to designate id as a phantom set element. Syntactically, a phantom element is handled like any other set element. Semantically, however, it is handled like it does not exist. This is sometimes used to specify a data template that initializes the phantom records to default values.

Consider the following example,

$phantom null
set i / null/
    j / a,b,null/ ;
display i,j ;

The resulting section of the listing file is shown below,

----      4 SET       I
                      (EMPTY)

----      4 SET       J
a,    b

Note that null does not appear in the listing file.

Attention
Assignment statements on the phantom label are ignored.

Consider the following extension to the previous example,

Parameter p(j) / a 1, null 23 / ;
display p ;

The resulting section of the listing file is shown below,

----      6 PARAMETER P

a 1.000

prefixPath

Augments the search path in the Windows path environment variable. The use of $prefixpath value results in the text in value being appended to the beginning of the search path. Consider the following example,

display "%sysenv.PATH%";
$prefixpath C:\somewhereelse\anotherpath
display "%sysenv.PATH%";

If %sysenv.PATH% contains C:\some\path\somehwere in the beginning it will also contain C:\somewhereelse\anotherpath after the second line and the resulting listing file contains

----      1
C:\some\path\somehwere
----      3
C:\somewhereelse\anotherpath;C:\some\path\somehwere

protect

Freezes all values of the named parameters not allowing modification but still allowing their use in model calculation (.. commands when models are set up) in a privacy setting. The syntax is

$protect item1 item2 ...

or

$protect all

where one can list multiple items to protect them. The word all causes protection of all items. These privacy restrictions can be removed with $expose or $purge.

purge

removes the items and all data associated in a privacy setting. The syntax is

$purge item1 item2 ...

or

$purge all

In the first case only the listed items are removed, in the second case all items are removed. One can set the corresponding privacy restrictions with $hide or $protect.

Note that a special license file is needed for this feature to work and that the removal only takes effect in the restart files.

remark

Adds a comment to the listing file with parameter substitution and suppressed line number. Consider the following example,

$set it TEST
$remark write %it% to the listing file

The resulting listing file contains

write TEST to the listing file

set

Establishes or redefines contents of a control variable that is accessible in the code where the command appears and all code included therein. The syntax is $set varname expression where varname is any user chosen variable name and expression is optional and can contain text or a number. These variables are destroyed using $drop varname.

In contrast to $eval the $set command does not evaluate the expression at compile time.

For differences to $setGlobal and $setLocal consider the following example,

$setGlobal Anumber 3**2+2
$setLocal Bnumber 44/2
$set Cnumber min(33,34)
$ife %Anumber%=11 display "Anumber equals 11"
$ife %Bnumber%=22 display "Bnumber equals 22"
$ife %Cnumber%=33 display "Cnumber equals 33"

$include test2.gms

$if %Dnumber%==44 display "Dnumber equals 44"
$if NOT %Dnumber%==44 display "Dnumber does NOT equal 44"
$if %Enumber%==55 display "Enumber equals 55"
$if NOT %Enumber%==55 display "Enumber does NOT equal 55"
$if %Fnumber%==66 display "Fnumber equals 66"
$if NOT %Fnumber%==66 display "Fnumber does NOT equal 66"

where test2.gms is

$ife %Anumber%==11 display "Anumber equals 11 in test2.gms"
$ife NOT %Anumber%==11 display "Anumber does NOT equal 11 in test2.gms"
$if %Bnumber%==22 display "Bnumber equals 22 in test2.gms"
$if NOT %Bnumber%==22 display "Bnumber does NOT equal 22 in test2.gms"
$ife %Cnumber%==33 display "Cnumber equals 33 in test2.gms"
$ife NOT %Cnumber%==33 display "Cnumber does NOT equal 33 in test2.gms"

$setGlobal Dnumber 44
$setLocal Enumber 55
$set Fnumber 66

The resulting listing file contains,

----      4 Anumber equals 11

----      5 Bnumber equals 22

----      6 Cnumber equals 33

----      9 Anumber equals 11 in test2.gms

----     12 Bnumber does NOT equal 22 in test2.gms

----     13 Cnumber equals 33 in test2.gms

----     20 Dnumber equals 44

----     23 Enumber does NOT equal 55

----     25 Fnumber does NOT equal 66

Note that GAMS allows one to define scoped, local and global variables with the same name and has to prioritize under some cases. Consider the following slice of code,

$setglobal notunique aa
$setlocal notunique bb
$set notunique cc
$if "%notunique%" == "aa" display "it is aa";
$if "%notunique%" == "bb" display "it is bb";
$if "%notunique%" == "cc" display "it is cc";

The resulting listing file contains,

----      5 it is bb

setArgs

Sets up substitutable parameters as GAMS control variable names. Consider the following example,

scalar a /2/, b /4/, c /5/;
$batinclude test3 a b c

where test3.gms is,

scalar x;
x = %1 + %2 * %3 ;
display x;
$setargs aa bb cc
x = %aa% - %bb% * %cc%  ;
display x;
x = %1 + %2 * %3 ;
display x;

The $setArgs command that must appear in the Batincluded file allows this Batinclude file to use %aa% in place of %1, %bb% in place of %2 and %cc% in place of %3. Note that the use of %1,%2 etc. is still allowed. The resulting listing file contains,

----      5 PARAMETER x                    =       22.000

----      8 PARAMETER x                    =      -18.000

----     10 PARAMETER x                    =       22.000

setComps

Establishes or redefines control variables so they contain the components of a period delimited string. The syntax is $setcomps perioddelimstring v1 v2 v3 ... where perioddelimstring is any period delimited string like the set specification of a multidimensional parameter and v1 is the name of a control variable that will contain the name of the set element in the first position v2 is the name of a control variable that will contain the name of the set element in the second position v3 is the name of a control variable that will contain the name of the set element in the third position. The items may be recombined back into the original filename string by using %v1%.%v2%.%v3%. Consider the following example,

$setcomps period.delim.string v1 v2 v3
display "v1 = %v1%";
display "v2 = %v2%";
display "v3 = %v3%";
$set name %v1%.%v2%.%v3%
display "name = %name%";

The resulting listing file contains,

----      2 v1 = period

----      3 v2 = delim

----      4 v3 = string

----      6 name = period.delim.string

setDDList

Causes GAMS to look for misspelled or undefined 'double dash' GAMS parameters. Consider the following example:

The following 'double dash' parameters are defined in the command line

--one=11 --three=33  --four=44

and the corresponding gms file contains

display '%one%';
display '%two%';
$setDDList three
display '%three%';
display '%four%';

$setDDList three checks if all 'double dash' parameters have been used so far except three. An error is triggered because four has not been used so far and the log file contains

*** 1 double dash variables not referenced
    --four=44

setEnv

Defines an operating system environment variable. The syntax is $setEnv varname value where varname is a user chosen environment variable name and value can contain text or a number. Environment variables are destroyed with $dropenv varname. Consider the following example,

$ondollar
$set env this is very silly
$log %env%
$setenv verysilly %env%
$log %sysenv.verysilly%
$if NOT "%env%" == "%sysenv.verysilly%" $error setenv did not work

$dropenv verysilly
$if setenv verysilly $error should not be true

The following output is echoed to the log file,

--- Starting compilation
this is very silly
this is very silly

setGlobal

Establishes or redefines contents of a control variable that is accessible in the code where the command appears and all code included therein. The syntax is $setglobal varname expression where varname is any user chosen variable name and expression is optional and can contain text or a number. These variables are destroyed using $dropglobal varname.

In contrast to $evalGlobal the $setGlobal command does not evaluate the expression at compile time. For differences to $set and $setLocal check the example in the description of $set.

Note that GAMS allows one to define scoped, local and global variables with the same name but treats them as different under some cases and prioritizes them when using $ife or $if. Consider the following example,

$setglobal notunique aa
$setlocal notunique bb
$set notunique cc
$if "%notunique%" == "aa" display "it is aa";
$if "%notunique%" == "bb" display "it is bb";
$if "%notunique%" == "cc" display "it is cc";

The resulting listing file contains,

----      5 it is bb

setLocal

Establishes or redefines contents of a control variable that is accessible only in the code module where defined. The syntax is $setLocal varname expression where varname is any user chosen variable name and expression is optional and can contain text or a number. These variables are destroyed using $droplocal varname.

In contrast to $evalLocal the $setLocal command does not evaluate the expression at compile time. For differences to $set and $setGlobal check the example in the description of $set.

Note that GAMS allows one to define scoped, local and global variables with the same name but treats them as different under some cases and prioritizes them when using $ife or $if.

Consider the following example,

$setglobal notunique aa
$setlocal notunique bb
$set notunique cc
$if "%notunique%" == "aa" display "it is aa";
$if "%notunique%" == "bb" display "it is bb";
$if "%notunique%" == "cc" display "it is cc";

The resulting listing file contains,

----      5 it is bb

setNames

Establishes or redefines three control variables so they contain the drive subdirectory, filename and extension of a file named with full path. The syntax is setnames FILE filepath filename fileextension where FILE is any filename, filepath is the name of a control variable that will contain the name of the subdirectory where the file is located, filename is the name of a control variable that will contain the root name of the file and fileextension is the name of a control variable that will contain the extension of the file. Consider the following example,

$setnames d:\gams\xxx.txt filepath filename fileextension
$setglobal name %filepath%%filename%%fileextension%
$log %name%

FILE is seperated into its three components placing d:\gams into filepath, xxx into filename and .txt into fileextension. The three items can be recombined back into the original filename by using %filepath%%filename%%fileextension% as shown in the example.

shift

The $shift option is similar to the DOS batch shift operator. It shifts the order of all parameters passed once to the 'left'. This effectively drops the lowest numbered parameter in the list. Consider the following example,

scalar a, b, c ; a = 1 ;
$batinclude inc.inc a b c
display a, b, c ;

where the batch include file inc.inc is as follows,

%2 = %1 + 1 ;
$shift
%2 = %1 + 1 ;

The resulting listing file contains,

    1  scalar a, b, c ; a = 1 ;
BATINCLUDE C:\PROGRAM FILES\GAMSIDE\INC.INC
    3  b = a + 1 ;
    5  c = b + 1 ;
    6  display a, b, c ;

In the first statement in the include file, %1 is the first argument in the $batinclude call and is interpreted in this case as a. %2 is the second argument in the $batinclude call and is interpreted as b. This leads to the overall assignment being interpreted as b=a+1.

The $shift option shifts the arguments to the left. So now, %1 is interpreted as b, and %2 is interpreted as c. This leads to the second assignment being interpreted as c=b+1.

The result of the display statement in the input file is therefore,

----      6 PARAMETER A                    =        1.000
            PARAMETER B                    =        2.000
            PARAMETER C                    =        3.000

show

Shows current values of the control variables plus a list of the macros. Consider the following example,

$set it 1
$setlocal yy
$setglobal gg what
$include includ
$show

where indlud.gms is

$set inincs
$setlocal inincsl
$setglobal inincsg
$show

The resulting listing file contains,

Level SetVal                          Type       Text
-----------------------------------------------------
    1 inincsl                         LOCAL
    1 inincs                          SCOPED
    0 yy                              LOCAL
    0 it                              SCOPED     1
    0 gg                              GLOBAL     what
    1 inincsg                         GLOBAL

and

Level SetVal                          Type       Text
-----------------------------------------------------
    0 yy                              LOCAL
    0 it                              SCOPED     1
    0 gg                              GLOBAL     what
    1 inincsg                         GLOBAL

Note that only the item defined as $setGlobal in the included file carries over.

single

The lines following a $single option will be echoed single spaced on the compiler listing. This option is the default, and is only useful as a switch to turn off the $double option.

Consider the following example,

set i /1*2/ ;
scalar a /1/ ;
$double
set j /10*15/ ;
scalar b /2/ ;
$single
set k /5*10/ ;
scalar c /3/ ;

The resulting listing file looks as follows,

    1  set i /1*2/ ;
    2  scalar a /1/ ;

    4  set j /10*15/ ;

    5  scalar b /2/ ;
    7  set k /5*10/ ;
    8  scalar c /3/ ;

Note that lines between the $double and $single options are listed double spaced, while the lines after the $single option revert back to being listed singly spaced.

splitOption

Establishes or redefines two compile-time variables so they contain the name and value of an option key/value pair specified in various formats. The syntax is splitOption KEYVALPAIR optname optvalue where KEYVALPAIR is a string formatted as -opt=val or -opt val (instead of - one can also use /). optname is the name of a compile-time variable that will contain the name of the option and optvalue is the name of a compile-time variable that will contain the value of the option. This is useful in particular in combination with batInclude files. Consider the following example,

* Default values for named arguments
$set a1 1
$set a2 2
$set a3 3
$label ProcessNamedArguments
$  splitOption "%1" key val
$  if x%key%==x $goto FinishProcessNamedArguments
$  iftheni.NamedArguments %key%==a1
$    set a1 %val%
$  elseifi.NamedArguments %key%==a2
$    set a2 %val%
$  elseifi.NamedArguments %key%==a3
$    set a3 %val%
$  else.NamedArguments
$    error Unkown named argument "%key%"
$  endif.NamedArguments
$  shift
$goto ProcessNamedArguments
$label FinishProcessNamedArguments
$log Using named arguments -a1=%a1% -a2=%a2% -a3=%a3%

Now when calling this piece of code as a batInclude one can specify optionally some named arguments (in any order) right after the name of the batInclude file and before the positional arguments:

$batInclude myinclude -a3=0 -a2=3.14 i j k

stars   (****)

This option is used to redefine the '****' marker in the GAMS listing file. By default, important lines like those denote errors, and the solver/model status are prefixed with '****'.

Consider the following example,

$stars *##*
garbage

The resulting listing file looks as follows,

    2  garbage
*##*         $140
*##*  $36,299  UNEXPECTED END OF FILE (1)

Error Messages
 36  '=' or '..' or ':=' or '$=' operator expected
     rest of statement ignored
140  Unknown symbol
299  Unexpected end of file

stitle

This option sets the subtitle in the page header of the listing file to 'text' which follows immediately the keyword stitle. The next output line will appear on a new page in the listing file.

Consider the following example,

$stitle data tables for input/output

stop

Stops program compilation without creating an error. But there is a difference to $exit. If you have only one input file $stop and $exit will do the same thing. If you are in an include file, $exit acts like an end-of file on the include file. However, if you encounter a $stop in an include file, GAMS will stop reading all input.

sysInclude

Equivalent to $batInclude:

$sysinclude file arg1 arg2 ...

However, if an incomplete path is given, the file name is completed using the system include directory. By default, the system include directory is set to the GAMS system directory. The default directory can be reset with the sdir command line parameter.

Consider the following example,

$sysinclude abc x y

This call first looks for the include file [GAMS System Directory]/abc, and if this file does not exist, looks for [GAMS System Directory]/abc.gms. The arguments x and y are passed on to the include file to interpret as explained for the $batinclude option.

Consider the following example,

$sysinclude c:\abc\myinc.inc x y

This call first looks specifically for the include file c:\abc\myfile.inc.

terminate

$terminate terminates compilation and execution immediately.

title

This option sets the title in the page header of the listing file to 'text' which follows immediately the keyword title. The next output line will appear on a new page in the listing file.

Consider the following example,

$title  Production Planning Model
$stitle Set Definitions

unload

This dollar command unloads specified items to a GDX file. It is employed using the syntax $unload item1 item2 ... but must be used in conjunction with the command $gdxOut. $unload must be preceded and succeeded by a $gdxOut. The preceding $gdxOut specifies the GDX file name and opens the file. The succeeding $gdxOut closes the file. More than one $unload can appear in between. Consider the following slice of code,

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  ;

$gdxout tran
$unload i j
$unload b=dem a=sup
$unload d
$gdxout

This will create a file tran.gdx containing i,j,d and parameters a and b which are now declared as dem and sup.

use205

This option sets the GAMS syntax to that of Release 2.05. This is mainly used for 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 run with the latest version of GAMS. This option will allow one to run such models.

Consider the following example,

$use205
set if /1.2.3/; scalar x ;

The word if is a keyword in GAMS introduced with the first version of Release 2.25. The setting of the $use205 option allows if to be used as an identifier since it was not a keyword in Release 2.05.

use225

This option sets the GAMS syntax to that of first version of Release 2.25. This is mainly used for backward compatibility. New keywords have been introduced in the GAMS language since the first version of Release 2.25. Models developed earlier that use identifiers that have since become keywords will cause errors when run with the latest version of GAMS. This option will allow one to run such models.

Consider the following example,

$use225
set for /1.2.3/; scalar x ;

The word for is a keyword in GAMS introduced with the later versions of Release 2.25. The setting of the $use225 option allows for to be used as an identifier since it was not a keyword in the first version of Release 2.25.

use999

This option sets the GAMS syntax to that of the latest version of the compiler. This option is the default.

Consider the following example,

$use225
set for /1.2.3/; scalar x ;
$use999
for (x=1 to 3, display x) ;

The word for is used as a set identifier by setting the option $use225, and later the keyword for is used as a looping construct by setting the language syntax to that of the latest version by setting $use999.

version

$version nnn issues a compilation error if nnn is greater than the current GAMS version.

warning

$warning issues a compilation warning but continues compilation and execution.