Dollar Control Options

Table of Contents

Introduction

Dollar control options are used to indicate compiler directives and options. Dollar control options are not part of the GAMS language and must be entered on separate lines marked with the 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 separated by spaces. Since the dollar control options are not part of the GAMS language, they do not appear on the compilation output in the listing file unless an error has been detected or the user has requested them to be shown (with the option $onDollar).Note that dollar control option lines are not case sensitive and a continued compilation uses the previous settings.

This chapter is organized as follows. First an overview of the dollar control options will be given in section List of Dollar Control Options, where the options will be presented in groups reflecting their major functional categories. Section Detailed Description of Dollar Control Options will contain a reference list of all dollar control options in alphabetical order with detailed description for each.

We will conclude this chapter with separate sections for two important topics: Conditional Compilation and Macros in GAMS.

Syntax

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

$option_name argument_list {option_name argument_list}

The symbol $ in the first column indicates that this is a dollar control statement. It is followed by the name of the dollar control option option_name and the list of arguments argument_list of the option. Depending on the particular option, the number of arguments required can vary from 0 to many. More than one dollar control option may be activated in one statement. Note that in this case the symbol $ is not repeated. Observe that some dollar control options require that they be the first option on a line.

Note
  • No blank space is permitted between the character $ and the first option that follows.
  • The effect of the dollar control option is felt immediately after the option is processed.
  • Dollar control options are not part of the GAMS language they instruct the compiler to perform some task. Therefore, dollar control options are not terminated with a semicolon as real GAMS language statements.

A simple 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. These options turn on the echoing of the symbol cross reference table and symbol listing in the compilation output in the listing file.

Observe that it is also permitted to place a dollar control statement in a column other than column 1. However, in this case the statement must begin with the symbols $$, like in this example

    $$title Example showing that dollar control option can start in any column with an extra $ added

List of Dollar Control Options

The dollar control options are grouped into nine major functional categories affecting

The following subsections briefly describe the options in each of the categories.

Dollar Control Options Affecting the Input Comment Format

Option Description
comment Set the comment character
eolCom Set the end-of-line comment character(s)
inlineCom Set the in-line comment characters
maxCol Set the right-hand margin of the input file
minCol Set left-hand margin of the input file
offEolCom Turn end-of-line comments off
offInline Turn in-line comments off
offMargin Turn margin marking off
offNestCom Turn nested comments off
offText Turn text mode off
onEolCom Turn end-of-line comments on
onInline Turn in-line comments on
onMargin Turn margin marking on
onNestCom Turn nested comments on
onText Turn text on: the following lines are comment

Note that comments in GAMS are introduced in section Comments.

Dollar Control Options Affecting the Input Data Format

Option Description
dollar Set the 'dollar' character
offDelim Turn delimited data statement syntax off
offDigit Turn the number precision check off
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 zero
offGlobal Disallow inheritance of parent file settings
offUNDF Do not allow UNDF as input
offUni Do not allow domain violations in assignments
offWarning Do not convert domain errors into warnings
onDelim Turn delimited data statement syntax on
onDigit Turn number precision check on
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 zero
onGlobal Force inheritance of parent file settings
onUNDF Allow UNDF as input
onUni Allow domain violations in assignments
onWarning Convert certain domain errors into warnings
use205 Language syntax of release 2.05
use225 Language syntax of release 2.25 Version 1
use999 Latest language syntax
version Test GAMS compiler version number

Dollar Control Options Affecting the Output Format

Option Description
double Double-spaced listing follows
echo Echo text to a file
echoN Echo text 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 the page
log Send message to the log
offDollar Turn the listing of dollar control option lines off
offEcho End of block echo
offInclude Turn the listing of include file names off
offListing Turn echoing input lines to listing file off
offLog Turn line logging off
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 and reset page

Dollar Control Options Affecting the Listing of Reference Maps

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

Dollar Control Options Affecting Program Control

Option Description
abort[.noError] Issue an (error) message and abort compilation
batInclude Include file with substitution arguments
call Execute another program during compilation
call.Async[NC] Execute another program asynchronously during compilation
clear Reset all data for an identifier to its default value
clearError[s] Clear compilation errors
else Else clause
elseIf ElseIf structure with case sensitive comparison
elseIfE ElseIf structure with expression evaluation
elseIfI ElseIf structure with case insensitive comparison
endif Close 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 Execute another program (hidden) during compilation
hiddenCall.Async[NC] Execute another program (hidden) asynchronously during compilation
if Conditional processing, case sensitive
ifE If statement with expression evaluation
ifI Conditional processing, case insensitive
ifThen IfThen-elseIf structure with case sensitive comparison
ifThenE IfThen-elseIf structure with expression evaluation
ifThenI IfThen-elseIf structure with case insensitive comparison
include Include file
kill Kill data connected with identifier
label Label name as entry point from $goto .
libInclude Include file from library directory
offEmbeddedCode Ends embedded code section
offMulti Turn redefinition of data off
offOrder Allow lag and lead operations on dynamic or unordered sets
offRecurse Disable recursive include files
offStrictSingleton Take first label if data statement for singleton set has multiple elements
onEmbeddedCode Starts embedded code section with substitution
onEmbeddedCodeS Starts embedded code section with substitution
onEmbeddedCodeV Starts embedded code section without substitution
onMulti Turn redefinition of data on
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 Define a phantom element
shift bat/lib/sysInclude argument shift operation
stop Stop compilation
sysInclude Include file from system directory
terminate Terminate compilation and execution
warning Issue compilation warning

Note that conditional compilation in GAMS is discussed in section Conditional Compilation below.

Dollar Control Options for 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.

Note that GDX facilities and utilities are introduced in chapter GAMS Data eXchange (GDX).

Dollar Control Options for Compile-Time Variables and Environment Variables

Option Description
drop Drop a scoped compile-time variable
dropGlobal Drop a global compile-time variable
dropLocal Drop a local compile-time variable
dropEnv Drop an OS environment variable
escape Define the % escape symbol
eval Evaluate and define a scoped compile-time variable
evalLocal Evaluate and define a local compile-time variable
evalGlobal Evaluate and define a global compile-time variable
prefixPath Prefix the environment variable PATH.
setArgs Define local compile-time variables using argument list
setComps Unpack dotted names into compile-time variables
setDDList Check double dash GAMS parameters
setEnv Define an OS environment variable
set Define a scoped compile-time variable
setGlobal Define a global compile-time variable
setLocal Define a local compile-time variable
setNames Unpack a filename into local compile-time variables
show Show macros and current values of compile-time variables
splitOption Unpack a key/value pair into local environment variables

See also sections Compile-Time Variables and Environment Variables in GAMS.

Dollar Control Options for Macro Definitions

Option Description
macro Preprocess macro definition
offDotL Do not assume .l for variables in assignments
offDotScale Assume .scale for variables and equations 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
onDotScale Assume .scale for variables and equations in assignments
onExpand Expand macros when processing macro arguments
onLocal No limit on .local nesting
onMacro Recognize macros for expansion

Note that macros are introduced in section Macros in GAMS below.

Dollar Control Options for Compressing and Encrypting Source Files

Option Description
compress Create compressed GAMS system file
decompress Decompress a GAMS system file
encrypt Create an encrypted GAMS system file
expose Remove all access control restrictions
hide Hide objects from the user
protect Protect objects from being modifified by the user
purge Remove the objects and all associated data

Detailed Description of Dollar Control Options

In this section we will describe each dollar control option in detail. Note that the dollar control options are listed in alphabetical order for easy reference. Note further, that in each entry the default value, if applicable, is given in parentheses.

$abort[.noError]

Syntax:

$abort[.noError] [text]

If used as $abort, this option will issue a compilation error and abort the compilation. It may be followed by a text.

Example:

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

This stops compilation if the operating system is not Unix. Running the example above on Windows will result in the compilation being aborted and the following lines in the listing file:

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

Error Messages
343  Abort triggered by above statement

This option has a variant: $abort.noError. If the extension .noError is used the compilation will be aborted as well, but there will be no error. If a save file is written, all remaining unexecuted code will be flushed. This allows effective reuse of the save file.

Note that there is also an abort statement in GAMS, it is used to terminate the execution of a program.

See also $exit, $error, $stop, and $terminate.

$batInclude

Syntax:

$batInclude external_file {arg}

The $batInclude facility performs the same task as the $include facility: it inserts the contents of the specified file external_file at the location of the call. However, in addition, the option $batInclude also passes on arguments arg which may be used inside the include file. External_file is the name of the batch include file, it may be quoted or unquoted. The arguments arg are passed on to the batch include file. These arguments are treated as character strings that are substituted by numbers inside the included file. The arguments may be single unbroken strings (quoted or unquoted) or quoted multi-part strings.

Note that 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 an 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). Observe that parameters are substituted independent of context and the entire line is processed before it is passed to the compiler. There is one exception: parameter flags that appear 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.
  • The case of the passed parameters is preserved, thus it may be used in string comparisons.

Example:

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

Note that file1.inc is included with abcd as the first parameter, bbbb as the second parameter and cccc dddd as the third parameter.

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 ;

The external file inc2.inc contains the following line:

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

The echo print in the corresponding listing file follows:

 1  Parameter a,b,c ;
 2  a = 1 ; b = 0 ; c = 2 ;
BATINCLUDE C:\tmp\inc2.inc
 4  b = sqr(a) - a ;
 5  display b ;
BATINCLUDE C:\tmp\inc2.inc
 7  b = sqr(c) - c ;
 8  display b ;
BATINCLUDE C:\tmp\inc2.inc
 10  b = sqr(a+5) - a+5 ;
 11  display b ;

Note that the option $batInclude appears three times with different arguments. GAMS is interprets the contents of the batch include file in turn as:

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

Note that the 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 are given below:

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

Observe that the third call leads to b = sqr(6)-1+5, thus the final value of b is 40. Suppose the statement in the batch include file is modified to read as follows:

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

With this modification the output generated by the display statement will be as follows:

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

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

Note
The option $batInclude without any arguments is equivalent to the option $include.

See also $include, $libInclude, $sysInclude.

$call

Syntax:

$call [=]command

This option passes a 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.

Example:

$call dir

This command creates a directory listing on a PC.

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

$call gams trnsport
$call =gams trnsport

The first call will run the model [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, will send the command directly to the system. The return codes from the system will be intercepted correctly and they will be available to the GAMS system through the errorLevel 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.
$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 may be used only 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).

See also $call.Async, $hiddenCall.

$call.Async[NC]

Syntax:

$call.Async[NC] command

$call.Async works like $call but allows asynchronous job handling. This means users may start a job command without having to wait for the result, they may continue in their model and collect the return code of the job later. The function jobHandle may be used to get the process ID (pid) of the last job started. The status of the job may be checked using the function jobStatus(pid). An interrupt signal to a running job may be sent with the function jobTerminate(pid). With the function jobKill(pid) a kill signal may be sent to a running job.

The difference between $call.Async and $call.AsyncNC is, that the latter starts processes in a new console, rather than sharing the console of the parent process.

Note
On non-Windows platforms $call.AsyncNC and $call.Async are synonyms.

$clear

Syntax:

$clear  ident {ident}

This option resets all data for the identifiers ident to their default values. Note that only the following data types may be reset: sets, parameters, variables and equations. Note further, that the clearing is carried out during compile time and not when the GAMS program executes.

Example:

Set    i  / 1*20 /; 
Scalar a  / 2 /;
$clear i a
display i, a;

The option $clear resets i and a to their default values: an empty set for i and zero for a. The output generated by the display statement follows:

----      4 SET i  
                                                      ( EMPTY )

----      4 PARAMETER a                    =        0.000  
Attention
The two-pass processing of a GAMS file may 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.
Scalar a / 12 /;
a = 5;
$clear a
display a;

Note that 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 ;

Therefore the result is that a takes the value of 5. The output from the display statement is as follows:

----      4 PARAMETER a                   =        5.000

Compare also $kill and the execution time option clear.

$clearError[s]

Syntax:

$clearError[s]

This option ($clearError and $clearErrors are synonyms) clears GAMS awareness of compiler errors and turn them into warning messages instead.

Example:

Scalar z / 11 /;
$eval x sqrt(-1)
$clearError
$log %x%
Display z;

Note that without the use of $clearError the program above would not continue with the execution after line 2.

$comment  (*)

Syntax:

$comment char

This option changes the symbol indicating a single line comment from the default * to the single character char. Note that after this option is used, the new comment character char cannot be used in column 1 as before, since it got a special meaning. Note further, that the case of the character does not matter if it is used as a comment character. This option should be used with great care and we recommend to reset the symbol quickly to the default.

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

Example:

$comment c
c now we use a FORTRAN style comment symbol
$comment *
* now we are back to the default

See also section Comments.

$compress

Syntax:

$compress source target

This option causes the file source to be compressed into the packed file target.

Example: Consider the following example where the well-known model [TRNSPORT] is used:

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

The first command retrieves the file trnsport.gms and the second command compresses it. Note that a compressed GAMS file is treated like any other GAMS file, therefore it may be included and executed as usual. Large data files that do not change often can be compressed this way to save disk space.

The following example serves as a little utility to compress and decompress files:

$ifthen set decompress
$  if not set input  $set input file_c.gms
$  if not exist %input% $abort No file input file %input% exist
$  if not set output $set output file.gms
$  log Decompressing %input% into %output%
$  decompress %input% %output%
$else
$  if not set input  $set input file.gms
$  if not exist %input% $abort No file input file %input% exist
$  if not set output $set output file_c.gms
$  log Compressing %input% into %output%
$  compress %input% %output%
$endif

The program (saved to a file called compress.gms) can be used as follows:

> gams compress.gms --input myfile.gms --output myfile_c.gms
> gams compress.gms --decompress=1 --input myfile_c.gms --output myfile.gms

See also $decompress. Further details are given in chapter Compressing and Decompressing Files.

$decompress

Syntax:

$decompress source target

This option causes the compressed file source to be decompressed into the unpacked file target.

Example: Consider the following example where the well-known model [TRNSPORT] is used:

$call gamslib trnsport
$compress trnsport.gms t2.gms
$decompress t2.gms t3.gms
$call diff t3.gms trnsport.gms
$if errorlevel 1 $abort t3.gms and trnsport.gms are not identical!

The first command retrieves the file trnsport.gms, the second command compresses it and the third command decompresses the compressed file. Note that the resulting file, t3.gms, is identical to the original file trnsport.gms which is tested via the diff program.

See also $compress. Further details are given in chapter Compressing and Decompressing Files.

$dollar   ($)

Syntax:

$dollar char

This option changes the current 'dollar' symbol to the single character char.

Note
The special %$ substitution symbol can be used to get the current 'dollar' symbol.

Example:

$dollar #
#log now we can use '%$' as the '$' symbol

$double

Syntax:

$double

The lines following this option will be echoed double spaced to the echo print in the listing file.

Example:

Set    i / 1*2 / ;
Scalar a / 1   / ;
$double
Set    j / 10*15 / ;
Scalar b / 2     / ;

The resulting echo print in the 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 option $double are listed single spaced, while the lines after the option are listed with double space.

See also $single.

$drop

Syntax:

$drop VARNAME

This option destroys (removes from the program) the scoped compile-time variable VARNAME that was defined with the dollar control option $set.

Example:

$set NAME my name
$if set NAME $log Scoped compile-time variable NAME is set to "%NAME%"
$drop NAME
$if not set NAME $log Scoped compile-time variable NAME is not available anymore

See also $set, $dropGlobal, and $dropLocal.

$dropEnv

Syntax:

$dropEnv VARNAME

This dollar control option destroys (removes from the program) the operating system environment variable VARNAME. For detailed information, see the dollar control option .

Example:

$if setEnv GDXCOMPRESS $dropEnv GDXCOMPRESS

See also $setEnv, and $if setEnv.

$dropGlobal

Syntax:

$dropGlobal VARNAME

This option destroys (removes from the program) the global compile-time variable VARNAME that was defined with the dollar control option $setGlobal.

Example:

$setGlobal NAME my name
$if setGlobal NAME $log Global compile-time variable NAME is set to "%NAME%"
$dropGlobal NAME
$if not setGlobal NAME $log Global compile-time variable NAME is not available anymore

See also $setGlobal, and $drop.

$dropLocal

Syntax:

$dropLocal VARNAME

This option destroys (removes from the program) the local compile-time variable VARNAME that was defined with the dollar control option $setLocal.

$setLocal NAME my name
$if setLocal NAME $log Local compile-time variable NAME is set to "%NAME%"
$dropLocal NAME
$if not setLocal NAME $log Local compile-time variable NAME is not available anymore

See also $setLocal, and $drop.

$echo

Syntax:

$echo text >[>] external_file

This option allows to write the text text to a file external_file. The text and the file name may both be quoted or unquoted. The file name is expanded using the working directory. The option $echo 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 an option $call or any variant of the option $include is encountered. The redirection symbols > and >> have the usual meaning of starting at the beginning or appending to an existing file respectively.

Example:

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

The content of the resulting file echo.txt is the following:

The message written goes from the first non blank
to the first > or >> symbol unless the text is
is quoted. The input File is C:\tmp\echoTest.gms. The
file name "echo.txt" will be completed with
C:\tmp\.

See also $on/offEcho, and $echoN.

$echoN

Syntax:

$echoN text >[>] external_file

This option sends a text message text to an file external_file like $echo but writes no end of line marker so the line is repeatedly appended to by subsequent commands. The redirection symbols > and >> have the usual meaning of starting at the beginning or appending to an existing file respectively. Note that the text and the file name may be quoted or unquoted. By default the file will be saved in the working directory.

Example:

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

The created file aaa.txt contains the following text:

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

See also $on/offEcho, and $echo.

$eject

Syntax:

$eject

This option advances the echo print to the next page.

Example:

$eject
Set       i,j ;
Parameter Data(i,j) ;
$eject
Scalar a;
a = 7;

The statements following the first $eject will be listed on one page in the echo print of the listing file and the statements following the second $eject will be listed on the next page.

$else

Syntax:

$ifThen[E|I] cond
  ...
{ $elseIf[E|I] cond 
  ... }
[ $else
  ... ]
$endIf

This option always appears together with the option $ifThen[E/I]. It is followed by an instruction which is executed if the conditional expression of the matching option $ifThen[E/I] is not true. For an example, see section Conditional Compilation with $ifThen and $else.

See also $ifThen, $elseIf and section Conditional Compilation.

$elseIf

Syntax:

$ifThen[E|I] cond
  ...
{ $elseIf[E|I] cond 
  ... }
[ $else
  ... ]
$endIf

This option always appears together with the option $ifThen[E/I]. It is followed by another condition and instruction. For an example, see section Conditional Compilation with $ifThen and $else.

See also $ifThen, $else, $elseIfE, $elseIfI and section Conditional Compilation.

$elseIfE

Syntax:

$ifThen[E|I] cond
  ...
{ $elseIf[E|I] cond 
  ... }
[ $else
  ... ]
$endIf

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

See also $elseIf and section Conditional Compilation.

$elseIfI

Syntax:

$ifThen[E|I] cond
  ...
{ $elseIf[E|I] cond 
  ... }
[ $else
  ... ]
$endIf

This option does the same as $elseIf but it is case insensitive.

See also $elseIf and section Conditional Compilation.

$encrypt

Syntax:

$encrypt source target

This option causes a file to be converted into an encrypted file. Here 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 the secure option to be licensed and is available for commercial licenses only. The command line parameter pLicense specifies the target license to be used for encryption. The encrypted file can only run on a system licensed with the license file used for encryption. No special action is required on the executing system since GAMS recognizes whether a file is encrypted and will process it accordingly. There is no option to decrypt an encrypted file, so better keep the original unencrypted file.

Further details and examples are given in chapter Encrypting Files.

$endIf

Syntax:

$ifThen[E|I] cond
  ...
{ $elseIf[E|I] cond 
  ... }
[ $else
  ... ]
$endIf

This must option must be matched with one of the options $ifThen, $ifThenE or $ifThenI. For an example, see section Conditional Compilation with $ifThen and $else.

See also $ifThen and section Conditional Compilation.

$eolCom (!!)

Syntax:

$eolCom char[char]

This option redefines and activates the end-of-line comment symbol, which may be one character or a sequence of two characters. By default, this is initialized to !!, but is not active. The option $onEolCom is used to activate the end-of-line comments. If $eolCom is used, $onEolCom is set automatically.

Example:

$eolCom //
Set i /1*2/ ;     // set declaration
Parameter a(i) ;  // parameter declaration

Here the character sequence // serves as the end-of-line-comment indicator.

Attention
It is not allowed to reset the end-of-line comment symbol to the current end-of-line comment symbol. This would cause an compilation error as in the following example:
$eolCom //
$eolCom //

Some end of line character settings can cause confusion. The widely used end of line character sequence // is also legal GAMS syntax in put statement to indicate two line breaks:

file fx; put fx;
put 'first line' // 'second line' //;
$eolCom //
put 'third line' // 'fourth line';

results in a put file with the following content:

first line

second line

third line

This can also confuse syntax highlighting in editors (or on thsi web page). Other popular end of line characters like # and @ are also used as GAMS syntax, see Controlling the Cursor On a Page.

See also section Comments for more about comments in GAMS.

$error

Syntax:

$error [text]

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

Example:

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

Note that the first line checks if the file myfile exists. If the file does not exist, it will generate an error with the comment File myfile not found - will continue anyway and then the compilation will continue with the next line.

See also $abort, $exit, $terminate, and $stop.

$escape

Syntax:

$escape character

This option allows users to work with text sequences containing % without substitution.

This causes all subsequent commands of the form %symbol% to not have parameter substitution done for them. As a consequence, no parameter substitutions are performed in GAMS statements (mostly useful in display and put statements) and the outcome of such statements where %symbol% is used is just %symbol%.

Note that the effect of the option $escape may be reversed with the option $escape %.

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 output generated by the display statements follows:

----      6 first DOIT

----      7 second %&tt%&

----     12 third DOIT

----     13 fourth %tt%

----     18 fifth DOIT

----     19 sixth %&tt%&

The file it.put will contain the following lines:

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

Note that this option was introduced to facilitate writing GAMS code (or command.com/cmd.exe batch scripts) from GAMS including unsubstituted compile-time variables. Text can also be written at compile-time without parameter substitution via option $on/offEchoV and at run-time via $on/offPutV.

Note
In GAMS the escape character follows the character (%) that needs to be escaped. In many other languages the escape character precedes the to be escaped character.

$eval

Syntax:

$eval VARNAME expression

This option evaluates a numerical expression at compile time and places it into a scoped compile-time variable. In turn the option $ifE may be used to do numeric testing on the value of this variable.

VARNAME is the name of a compile-time variable and expression is an expression that consists of constants, functions, operators and other compile-time variables with numerical values. Note that no whitespace is allowed in the expression which can be overcome by additional parentheses.

Example:

$eval b1 ifthen(uniform(0,1)<0.5,0,1)
$eval b2 ifthen(uniform(0,1)<0.5,0,1)
$eval b3 (%b1%)xor(%b2%)
$log b1=%b1% b2=%b2% b1 xor b2=%b3%

The first two lines use the uniform function to generate a random number between 0 and 1 and assign 0 if this number is less than 0.5 otherwise 1 via the ifthen function to the scoped compile-time variable b1 and b1. In the third line we apply the logical xor operator to b1 and b2 and store the result in b3. The parentheses are required because the more natural expression b1% xor b2% contains spaces. In the forth line we print the values and result to the log.

b1=1 b2=1 b1 xor b2=0

The expression are evaluated using IEEE nonstop arithmetic, so no evaluation errors are triggered as demonstrated in the following example:

$eval OneDividedByZero 1/0
$log 1/0=%OneDividedByZero%

This produces the following log:

1/0=+INF

The $eval and related dollar control options give access to a reduced set of GAMS functions: abs, card, ceil, cos, errorlevel, exp, fact, floor, frac, gamsrelease, gamsversion, gday, gdow, ghour, gleap, gmillisec, gminute, gmonth, gsecond, gyear, ifthen, jdate, jnow, jobhandle, jobkill, jobstatus, jobterminate, jstart, jtime, log, log10, log2, max, min, mod, numcores, pi, power, round, sameas, sign, sin, sleep, sqr, sqrt, tan, trunc, and uniform. The available operators are: +, -, *, /, ** and even ^ (integer power) which is not available in regular GAMS expression and requires the use of the function ipower. The comparison relations are <, >, <=, >=, <>, and =. The logical operators are not, and, or, xor, imp, and eqv.

The expression also allows the use of dollar on the right. In the following example we replace the ifthen function by a dollar one the right:

$eval b1 1$(uniform(0,1)>=0.5)
$eval b2 1$(uniform(0,1)>=0.5)
$eval b3 (%b1%)xor(%b2%)
$log b1=%b1% b2=%b2% b1 xor b2=%b3%

Moreover, the $eval has access to data available at compile time. The expression can access the value of scalars and for other symbols we can use the card function to access the cardinality (at this point) of the symbol. Here is an example:

Scalar ac 'Avogadro constant' / 6.0221409e+23 /;
$eval log_ac round(log10(ac))
$log round(log10(ac))=%log_ac%
Set d / d0*d%log_ac% /;
$eval card_d card(d)
$log card(d)=%card_d%

Access to individual records of symbols is not possible. The embedded code facility allows access to symbol records at compile time.

See also $evalGLobal, $evalLocal, $ifE, and $set.

$evalGlobal

Syntax:

$evalGlobal VARNAME expression

This option evaluates a numerical expression at compile time and places it into a global compile-time variable. The syntax and behavior otherwise is identical to $eval.

$evalLocal

Syntax:

$evalLocal VARNAME expression

This option evaluates a numerical expression at compile time and places it into a local compile-time variable. The syntax and behavior otherwise is identical to $eval.

$exit

Syntax:

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

Example:

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

Note that the lines following the option $exit will not be compiled.

Observe that there is a difference to the dollar control option $stop. If there is only one input file, $stop and $exit will have the same effect. If the option $exit occurs within an include file, it acts like an end-of-file on the include file. However, if the option $stop occurs within an include file, GAMS will stop reading all input.

See also $abort, $error, $terminate, and $stop.

$expose

Syntax:

$expose all | ident1 ident2 ...

This option removes all privacy restrictions from identifiers.

With explicit identifiers the privacy restrictions are removed only for the listed identifiers and with all the restrictions are removed for all identifiers. The privacy restrictions may be set with the dollar control options $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. For further information, see chapter Secure Work Files.

$funcLibIn

Syntax:

$FuncLibIn InternalLibName ExternalLibName

This makes extrinsic function libraries available to a model. InternalLibName is the internal name of the library in the GAMS code and ExternalLibName is the name of the shared library in the file system. See Using Function Libraries for more information.

$gdxIn

Syntax:

$gdxIn [GDXFileName]

This option is used in a sequence to load specified items from a GDX file. Here GDXFileName denotes the name of the GDX file (with or without the extension .gdx) and the command opens the specified GDX file for reading. The use of $gdxIn without a file name closes the currently open GDX file. The command is used in conjunction with the option $load or one of its variants.

Example:

set i,j; parameters a(i), b(j), d(i,j), f;
$gdxIn mydata.gdx
$load i j a b d f
$gdxIn

See also $load, and $gdxOut.

$gdxOut

Syntax:

$gdxOut [GDXFileName]

This option is used in a sequence to unload specified items to a GDX file at compile time. Here GDXFileName denotes the name of the GDX file (with or without the extension GDX) and the command opens the specified GDX file for writing. The use of $gdxOut without a file name closes the currently open output GDX file. The command is used in conjunction with the dollar control option $unLoad.

Example:

set i /i1*i3/; parameters a(i) /i1 3, i2 87, i3 1/;
$gdxOut mydata.gdx
$unLoad i a
$gdxIn

See also $unLoad, and $gdxIn.

$goto

Syntax:

$goto id
$label 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 $batinclude 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, jumps to the same label are restricted to a maximum of 100 times by default. This maximum may be changed with the option $maxGoto.

Example:

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

Note that GAMS will continue from line $label next after reading line $goto next. Observe that all lines in between are ignored. Therefore the final value of a in the example above will be 15.

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

See also $label, $maxGoto.

$hidden

Syntax:

$hidden text

A line starting with this option 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.

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.

Note
This option is particularly useful when the input file is encrypted.

$hiddenCall

Syntax:

$hiddenCall [=]command

This option does the same as $call but the statement is neither shown on the log nor the listing file.

$hiddenCall.Async[NC]

Syntax:

$hiddenCall.Async[NC] command

This option does the same as $call.Async[NC] but the statement is neither shown on the log nor the listing file.

$hide

Syntax:

$hide all | ident1 ident2 ...

This option hides identifiers so they cannot be displayed or computed, but they may still be used in model calculations (i.e. commands when the solve statement is executed).

With explicit identifiers the listed identifiers are hidden and with all all identifiers are hidden. These restrictions may be removed with the dollar control options expose or purge. Note that a special license file is needed for this feature to work.

For further information, see chapter Secure Work Files.

$if

Syntax:

$if [not] conditional_expression new_input_line

This dollar control option provides the greatest amount of control over conditional processing of the input file(s).

For more information on the conditional expressions allowed, details on the new_input_line and examples, see section Conditional Compilation below.

See also $ifE, $ifI, $ifThen.

$ifE

Syntax:

$ifE [not] conditional_expression new_input_line

This dollar control option does the same as the option $if but allows constant expression evaluation. The conditional_expression may take two different forms:

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

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

----      3 PARAMETER a                    =        1.000  

----      4 PARAMETER a                    =        2.000  

----      6 PARAMETER a                    =        4.000 

See also $if and section Conditional Compilation.

$ifI

Syntax:

$ifI [not] conditional_expression new_input_line

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

See also $if and section Conditional Compilation.

$ifThen

Syntax:

$ifThen[E|I] cond
  ...
{ $elseIf[E|I] cond 
  ... }
[ $else
  ... ]
$endIf

This option is a form of the option $if that controls whether a number of statements are active. The syntax for the condition is generally the same as for the option $if. Like $if, it is case sensitive. Often it is followed by one or more of the following dollar control options: $else, $elseIf, $elseIfI, $elseIfE. The option $ifThen must be matched with the option $endIf that marks the end of the construct. An example is given in section Conditional Compilation with $ifThen and $else.

Note that users may add a tag to the $ifThen and $endIf. For example, $ifThen.tagOne has to match with $endif.tagOne.

Example:

$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 will contain the following lines:

----      2 it2

----      4 it3

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

See also $if, $ifThenE, $ifThenI, $else, $elseIF and section Conditional Compilation.

$ifThenE

Syntax:

$ifThen[E|I] cond
  ...
{ $elseIf[E|I] cond 
  ... }
[ $else
  ... ]
$endIf

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

See also $ifThen and section Conditional Compilation.

$ifThenI

Syntax:

$ifThen[E|I] cond
  ...
{ $elseIf[E|I] cond 
  ... }
[ $else
  ... ]
$endIf

This option does the same as the option $ifThen but it is case insensitive.

See also $ifThen and section Conditional Compilation.

$include

Syntax:

$include external_file

This option inserts the contents of a specified text file at the location of the call. External_file is the name of the file that is included. It can be quoted or unquoted. Note that include files may be nested.

The include file names are processed in the same way like the input file. 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 search path may be extended with the command line parameter InputDir.

Note that the start of the include file is marked and the include file is echoed to the echo print in the listing file. This reference to the include file may be omitted by using the option $offInclude.

Example:

$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 the command line parameter InputDir.
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 option $onGlobal is set.

Note that details on the compilation output of include files are given in section The Include File Summary.

See also $batInclude, $libInclude, $sysInclude.

$inlineCom ( \(/* ~~ */\))

Syntax:

$inlineCom char[char] char[char]

This option redefines and activates the in-line comment symbols. These symbols are placed at the beginning and the end of the in-line comment and are one character or a two character sequence at the beginning and the end. By default, the system is initialized to ' \(/*\)' and ' \(*/\)', but is not active. The option $onInline is used to activate the in-line comments. If $inlineCom is used, $onInline is set automatically.

Example:

$inlineCom {{ }}
Set {{ this is an inline comment }} i / 1*2 / ;

Note that the character pairs {{ }} serve as the indicator for in-line comments.

Attention
It is not allowed to reset the option $inlineCom to the current symbol for in-line comments. This would cause an compilation error as in the following example:
$inlinecom {{  }}
$inlinecom {{  }}
Note
The option $onNestCom enables the use of nested comments.

See also section Comments.

$kill

Syntax:

$kill ident {ident}

This option removes all data for the identifiers ident, only the type and dimension are retained (this means that these identifiers will be declared but not defined anymore). Note that only the data of the following data types may be removed: sets, parameters, variables and equations. Note further that the data removal is carried out during compile time and not when the GAMS program executes.

Example:

Set i / 1*20 /; 
Scalar a /2/;
$kill i a

Note that the effect of the third line above is that all data from a and i is removed, so the set i and the scalar a are declared, but not initialized or assigned to. Note that after i and a have been killed, a display statement for them will trigger an error. However, new data may be assigned to identifiers that were previously killed. Thus the following statements are valid if appended to the code above:

Set i / i1 *i3 /;
a = 7;

Observe that this option needs to be distinguished from the dollar control option $clear, that resets the data to the default values.

$label

Syntax:

$goto id
$label id

This option marks a line to be jumped to by a dollar control option $goto. Any number of labels may 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.

Example:

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

When GAMS reaches the line $goto next, it continues from the line $label next. All lines in between are ignored. Therefore in the example above, the final value of a is 15.

Attention
If several dollar control options appear in one line and label is one of them, then label must be listed first.

See also $goto, $maxGoto.

$libInclude

Syntax:

$libInclude external_file {arg}

This option is mostly equivalent to the option $batInclude. 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 directory inclib in the GAMS system directory. Note that the default directory may be reset with the command line parameter ldir.

Example:

$libInclude abc x y

This call will first look for the include file [GAMS System Directory]/inclib/abc. If this file does not exist GAMS will looks for the file [GAMS System Directory]/inclib/abc.gms. The arguments x and y are passed on to the include file and are interpreted as explained in the detailed description of the option $batInclude.

See also $include, $batInclude, $sysInclude.

$lines

Syntax:

$lines n

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

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

Syntax:

$load [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]

This option is preceded and succeeded by the option $gdxIn that open the GDX file for reading. The option $load loads specified items from the GDX file. Note that more than one instance of $load may occur. A listing of the GDX file contents will be created if the option $load is not followed by arguments.

Examples

Consider the following example, where transsol is the GDX file of the transportation model [TRNSPORT]

$gdxIn transsol
$load
Sets i, j; Parameters a(i), b(j), d(i,j), f;
$load i j a b d f
$gdxIn

A comma between the symbols is optional. The follow example works identically:

$gdxIn transsol
$load
Sets i, j; Parameters a(i), b(j), d(i,j), f;
$load i, j, a, b, d, f
$gdxIn

The $load without any arguments produces a table of contents of the GDX container in the listing file:

Content of GDX C:\Users\default\Documents\gamsdir\projdir\transsol.gdx
               5 UELs

    Number Type       Dim       Count  Name
         1 Set          1           2  i           canning plants
         2 Set          1           3  j           markets
         3 Parameter    1           2  a(i)        capacity of plant i in cases
         4 Parameter    1           3  b(j)        demand at market j in cases
         5 Parameter    2           6  d(i,j)      distance in thousands of miles
         6 Parameter    0           1  f           freight in dollars per case per thousand miles
         7 Parameter    2           6  c(i,j)      transport cost in thousands of dollars per case
         8 Variable     2           6  x(i,j)      shipment quantities in cases
         9 Variable     0           1  z           total transportation costs in thousands of dollars
        10 Equation     0           1  cost        define objective function
        11 Equation     1           2  supply(i)   observe supply limit at plant i
        12 Equation     1           3  demand(j)   satisfy demand at market j

Symbols may be loaded with new names with the following syntax: $load i=gdx_i j=j_gdx. The universal set may be loaded using $load uni=*.

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

This results in a display of all used labels:

----      5 SET uni 
Seattle  ,    San-Diego,    New-York ,    Chicago  ,    Topeka   

The syntax sym<[=]GDXSym[.dimI] allows to load a one dimensional set from from a symbol in the GDX file that has even a higher dimensionality. GAMS tries to find the set sym as a domain in the symbol GDXSym and uses the labels from this index position (with < the first domain set from the right and with <= from the left). If no domain information is stored in the GDX file or the domain information does not match the suffix .dimI allows to pick a fixed index position.

In the following we work with a GDX file created by the following code:

set i / i1*i3 /, ii(i,i) / i1.i2, i2.i3 /;
$gdxOut ii
$unLoad i ii
$gdxOut

Now use use this GDX file to load the first and second index from ii:

set i, i1;
$gdxIn ii
* Load first index from ii as i
$load i<=ii i1<ii.dim1
display i, i1;

the display lists all labels from the first index of ii:

----      5 SET i  Domain loaded from ii position 1
i1,    i2

----      5 SET i1  Domain loaded from ii position 1
i1,    i2

Now we match from the right and get the second index of ii:

set i, i2;
$gdxIn ii
* Load second index from ii as i
$load i<ii i2<ii.dim2
display i, i2;

The resulting listing file will contain the following lines:

----      5 SET i  Domain loaded from ii position 2
i2,    i3

----      5 SET i2  Domain loaded from ii position 2
i2,    i3

This type of projection loading can be useful to extract the domain sets from a single parameter that is stored in a GDX file:

set i,j,k; parameter data(i,j,k);
$gdxIn data
$load i<data.dim1 j<data.dim2 k<data.dim3 data
Attention
Loading an item that was already initialized will cause a compilation error.

For example, the following code snippet will cause a compilation error:

Set j / 1*5 /;
$gdxIn transsol
$load j
$gdxIn 

Note that GAMS offers variants of $load that do not cause a compilation error in such a case: $loadM and $loadR.

$loadDC

Syntax:

$loadDC [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]

This option is an alternative form of $load. It performs domain checking when items are loaded. Any domain violations will be reported and flagged as compilation errors. All other features are the same as discussed under $load .

Example: Consider the following example where transsol is the GDX file of the transportation model [TRNSPORT].

Set i, j;
Parameter b(i), a(j);
$gdxIn transsol
$load i b
$loadDC j a
$gdxIn

Note that in contrast to the example above, the parameter a is indexed over the set i and the parameter b is indexed over the set j in the file transsol. While $load i b does not generate an error and b is just empty, the option $loadDC j a triggers a domain violation error because in transsol a is indexed over i and produces a list of errors in the listing file:

--- LOAD  a = 3:a
**** Unique domain errors for symbol a
 Dim  Elements
   1  seattle, san-diego

   5  $loadDC j a
****            $649

$loadDCM

Syntax:

$loadDCM [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]

This option combines the functionality of merging as in $loadM and domain checking as in $loadDC.

Example:

Consider the following example where transsol is the GDX file of the transportation model [TRNSPORT].

Set i, uni 'all labels';
Parameter abFail(i), ab(uni) 'capacity and demand';
$gdxIn transsol
$load i abFail=a
$loadDCM abFail=b
$loadDCM uni=i uni=j ab=a ab=b
$gdxIn
display uni, ab;

Here we try to merge parameters a and b together into one parameter. The first attempt (to merge it into parameter abFail) would fail because of line 5 and result into a domain violation report as described with dollar control option $loadDC. In the second attempt we first merge the sets i and j into set uni and then merge the parameters a and b into ab. If one comments line 5 the resulting display looks as follows:

----      8 SET uni  all labels
seattle  ,    san-diego,    new-york ,    chicago  ,    topeka   

----      8 PARAMETER ab  capacity and demand
seattle   350.000,    san-diego 600.000,    new-york  325.000
chicago   300.000,    topeka    275.000

$loadDCR

Syntax:

$loadDCR [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]

This option combines the functionality of replacing data as in $loadR and domain checking as in $loadDC.

Example:

Consider the following example where transsol is the GDX file of the transportation model [TRNSPORT].

Set uni 'all labels';
Parameter ab(uni) 'capacity and demand';
$gdxIn transsol
$loadM uni=i uni=j ab=a
$loadDCR ab=b
$gdxIn
display uni, ab;

Here we try to read twice into the parameter ab. First GDX symbol a and b are read into ab. GDX symbol b is read with replace and hence the parameter ab contains the elements of b only.

$loadM

Syntax:

$loadM [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]

This option is an alternative form of $load. Instead of replacing an item or causing a symbol redefined error if the item was already initialized it merges the contents. Records that would result in domain violations will be ignored.

Example:

Consider the following example where transsol is the GDX file of the transportation model [TRNSPORT].

Set i, uni 'all labels';
Parameter ab(uni) 'capacity and demand';
$gdxIn transsol
$loadM uni=i uni=j ab=a ab=b
$gdxIn
display uni, ab;

Here we merge parameters a and b together into one parameter ab. We first merge the sets i and j into set uni and then merge the parameters a and b into ab. The resulting display looks as follows:

----      6 SET uni  all labels
seattle  ,    san-diego,    new-york ,    chicago  ,    topeka   

----      6 PARAMETER ab  capacity and demand
seattle   350.000,    san-diego 600.000,    new-york  325.000
chicago   300.000,    topeka    275.000

$loadR

Syntax:

$loadR [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]

This option is a variant of the option $load. With $loadR we can have multiple loads into the same symbols and the data stored in GAMS will be replaced with the one from the GDX container.

Example:

Consider the following example, where transsol is the GDX file of the transportation model [TRNSPORT]:

Sets i  / 1*3 /
     j  / 1*2 /;
$gdxIn transsol
$loadR i j
$gdxIn
display i, j;

The resulting listing file will contain the following lines:

----      6 SET i  canning plants
Seattle  ,    San-Diego

----      6 SET j  markets
New-York,    Chicago ,    Topeka  

$log

Syntax:

$log text

This option will send a message text to the log file. Recall that by default, the log file is the console. The default log file may be reset with the command line parameters logOption and logFile.

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

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 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 will contain the following lines:

The following message will be written to the log file
with leading blanks ignored. All special % symbols will
be substituted before this text is sent to the log file.
This was line 5 of file C:\tmp\logTest.gms

Note that %system.incLine% is replaced by 5 which is the line number where the string replacement was requested. Note further that %system.incName% is substituted with the name of the file completed with the absolute path. Observe that the leading blanks on the second line of the example are ignored.

$macro

Syntax:

$macro name(arg1,arg2,arg3, ...) macro_body

This option defines a macro in GAMS. Here name is the name of the macro, arg1,arg2,arg3,... are the arguments and macro_body defines what the macro should do. The macro names follow the rules for identifiers. The macro name cannot be used for other symbols. For further details and examples, see section Macros in GAMS below.

$maxCol    (80001)

Syntax:

$maxCol n

This option restricts the valid range of input columns at the right margin. Note that all input after column n is treated as comment, therefore it is ignored.

Example:

$maxCol 30
Set    i  / vienna, rome /;   set definition
Scalar a  / 2.3          /;   scalar definition

Observe that the text strings set definition and scalar definition are treated as comments and are 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 following message:

NEW MARGINS: 20-110
Note
  • 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.

See also $on/offMargin and section Comments.

$maxGoto 100

Syntax:

$maxGoTo n

This option sets the maximum number of jumps to the same label and is used in the context of the options $goTo and $label. Once the maximum number is reached a compilation error is triggered. Such a limit has been implemented to avoid infinite loops at compile time.

Example:

Scalar a / 1 /;
$maxGoTo 5
$label label1
a = a+10;
display a ;
$goTo label1

Note that a compilation error is triggered if $goTo label1 is called for the fifth time.

$minCol    (1)

Syntax:

$minCol n

This option restricts the valid range of input columns at the left margin. Note that all input before column n is treated as comment, therefore it is ignored.

Example:

$minCol 30
Set definition               Set    i / vienna, rome /;
Scalar definition            Scalar a / 2.3          /;

Observe that the text strings set definition and scalar definition are treated as comments and are ignored since they are placed before column 30.

Any changes in the margins via the option $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 MARGINS: 20-110
Attention
GAMS requires that the left margin set by the option $minCol is smaller than the right margin set by the option $maxCol.

See also $on/offMargin and section Comments.

$[on][off]Delim    ($offDelim)

Syntax:

$onDelim
$offDelim

This option controls whether data in table statements may be entered in comma delimited format.

Example:

Sets  plant  'plant locations' / NEWYORK, CHICAGO, LOSANGELES /
      market 'demands'         / MIAMI, HOUSTON, PORTLAND     /;

Table dist(plant,market)
$onDelim
,MIAMI,HOUSTON,PORTLAND
NEWYORK,1300,1800,1100
CHICAGO,2200,1300,700
LOSANGELES,3700,2400,2500
$offDelim
;

Display dist;

The resulting listing file will contain the following output:

----     12 PARAMETER dist

               MIAMI     HOUSTON    PORTLAND

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

$[on][off]Digit    ($onDigit)

Syntax:

$onDigit
$offDigit

This option controls the precision check on numbers. Computers work with different internal precision. To have the same behavior on all supported platforms, GAMS does not accept numbers with more than 16 significant digits on input. Sometimes one needs to work with input values with more digits, e.g., if the data is generated from some source, which is out if the users control. Instead of changing numbers with too much precision, the option $offDigit instructs GAMS to use as much precision as possible and ignore the rest of the number.

Example:

Parameter y(*)   / toolarge 12345678901234.5678
$offDigit
                   ignored  12345678901234.5678  /;

The resulting listing file will contain the following lines:

    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 line containing the option $offDigit, y("ignored") is accepted without any errors even though there are more than 16 significant digits.

$[on][off]Dollar    ($offDollar)

Syntax:

$onDollar
$offDollar

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

Example:

$hidden This line will not be displayed
$onDollar
$hidden This line will be displayed
$offDollar
$hidden This line will not be displayed

The compilation output of the resulting listing file will contain the following lines:

2  $onDollar
3  $hidden This line will be displayed

Note that all lines between the option $onDollar and the option $offDollar are echoed in the listing file. Note further that the effect of this option is immediate: the line $onDollar is echoed in the listing file, while the line $offDollar is not.

$[on][off]DotL ($offDotL)

Syntax:

$onDotL
$offDotL

This option activates or deactivates the automatic addition of the attribute .L to variables on the right-hand side of assignments. It is most useful in the context of macros. For further information, see section Macros in GAMS below.

$[on][off]DotScale ($offDotScale)

Syntax:

$onDotScale
$offDotScale

This option activates or deactivates the automatic addition of the attribute .Scale to variables and equations on the right-hand side of assignments. As with on|offDotL It is most useful in the context of macros. For further information, see section Macros in GAMS below.

$[on][off]Echo[S][V]

Syntax:

$onEcho[S|V]  >[>] external_file
text
{text}
$offEcho

This option is used to send one or more lines of text to an file external_file. The text and the file name may be quoted or unquoted. The external file is not closed until the end of the compilation or when the option $call or any variant of the option $include is encountered. Note that the redirection symbols > and >> have the usual meaning: > creates a new file and writes to it or - in case there exists already a file with the respective name - overwrites the existing file and >> appends to a file. Note further that parameter substitutions are permitted with $onEcho. The option $onEcho has two more variants: $onEchoS and $onEchoV. $onEchoS allows parameter substitutions like $onEcho, so it is just a synonym which makes it more obvious that parameter substitution is allowed with the appended S. The option $onEchoV does not allow parameter substitutions but writes the text verbatim.

Example:

$set it TEST
$onEchoS  > externalfile1.txt
send %it% to external file
line 2 to send
$offEcho

$onEchoV  > externalfile2.txt
send %it% to external file
line 2 to send
$offEcho

The externalfile1.txt will contain the following lines:

send TEST to external file
line 2 to send

The externalfile2.txt will contain these lines:

send %it% to external file
line 2 to send

Observe that in the first case %it% is substituted with TEST, but in the second case there is no substitution.

Note that by default the external file will be placed in the current working directory if there is no path specified.

See also options $echo, and $echoN.

$[on][off]Embedded    ($offEmbedded)

Syntax:

$onEmbedded
$offEmbedded

This option enables or disables the use of embedded values in parameter and set data statements. If enabled, the explanatory text for set elements is concatenated with blank separators. For parameters, the embedded values get multiplied.

Example:

Set k / a,b /
    l / a   /;
Set       i(k,l) / a.a 'aaaa cccc dddd'
                   b.a 'bbbb cccc dddd' /;
Parameter m(k,l) / a.a 12
                   b.a 24 /;
$onEmbedded
Set       j(k,l) / (a aaaa, b bbbb).(a cccc) dddd /;
Parameter n(k,l) / (a 1,    b 2)   .(a 3)    4    /;

Note that the explanatory text of the set elements in i and j as well as the values of the parameters m and n are identical.

$[on][off]EmbeddedCode[S][V]

Syntax:

$onEmbeddedCode[S|V] Python: [arguments]
Python code
{Python code}
$offEmbeddedCode {output symbol}

This option is used to execute one or more lines of Python code while GAMS stays alive. The Python code has access to GAMS symbols and can read and change them.

Note that parameter substitutions are permitted with $onEmbeddedCode. The option $onEmbeddedCode has two more variants: $onEmbeddedCodeS and $onEmbeddedCodeV. $onEmbeddedCodeS allows parameter substitutions like $onEmbeddedCode, so it is just a synonym which makes it more obvious that parameter substitution is allowed with the appended S. The option $onEmbeddedCodeV does not allow parameter substitutions but passes the code verbatim to the Python interpreter. The optional arguments given to $onEmbeddedCode[S|V] can be accessed in the Python code.

$offEmbeddedCode can be followed by a GAMS symbol or a list of GAMS symbols. If GAMS symbols are specified they get updated in the GAMS database after the Python code got executed.

Example:

Set cc      / "France - Paris", "France - Lille", "France - Toulouse"
              "Spain - Madrid", "Spain - Cordoba", "Spain - Seville", "Spain - Bilbao"
              "USA - Washington DC", "USA - Houston", "USA - New York",
              "Germany - Berlin", "Germany - Munich", "Germany - Bonn" /
    country / system.empty /
    city    / system.empty /
    mccCountry(cc,country)
    mccCity(cc,city);
    
$onEmbeddedCode Python:
  mccCountry = []
  mccCity = []
  country = set()
  city = set()
  for cc in gams.get("cc"):
    r = str.split(cc, " - ", 1)
    mccCountry.append((cc,r[0]))
    mccCity.append((cc,r[1]))
    country.add(r[0])
    city.add(r[1])
  gams.set("country",list(country))
  gams.set("city",list(city))
  gams.set("mccCountry",mccCountry)
  gams.set("mccCity",mccCity)
$offEmbeddedCode country city mccCountry mccCity

Option mccCountry:0:0:1, mccCity:0:0:1;
Display country, city, mccCountry ,mccCity;

This will be in the listing file:

----     28 SET country  

Spain  ,    USA    ,    France ,    Germany


----     28 SET city  

Washington DC,    Toulouse     ,    Berlin       ,    Munich       
Houston      ,    Madrid       ,    New York     ,    Seville      
Paris        ,    Bilbao       ,    Lille        ,    Bonn         
Cordoba      


----     28 SET mccCountry  

France - Paris     .France 
France - Lille     .France 
France - Toulouse  .France 
Spain - Madrid     .Spain  
Spain - Cordoba    .Spain  
Spain - Seville    .Spain  
Spain - Bilbao     .Spain  
USA - Washington DC.USA    
USA - Houston      .USA    
USA - New York     .USA    
Germany - Berlin   .Germany
Germany - Munich   .Germany
Germany - Bonn     .Germany


----     28 SET mccCity  

France - Paris     .Paris        
France - Lille     .Lille        
France - Toulouse  .Toulouse     
Spain - Madrid     .Madrid       
Spain - Cordoba    .Cordoba      
Spain - Seville    .Seville      
Spain - Bilbao     .Bilbao       
USA - Washington DC.Washington DC
USA - Houston      .Houston      
USA - New York     .New York     
Germany - Berlin   .Berlin       
Germany - Munich   .Munich       
Germany - Bonn     .Bonn   

See also chapter Embedded Code Facility for more details.

$[on][off]Empty    ($offEmpty)

Syntax:

$onEmpty
$offEmpty

Setting $onEmpty allows empty data statements for list or table formats. Note that by default, empty data statements will cause a compilation error.

Example:

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) "headers only"
     1   2   3
;

The resulting listing file will contain the following lines:

   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) "headers only"
  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

Empty data statements are most likely to occur when data is being entered into the GAMS model by an external program. This problem may be overcome with the option $onEmpty.

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

The option $onEmpty in conjunction with the option $onMulti and the save and restart feature may be used to set up a model and add data later.

$[on][off]End    ($offEnd)

Syntax:

$onEnd
$offEnd

This option offers an alternative syntax for flow control statements. The option $onEnd causes the following words to be regarded as keywords: do, endLoop, endIf, endFor and endWhile. They are used to close the language constructs loop, if, for and while respectively.

Example:

Note
The standard syntax is given as an end-of-line comment.
Set       i    / 1*3 /;
Scalar    cond / 0 /;
Parameter a(i) / 1 1.23, 2 2.65, 3 1.34/;

$eolCom //
$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 > 3 do                        // while (cond > 3,
  a(i) = a(i) / 2;                       //   a(i) = a(i) / 2;
  cond = cond-1;                         //   cond = cond-1;
endWhile;                                // );

Observe that the alternative syntax is more in line with the syntax used in some of the popular programming languages.

Attention
Setting the option $onEnd will make the alternative syntax valid, and at the same time it will make the standard syntax invalid. Therefore the two forms of the syntax will never be valid simultaneously.

$[on][off]EolCom ($offEolCom)

Syntax:

$onEolCom
$offEolCom

This option acts as a switch to control the use of end-of-line comments. Note that by default, the end-of-line comment symbol is set to !! but the processing is disabled.

Example:

$onEolCom
Set       i    /1*2/ ;  !! set declaration
Parameter a(i)       ;  !! parameter declaration

Observe that after the option $onEolCom has been specified, comments may be entered on the same line as GAMS code.

Note
The option $eolCom automatically sets $onEolCom.

See also section Comments.

$[on][off]Eps    ($offEps)

Syntax:

$onEps
$offEps

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

Example:

Set       i    / one, two, three, four /;
Parameter a(i) /
$oneps
      one     0
$offeps
      two     0
      three   EPS   /;
Display a ;

The outcome generated by the display statement follows:

----      8 PARAMETER a

one   EPS,    three EPS

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

$[on][off]Expand ($offExpand)

Syntax:

$onExpand
$offExpand

This option changes the processing of macros that appear 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.

Example:

variable x(*,*);
$macro  f(i)   sum(q, x(i,q))
$macro equ(x)  equation equ_&x; equ_&x.. &x =e= 0;
equ(f(i))

The macro expansion of the code above will result in an equation definition that reads as follows:

equation equ_f(I); equ_f(i).. f(i) =e= 0;

If we compile the code under $onExpand the argument f(i) is expanded before the macro equ() gets expanding resulting in the following (incorrect) code:

equation equ_sum(q, x(i,q)); equ_sum(q, x(i,q)).. sum(q, x(i,q)) =e= 0;

For further information, see section Macros in GAMS below.

$[on][off]Global    ($offGlobal)

Syntax:

$onGlobal
$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 the options of the parent file as well.

Example:

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

The file inc.inc contains the following lines:

$onDollar
$hidden text inside include file

The the echo print of the resulting listing file 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 dollar control option $onDollar inside the include file does not affect the parent file until $onGlobal is set. The text following the option $hidden is then echoed to the listing file.

$[on][off]Include    ($onInclude)

Syntax:

$onInclude
$offInclude

This option controls the listing of the expanded include file name in the listing file.

Example:

$include 'inc.inc'
$offInclude
$include 'inc.inc'

We assume that the file inc.inc contains the following lines:

$onDollar
$hidden Text inside include file

The resulting listing file will contain the following lines:

INCLUDE    C:\tmp\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 has been set.

$[on][off]Inline    ($offInline)

Syntax:

$onInline
$offInline

This option acts as switch to control the use of in-line comments. Note that by default, the in-line comment symbols are set to the two character pairs \(/*\) and \(*/\) but the processing is disabled. In-line comments may span several lines till the end-of-comment characters are encountered.

Example:

$onInline
Set i /* The default comment symbols are now
         active. These comments can continue
         to additional lines till the closing
         comments are found.  */ / i1*i3 / ;
Note
  • The option $inlineCom automatically sets $onInline.
  • Nested in-line comments are illegal unless the option $onNestCom is set.

See also section Comments.

$[on][off]Listing    ($onListing)

Syntax:

$onListing
$offListing

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

Example:

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 will contain the following lines:

    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 options $offListing and $onListing are not echoed to the listing file.

Note
For some projects the listing file can become huge and can take significant time to be written. This time can be saved by setting $offListing at the beginning of the input file and $onListing just before the parts one is interested in, or not at all, if one does not look at the listing file anyway.

$[on][off]Local ($onLocal)

Syntax:

$onLocal
$offLocal

The suffix .local attached to the name of a controlling set will use an implicit alias within the scope of the indexed operation or on the left-hand side of an assignment statement. This feature is particularly useful in the context of nested macros.

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 p(i);
p(i.local) = sum(j, xxx(i,j)); 
display p;

Note that in the assignment statement the set i on the right-hand side is controlled by i.local on the left-hand side. Thus we have the following values for the two parameters:

----      3 PARAMETER xxx  
            1           2           3
1       1.000                  13.000
2                   2.000
3      31.000                   3.000

----      7 PARAMETER p  
1 14.000,    2  2.000,    3 34.000

In the example above, the suffix .local appeared one time on the left-hand side. The option $onLocal allows the suffix .local to appear more that one time attached to the same symbol. Consider the following example that extends the example above:

Parameter g(i,i);
g(i.local-1,i.local) = xxx(i,i);   
display g;

Note that in the assignment statement of g the suffix .local attached to the set i appears two times on the left-hand side. The question arises whether the reference to the set i on the right-hand side refers to the first or the second instance of .local on the left-hand side. The assignment statement may alternatively be written in the following way using an explicit alias statement:

alias (i,i1,i2);
g(i1-1,i2) = xxx(i2,i2); 

Thus is becomes clear that the symbol on the right-hand side refers to the controlling index that enters last (here the second one). The output generated by the display statement follows:

----      10 PARAMETER g  
            1           2           3
1       1.000       2.000       3.000
2       1.000       2.000       3.000

Observe that the multiple use of the suffix .local on the same symbol is considered an error with the option $offLocal.

Note that it is also allowed to combine the original index with an index suffixed with .local. Consider the following alternative formulation:

g(i.local-1,i) = xxx(i,i); 

Note that in this case the index suffixed with .local takes precedence and the reference of i on the right-hand side refers to the index i.local even though i is entered last. Observe that this statement even works with $offLocal as the suffix .local appears only once.

See also section Macros in GAMS below.

$[on][off]Log    ($onLog)

Syntax:

$onLog
$offLog

This option acts as a switch that controls logging information about the line number and memory consumption during compilation. This is scoped like the option $on/offListing applying only to included files and any subsequent included files but reverting to the setting $onLog in the parent files (if it was not changed there as well).

Example:

Set i /i1*i20000000/;
$include inc.inc
Set l /l1*l20000000/;

The file inc.inc looks like this:

Set j /j1*j20000000/;
$offLog
Set k /k1*k20000000/;

The generated log will contain the following lines:

--- test.gms(1) 1602 Mb  5 secs
--- test.gms(2) 1602 Mb
--- .inc.inc(1) 3122 Mb  6 secs
--- test.gms(3) 6161 Mb  14 secs

Note that the first line of both the parent and the include file got logged, but not the third line of the include file, after $offLog was set. The last line of the parent file got logged again.

$[on][off]Macro ($onMacro)

Syntax:

$onMacro
$offMacro

Enables or disables the expansion of macros defined by $macro.

Example:

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

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

$[on][off]Margin    ($offMargin)

Syntax:

$onMargin
$offMargin

This option controls margin marking, that means if margins set by the options $minCol and $maxCol, should be marked in the lst file.

Example:

$onmargin mincol 20 maxcol 51
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

The lst file will contain this:

   2 Now we have        |Set       i "plant" / US, UK /; |This defines I
   3 turned on the      |Scalar    x         / 3.145  /; |A scalar example.
   4 margin marking.    |Parameter a, b;                 |Define some
   5                    |                                |parameters.

Note that any statements between columns 1 and 19 and any input beyond column 52 are treated as comments. These margins are marked with | on the left and right.

See also section Comments.

$[on][off]Multi ($offMulti)

Syntax:

$onMulti
$offMulti

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

Example:

Consider the following slice of code. The list after the end of line comment describes the complete content of the symbol x after the data statement has been processed:

$eolCom //
Set i / i1*i10 /;
Parameter x(i) / i1*i3  1 /   // /i1 1,i2 1,i3 1/
$onMulti
Parameter x(i) / i7*i9  2 /   // /i1 1,i2 1,i3 1,i7 2,i8 2,i9 2/
Parameter x(i) / i2*i6  3 /   // /i1 1,i2 3,i3 3,i4 3,i5 3,i6 3,i7 2,i8 2,i9 2/
Parameter x(i) / i3*i5  0 /   // /i1 1,i2 3,i6 3,i7 2,i8 2,i9 2/
$offMulti
display x;

Note that the repeated parameter statements would have resulted in a compilation error without the presence of the option $onMulti. The result of the display statement in the listing file 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("i1") is assigned the value of 1 with the first data and is not affected by any of the subsequent data statements. x("i3") on the other hand is reset to 3 by the third data statement and wiped out with 0 in the fourth data statement.

Attention
The two-pass processing of a GAMS file may lead to seemingly unexpected results. Dollar control options and data initialization are both done in the first pass and assignments in the second, irrespective of their relative locations. This is an issue particularly with the option $onMulti since it allows data initializations to be performed more than once. See section GAMS Compile Time and Execution Time Phase for details.

Consider the following example:

Scalar a /12/;
a=a+1;
$onMulti
Scalar a /20/;
display a;

Note that the two scalar data initialization statements and the option $onMulti are processed before the assignment statement a=a+1. As a result, the final value of a will be 21. The output of the display statement follows:

----      5 PARAMETER a                   =       21.000

Observe that the option $onEmpty in conjunction with the option $onMulti and the save and restart feature may be used to set up a model and add data later. See example in section Advanced Separation of Model and Data for details.

$[on][off]NestCom    ($offNestCom)

Syntax:

$onNestCom
$offNestCom

This option controls nested in-line comments. It makes sure that the open-comment and close-comment characters match.

Example:

$inlineCom { } onNestCom
  { nesting is now possible in comments { braces
    have to match } }

See also $inlineCom, $onInline and section Comments.

$[on][off]Order ($onOrder)

Syntax:

$onOrder
$offOrder

Lag and lead operations and the ord function require the referenced set to be ordered and constant. In some special cases users might want to use those operations 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.

Example:

Set       t1    / 1987, 1988, 1989, 1990, 1991 /
          t2    / 1983, 1984, 1985, 1986, 1987 /;
Parameter p(t2);
$offOrder
p(t2) = ord(t2);
display t2,p;

Without the $offOrder the compilation of the line p(t2) = ord(t2); would have triggered a compilation error. The ordinal numbers assigned here are probably not what one expects. The element 1987 gets ordinal number 1 although it seems to be last last in the set. The ordinal numbers are assigned in the order the set is stored internally in GAMS. This order is also used when displaying the set t2:

----      6 SET t2  
1987,    1983,    1984,    1985,    1986

----      6 PARAMETER p  
1987 1.000,    1983 2.000,    1984 3.000,    1985 4.000,    1986 5.000

$[on][off]Put[S][V]

Syntax:

File myputfile;
put myputfile;
$onPut[S|V]
text
{text}
$offPut

The pair $onPut[S|V] - $offPut causes a block of text to be placed in a put file at run-time. The is one of the few dollar control options that operate at run time. The $ in the first column usually indicates action at compile time.

Note that parameter substitutions are not permitted with $onPut. The option $onPut has two more variants: $onPutS and $onPutV. $onPutS allows parameter substitutions while the option $onPutV does not allow parameter substitutions, like $onPut, so it is just a synonym which makes it more obvious that the text is written verbatim with the appended V.

Example:

$set it TEST
File myputfile;
put myputfile;
$onPutS
Line 1 of text "%it%"
Line 2 of text %it%
$offPut

This code generates the put file myputfile.put with the following content:

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

Note that the compile-time variable %it% was replaced by TEST. However, if the option $onPutV is used instead, then %it% will not be substituted:

$set it TEST
File myputfile
put myputfile
$onPutV
Line 1 of text "%it%"
Line 2 of text %it%
$offPut

The resulting file myputfile.put will contain the following lines:

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

$[on][off]Recurse ($offRecurse)

Syntax:

$onRecurse
$offRecurse

This option controls whether it is permitted for a file to include itself.

Example:

The following GAMS program result in a recursive inclusion of the program itself:

$onRecurse
$include "%gams.input%"

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

In the following example that prints a string and then the reverse string the nesting level is less that 40 and one get some kind of recursion at compile time:

$onEchoV > reverse.gms
$ifthene %1=%3+1
  put ' '
$ exit
$endif
loop(map(chars,code)$(code.val=ord("%2",%1)), put chars.tl:0);
$eval posPlus1 %1+1
$batInclude reverse %posPlus1% %2 %3
loop(map(chars,code)$(code.val=ord("%2",%1)), put chars.tl:0);
$offEcho

set chars / A*Z /, code / 65*90 /, map(chars,code) / #chars:#code /;
file fx /''/; put fx;
$onRecurse
$batInclude reverse 1 RACECAR 7
put /;
$batInclude reverse 1 LAGER 5

The log will print the following lines:

--- Starting execution: elapsed 0:00:00.067
RACECAR RACECAR
LAGER REGAL
*** Status: Normal completion

$[on][off]StrictSingleton ($onStrictSingleton)

Syntax:

$onStrictSingleton
$offStrictSingleton

If the option $onStrictSingleton is active, a compilation error is triggered if a data statement for a singleton set contains more than one element. After activating the option $offStrictSingleton GAMS will take the first element of a singleton set that was declared with multiple elements as the valid element, the other elements are disregarded and there is no error. The option to control this behavior at runtime is strictSingleton.

Example:

The first element is not always the one that appears in the data statement first as the following example shows:

set i /1,2/
$offStrictSingleton
singleton set ii(i) /2,1/;
display ii;

The set ii contains the element 1 because it is the first in the GAMS label order as the display statements shows:

----      4 SET ii  
1

$[on][off]SymList    ($offSymList)

Syntax:

$onSymList
$offSymList

This option controls whether the symbol listing map appears in the compilation output of the listing file. The symbol listing map contains the complete listing of all symbols that have been defined and their explanatory text. The entries are in alphabetical order and grouped by symbol type.

Example:

The symbol listing map 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     

This serves as a simple description of the symbols used in a model and may be used in reports and other documentation. For further information, see section The Symbol Listing Map.

$[on][off]SymXRef    ($offSymXRef)

Syntax:

$onSymXRef
$offSymXRef

This option controls the following:

  • Collection of cross references for symbols like sets, parameters, variables, acronyms, equations, models and put files.
  • Symbol cross reference report of all collected symbols in the compilation output of the listing file. For details, see section The Symbol Reference Map.
  • Listing of all referenced symbols and their explanatory text by symbol type in listing file. This listing may also be activated with the option $onSymList.

Example:

$onSymXRef
Set i / 1*6 /, k;
$offSymXRef
Set j(i) "will not show" / 1*3 /;
$onSymXRef
k('1') = yes;

The resulting listing file will contain the following symbol reference map and symbol listing map:

SYMBOL      TYPE   REFERENCES

i            SET   declared        2  defined        2
k            SET   declared        2 assigned        6

SETS      

i             
k  

Note that the set j does not appear in these listings because the listing was deactivated with the option $offSymXRef in line 3 of the code above.

$[on][off]Text

Syntax:

$onText
$offText

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

Example:

* 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 echo print of the resulting listing file will contain the following lines:

    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.

See also section Comments.

$[on][off]UElList ($offUElList)

Syntax:

$onUElList
$offUElList

This option controls the complete listing of all set elements that have been entered in the compilation output of the listing file. For details see section The Unique Element Listing Map.

Example:

The unique element listing in the listing file generated by running the model [TRNSPORT] with $onUElList 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. For more information, see section Ordered and Unordered Sets.

$[on][off]UElXRef ($offUElXRef)

Syntax:

$onUElXRef
$offUElXRef

This option controls the collection and listing of cross references of set elements in the compilation output. For more information, see section The Unique Element Listing Map.

Example:

Set i "set declaration" / one, two, three /, k(i);
$onUElXRef
k('one') = yes;
$offUElXRef
k('two') = yes;
$onUElXRef
k('three') = yes;

The resulting listing file will contain the following unique element reference report:

Unique Element Listing


ELEMENT   REFERENCES

one          index        3
three        index        7

Note that the element two does not appear in this listing because the listing was deactivated with the option $offUElXRef in line 4 of the code above.

$[on][off]UNDF    ($offUNDF)

Syntax:

$onUNDF
$offUNDF

This option controls the use of the special value UNDF which indicates a result is undefined. For details see section Extended Range Arithmetic. By default, UNDF is not permitted to be used in assignments. This may be changed with the option $onUNDF.

Example:

Scalar x;
$onUNDF
x = UNDF;
Display x;

The output of the display statement follows:

----      4 PARAMETER x                    =         UNDF  

Note that an error would have been triggered without the use of $onUNDF. The option $offUNDF will return the system to the default, where UNDF may not be used in assignments.

$[on][off]Uni    ($offUni)

Syntax:

$onUni
$offUni

This controls whether the compiler checks the referential integrity (see section Domain Checking) of the code. This is an essential part of good GAMS programming and it is highly recommend to declare symbols with proper domains. With the universe as a domain the compiler does not help the user with easy-to-make mistakes, like swapping indexes, a(i,j) versus a(j,i). By default something like this would generate an error, if a was declared as a(i,j). Such an error could be ignored, by setting $onUni, which can be useful in few situations, when accessing a symbol with a set that is not the domain or a subset of the domain. For example, we could read data of a union of sets that already exist. We could use the universe as the domain for that symbol, but perhaps we need to protect the referential integrity of this symbol too.

Example:

Set       fruit   / apple, pear /
          veggie  / carrot, pea /
          produce / #fruit, #veggie /;
Parameter produceCalories(produce) "per 100g" / apple 52, pear 57, carrot 41, pea 81 /
          fc(fruit)  "calories per 100g"
          vc(veggie) "calories per 100g";
$onUni
fc(fruit)  = produceCalories(fruit);
vc(veggie) = produceCalories(veggie);
$offUni
display fc, vc;

So when assigning fc we only access produceCalories with fruit. We could reverse the order of declaration of fruit, veggie and produce and use a proper subdomain, but sometimes data flow and input don't allow that.

Attention
When the GAMS compiler operates under $onUni it treats all symbols as being declared over the universe. So all domain checking is gone. We can set elements in a symbols that normally can't be entered. This can also lead to strange effects:
set       i / 1*2 /
          j / a,b /;
parameter pi(i);
$onuni
pi(j) = 1;
$offuni
* We will see elements from j in pi
Display pi;
* The following should only clear the i-elements from pi, but it clears the
* entire symbol, because GAMS knows it's doing this to the entire domain and
* takes a shortcut.
pi(i) = no;
Display pi;

$[on][off]Verbatim

Syntax:

$onVerbatim
$offVerbatim

These options are used in conjunction with the GAMS command line 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.

Note that the options $on/offVerbatim are only recognized for DumpOpt \(\geq\) 10 and apply only to lines in the file between the two options.

Observe that the use of the options $goto and $on/offVerbatim are incompatible and may produce unexpected results.

Example:

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

The corresponding dmp file will contain the following lines:

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

See also command line parameter DumpOpt.

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

Syntax:

$onWarning
$offWarning

This option acts as a 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, see example below.
  • This may have serious side affects and we recommend to exercise great care when using this feature.

Example:

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 the domain of i. The skeleton listing file that results from running this code 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

Observe that the domain violations are marked like normal compilation errors but are only treated as warnings and it is permitted to execute the code.

For an introduction to domain checking in GAMS, see section Domain Checking.

$phantom id

Syntax:

$phantom id

This option is 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.

Example:

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

The output generated by the display statement is shown below:

----      4 SET i  
                                                      ( EMPTY )

----      4 SET j  
a,    b

Note that null does not appear in the listing file.

Attention
Statements that assign values to phantom labels are ignored.

Consider the following extension to the previous example:

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

The output generated by the display statement is shown below:

----      6 PARAMETER p
a 1.000

The system attribute system.empty is an implicitly defined phantom element. The following code works even without specifying $phantom:

Set i / system.empty /
    j / a, b, system.empty /;
display i,j;

Another way to specify empty data statements makes use of on/offEmpty. The following example produces the same data as the data statement with the phantom label. In contrast to the example we $phantom we need to provide the dimensionality of the symbol i explicitly via the (*):

$onEmpty
Set i(*) / /
    j / a, b /;
display i,j;

$prefixPath

Syntax:

$prefixPath directoryPath

This option augments the search path in PATH environment variable. The effect is that the text directoryPath is added to the beginning of the search path.

Example:

$log %sysenv.PATH%
$prefixPath C:\somewhereelse\anotherpath
$log %sysenv.PATH%

The log contains the following two relevant lines:

C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0
C:\somewhereelse\anotherpath;C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0

The option setEnv and sysEnv.VARNAME% allow to modify system environment variables but the length of the environment variable value is limited in GAMS to 255 characters. The PATH environment variable is often much longer and therefore this special $prefixPath option exists.

This works on all platforms but the path separator depends on the operating system (; for Windows and : for Unix).

$protect

Syntax:

$protect all | ident1 ident2 ...

This option creates a privacy setting: it freezes all values of identifiers with the result that modifications are no longer allowed but the parameters may still be used in model calculation (for example, equation definitions). Here ident1 and ident2 are specific GAMS identifiers previously defined in the program and the keyword all denotes all identifiers.

Note that this option is mainly used in the context of secure work files. The privacy restrictions may be removed with the options $expose or $purge.

$purge

Syntax:

$purge all | ident1 ident2 ...

This option removes the identifiers and all associated data in a privacy setting. With explicit identifiers the listed identifiers are removed, and with all all identifiers are removed.

Note that this option is used in the context of secure work files. A special license file is needed for this feature to work, the removal only takes effect in the restart files.

$remark

Syntax:

$remark text

This option performs a parameter substitution and writes a comment text to the compilation output of the listing file. Note that the line numbers of the comment are suppressed.

Example:

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

The resulting listing file will contain the following line:

Write TEST to the listing file

$set

Syntax:

$set VARNAME text

This option establishes or redefines contents of a scoped compile-time variable that is accessible in the code where the command appears and all code included therein. Here VARNAME is any user chosen variable name; text is optional and may contain any text. The text may contain spaces. The text can not be longer than 255 characters otherwise a compilation error is triggered. Observe that scoped compile-time variables may be destroyed (removed from the program) with the option $drop.

Note that in contrast to the option $eval the option $set does not evaluate the expression at compile time.

Note that GAMS allows scoped, local and global compile-time variables to be defined with the same name and therefore in some cases needs to prioritize. When referencing a compile-time variable via VARNAME% a local variable hides scoped and global variables and a scoped variables hides the global variable as the following example demonstrates.

Example:

$setLocal myvar this is a local variable
$set myvar this is a scoped variable
$setGlobal myvar this is a global variable
$log %myvar%
$droplocal myvar
$log %myvar%
$drop myvar
$log %myvar%

The log will look as follows:

this is a local variable
this is a scoped variable
this is a global variable

If one wants to set a compile-time variable in an include file that is visible to the program after the $include one need to use $setglobal:

$onEchoV > setvar.gms
$setArgs varname varvalue
$setglobal %varname% %varvalue%
$offEcho
$batInclude setvar MYVAR one
$log %MYVAR%

The log will show

one

An inventory of all defined compile-time variables and their type (local, scoped, and global) is available with the option $show.

See also $setGlobal, $setLocal, and section Compile-Time Variables.

$setArgs

Syntax:

$setArgs id1 id2 id3 ...

With this option parameters that may be substituted are defined as GAMS compile-time variables. Note that $setArgs may only be used in external files that are included with the option $batInclude, $libInclude, and $sysInclude.

Example:

Scalar a /2/, b /4/, c /5/;
$batInclude test3 a b c

The file test3.gms contains the following lines:

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 option $setArgs allows the batInclude file to use the more descriptive compile-time variables aa% instead of %1, bb% instead of %2 and cc% instead of %3. Note that the use of %1, %2 etc. is still allowed. The program listing looks as follows:

   1  Scalar a /2/, b /4/, c /5/;
BATINCLUDE C:\Users\default\Documents\gamside\projdir\test3.gms
   3  Scalar x;
   4  x = a + b * c ;
   5  display x;
   7  x = a - b * c  ;
   8  display x;
   9  x = a + b * c ;
  10  display x;

and the output generated by the display statements follows:

----      5 PARAMETER x                    =       22.000
----      8 PARAMETER x                    =      -18.000
----     10 PARAMETER x                    =       22.000

See also $set, $batInclude.

$setComps

Syntax:

$setComps perioddelimstring id1 id2 id3 ...

This option establishes or redefines compile-time variables so they contain the components of a period delimited string.

Here perioddelimstring is any period delimited string like the set specification of a multidimensional parameter, id1 is the name of a scoped compile-time variable that will contain the name of the set element in the first position, id2 is the name of a scoped compile-time variable that will contain the name of the set element in the second position and id3 is the name of a scoped compile-time 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 id1%.id2%.id3%.

Example:

$setComps period.delim.string id1 id2 id3
$log id1=%id1%
$log id2=%id2%
$log id3=%id3%
$set name %id1%.%id2%.%id3%
$log name=%name%

The resulting log file will contain the following lines:

id1=period
id2=delim
id3=string
name=period.delim.string"

See also $set.

$setDDList

Syntax:

$setDDList id1 id2 id3 ...

This option causes GAMS to look for misspelled or undefined double dash GAMS parameters.

Example: Consider the following example where three double dash GAMS parameters are defined on the command line:

> gams mymodel.gms --one=11 --two=22 --three=33  --four=44

The corresponding GAMS file follows:

$log %one%
$log %two%
$setDDList three
$log %three%
$log %four%

Note that the option $setDDList three checks if all double dash parameters have been used so far except for three. An error is triggered because four has not been used so far, the log file will contain the following:

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

See also section Double Dash Parameters.

$setEnv

Syntax:

$setEnv VARNAME value

This option defines an operating system environment variable. Here VARNAME is a user chosen environment variable name and value may contain text or a number. Note that system environment variables are destroyed (removed from the program) with the option $dropEnv or when GAMS terminates.

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

See also $dropEnv and section Environment Variables in GAMS.

$setGlobal

Syntax:

$setGlobal VARNAME text

This option establishes or redefines contents of a global compile-time variable that is accessible in the code where the command appears and all code included therein and all parent files. Here VARNAME is any user chosen variable name; text is optional and may contain any text. The text may contain spaces. The text can not be longer than 255 characters otherwise a compilation error is triggered. Observe that global compile-time variables may be destroyed (removed from the program) with the option $dropGlobal.

The difference between local, scoped, and global compile-time variable is explained with the option $set.

See also $set, $setLocal, $dropGlobal and section Compile-Time Variables.

$setLocal

Syntax:

$setGlobal VARNAME text

This option establishes or redefines contents of a local compile-time variable that is accessible only in the code module (source file) where it is defined. Here VARNAME is any user chosen variable name; text is optional and may contain any text. The text may contain spaces. The text can not be longer than 255 characters otherwise a compilation error is triggered. Observe that local compile-time variables may be destroyed (removed from the program) with the option $dropLocal.

The difference between local, scoped, and global compile-time variable is explained with the option $set.

See also $set, $setGlobal, $dropLocal and section Compile-Time Variables.

$setNames

Syntax:

$setNames file filepath filename fileextension

This option establishes or redefines three scoped compile-time variables so they contain the drive subdirectory, filename and extension of a file named with full path. Here file is any filename, filepath is the name of a scoped compile-time variable that will contain the name of the subdirectory where the file is located, filename is the name of a scoped compile-time variable that will contain the root name of the file and fileextension is the name of a scoped compile-time variable that will contain the extension of the file.

Example:

$setNames "%gams.input%" filepath filename fileextension
$set name %filepath%%filename%%fileextension%
$log %name%

The log will show

C:\Users\default\Documents\gamside\projdir\
Untitled_1
.gms
C:\Users\default\Documents\gamside\projdir\\Untitled_1.gms

Note that file is separated into its three components placing C:\Users\default\Documents\gamside\projdir\ into filepath, Untitled_1 into filename and .gms into fileextension. The three items may be recombined back into the original filename by using filepath%filename%fileextension% as shown in the example.

If the file is missing a path, name, or extension the corresponding variable is defined but remains empty as demonstrated in the following example:

$onEchoV > showfileparts.gms
$setNames "%1" filepath filename fileextension
$log path=%filepath%
$log name=%filename%
$log ext=%fileextension%
$offEcho
$batInclude showfileparts "C:\tmp\"
$batInclude showfileparts "Untitled_1"
$batInclude showfileparts "Untitled_1.gms"
$batInclude showfileparts "Untitled_1.gms.txt"

The log shows:

--- Untitled_1.gms(7) 2 Mb
path=C:\tmp\
name=
ext=
--- .showfileparts.gms(4) 2 Mb
--- Untitled_1.gms(8) 2 Mb
path=
name=Untitled_1
ext=
--- .showfileparts.gms(4) 2 Mb
--- Untitled_1.gms(9) 2 Mb
path=
name=Untitled_1
ext=.gms
--- .showfileparts.gms(4) 2 Mb
--- Untitled_1.gms(10) 2 Mb
path=
name=Untitled_1.gms
ext=.txt

Note that if a file contains multiple . the last one will be assigned to the fileextension as shown in the example with Untitled_1.gms.txt.

$shift

Syntax:

$shift

This option is similar to the command.com/cmd.exe shift operator (see en.wikipedia.org/wiki/COMMAND.COM::Batch_file_commands. It shifts the order of all parameters passed once to the left. This effectively drops the lowest numbered parameter in the list.

Example:

Scalar a, b, c ; a = 1 ;
$batInclude inc.inc a b c
display a, b, c ;

The batch include file inc.inc follows:

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

The resulting listing file will contains the following echo print:

    1  Scalar a, b, c ; a = 1 ;
BATINCLUDE C:\Users\default\Documents\gamsdir\projdir\inc.inc
    3  b = a + 1 ;
    5  c = b + 1 ;
    6  display a, b, c ;

Note that in the first statement in the include file, %1 is the first argument in the $batInclude call and in this case it is interpreted 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 dollar control option $shift shifts the arguments to the left. As a result, %1 is interpreted as b, and %2 is interpreted as c. This leads to the second assignment being interpreted as c=b+1.

Therefore the outcome generated by the display statement in the input file is as follows:

----      6 PARAMETER a                    =        1.000
            PARAMETER b                    =        2.000
            PARAMETER c                    =        3.000

See also $batInclude.

$show

Syntax:

$show

This option causes current values of the compile-time variables plus a list of the macros and active input and include files to be shown in the compilation output.

Example:

$set it 1
$setLocal yy
$setGlobal gg what
$include myinclude
$show

The file myinclude.gms follows:

$set inincs
$setLocal inincsl
$setGlobal inincsg
$show

The resulting listing file will contain the following environment reports in the compilation output:

---- Begin of Environment Report
LEVEL TYPE         LINE  FILE NAME
----------------------------------
    1 INCLUDE         5  C:\Users\default\Documents\gamside\projdir\myinclude.gms
    0 INPUT           4  C:\Users\default\Documents\gamside\projdir\\Untitled_1.gms

Level SetVal                          Type       Text
-----------------------------------------------------
    1 inincsl                         LOCAL      
    1 inincs                          SCOPED     
    0 yy                              LOCAL      
    0 it                              SCOPED     1
    0 gg                              GLOBAL     what
    0 inincsg                         GLOBAL     
---- macro definitions
$macro multx(x)  x*x
---- End of Environment Report

and

---- Begin of Environment Report
LEVEL TYPE         LINE  FILE NAME
----------------------------------
    0 INPUT           6  C:\Users\default\Documents\gamside\projdir\\Untitled_1.gms

Level SetVal                          Type       Text
-----------------------------------------------------
    0 yy                              LOCAL      
    0 it                              SCOPED     1
    0 gg                              GLOBAL     what
    0 inincsg                         GLOBAL     
---- macro definitions
$macro multx(x)  x*x
$macro addx(x)  x+x
---- End of Environment Report

Note that only the macros and the item defined with the option $setGlobal in the included file carries over. Observe that the name "Environment Report" is unfortunate since the reported values are for compile-time variables, not environment variables.

See also section Compile-Time Variables.

$single

Syntax:

$single

The lines following this option will be echoed single spaced in the compilation output. Note that this is the default. The option is only useful as a switch to deactivate the option $double.

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 echo print in the resulting listing file will look 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 options $double and $single are listed double spaced, while the lines after the option $single revert back to being listed single spaced.

See also $double.

$splitOption

Syntax:

$splitOption KEYVALPAIR optname optvalue

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

Example:

$onechoV > myinclude.gms
* Default values for named arguments
$setGlobal a1 1
$setGlobal a2 2
$setGlobal a3 3
$setGlobal positionalArgs
$label ProcessNamedArguments
$  splitOption "%1" key val
$  if x%key%==x $goto FinishProcessNamedArguments
$  ifThenI.NamedArguments %key%==a1
$    setGlobal a1 %val%
$  elseIfI.NamedArguments %key%==a2
$    setGlobal a2 %val%
$  elseIfI.NamedArguments %key%==a3
$    setGlobal a3 %val%
$  else.NamedArguments
$    error Unkown named argument "%key%"
$  endIf.NamedArguments
$  shift
$goTo ProcessNamedArguments
$label FinishProcessNamedArguments
$setGlobal positionalArgs %1 %2 %3
$offEcho
$batInclude myinclude -a3=0 -a2=3.14 i j k
$log Using named arguments -a1=%a1% -a2=%a2% -a3=%a3% positionalArgs=%positionalArgs%

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 as demonstrated by the log output:

Using named arguments -a1=1 -a2=3.14 -a3=0 positionalArgs=i j k

stars   (****)

Syntax:

$stars char[char][char][char]

This option is used to redefine the **** marker in the GAMS listing file. By default, important lines like those that denote errors and the solver and model status are prefixed with ****. A new marker consists of one to four characters.

Example:

$stars *##*
garbage

The resulting listing file 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

Syntax:

$sTitle text

This option sets the subtitle in the page header of the listing file to text. Note that the next output line will appear on a new page in the listing file.

Example:

$sTitle Data tables for input/output

See also $title.

$stop

Syntax:

$stop [text]

This option stops program compilation without creating an error. Note there is a difference to the option $exit. If there is only one input file, $stop and $exit will have the same effect. In an include file the option $exit acts like an end-of file on the include file. However, the option $stop in an include file will cause GAMS to stop reading all input but continue the execution phase of the so far compiled program. The text followed by $stop is ignored.

Example:

$ifthen not set EXPORTEXCEL
$  stop No export to Excel
$else
$  call gdxxrw ...
$endif 

See also $abort, $error, $exit, and $terminate.

$sysInclude

The syntax of this dollar control option is equivalent to the syntax of $batinclude:

Syntax:

$sysinclude external_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. Note that the default directory may be reset with the command line parameter sysIncDir.

Example:

The only relevant include file in the GAMS system directory is mpsgeset for MPSGE models, see for example [HARMGE]:

$sysInclude mpsgeset KAMIYA

Note that this call will first look for the include file [GAMS System Directory]/mpsgeset. If this file does not exist, it will looks for [GAMS System Directory]/mpsgeset.gms. The argument KAMIYA is passed on to the include file and are interpreted as explained for the dollar control option $batInclude.

Consider the following example:

$sysInclude C:\Users\default\Documents\mpsgeset KAMIYA

This call will first look specifically for the include file C:\Users\default\Documents\mpsgeset and next for C:\Users\default\Documents\mpsgeset.gms.

See also $batInclude.

$terminate

Syntax:

$terminate [text]

This option terminates compilation and also does not execution to program compiled so far without giving an error.

Example:

$if set JUSTTERMINATE $terminate

See also $abort, $error, $exit, and $stop.

$title

Syntax:

$title text

This option sets the title in the page header of the listing file to text. Note that the next output line will appear on a new page in the listing file.

Example:

$title  Production Planning Model
$sTitle Set Definitions

See also $sTitle.

$unLoad

Syntax:

$unLoad sym1[,] sym2=gdxSym2[,] ...]

This option unloads specified items to a GDX file. Note that $unLoad must be used in conjunction with the option $gdxOut: $gdxOut must precede $unLoad. More than one option $unload may appear in between. Symbols can be renamed via the sym=GDXSym syntax. A $unLoad without arguments unloads the entire GAMS database into the GDX file.

Example: 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 tranX
$unLoad

Note that the last lines will create a file named tran.gdx that contains i, j and d and the parameters a and b which are now named dem and sup. The $unLoad in the very last line creates a GDX file tranX.gdx with all symbols (with their original names). The table of content (via $gdxIn and $load without parameters) of these two files looks as follows:

Content of GDX C:\Users\default\Documents\gamsdir\projdir\tran.gdx
               5 UELs

    Number Type       Dim       Count  Name
         1 Set          1           2  i           canning plants
         2 Set          1           3  j           markets
         3 Parameter    1           3  dem(j)      demand at market j in cases
         4 Parameter    1           2  sup(i)      capacity of plant i in cases
         5 Parameter    2           6  d(i,j)      distance in thousands of miles

Content of GDX C:\Users\default\Documents\gamsdir\projdir\tranX.gdx
               5 UELs

    Number Type       Dim       Count  Name

         1 Set          1           2  i           canning plants
         2 Set          1           3  j           markets
         3 Parameter    1           2  a(i)        capacity of plant i in cases
         4 Parameter    1           3  b(j)        demand at market j in cases
         5 Parameter    2           6  d(i,j)      distance in thousands of miles

Both listings show domain information for the various symbols but only the file tranX.gdx created with $unLoad without arguments has the real domain sets that can be used for domain matching when loading with the $load sym<[=]symGDX, see $load for details.

$use205

Syntax:

$use205

This option sets the GAMS syntax to the syntax 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 to run such models.

Example:

$use205
Set if /1.2.3/; 
Scalar x ;

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

$use225

Syntax:

$use225

This option sets the GAMS syntax to the syntax of the 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 to run such models.

Example:

$use225
Set for /1.2.3/; 
Scalar x ;

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

$use999

Syntax:

$use999

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

Example:

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

Note that the word "for" is used as a set identifier after setting the option $use225 and later the keyword for is used in a looping construct after having set the language syntax to that of the latest version using the option $use999.

$version

Syntax:

$version n

This issues a compilation error if n is greater than the current GAMS version. This can be useful to ensure that a model is run only with new versions of GAMS, because, e.g., a particular feature which did not exist in older versions is needed.

Example:

* With GAMS 24.8.1 the function numCores was added to the system.
* Make sure, that we use this GAMS version or newer.
$version 248

Scalar nc "Number of cores";
nc = numCores;
Display nc;

$warning

Syntax:

$warning text

This dollar control option issues a compilation warning to the log and listing but continues compilation and execution.

Example

$ifthen not set INPUTFILE
$ set INPUTFILE default.txt
$ warning Using default INPUTFILE "default.txt". Use --INPUTFILE=myfile.txt to overwrite default.
$endif

The GAMS log file will issue a warning:

*** Error 332 in C:\Users\default\Documents\gamsdir\projdir\myinput.gms
    $Warning encountered - see listing for details

with the details in the listing file:

   3  $ warning Using default INPUTFILE "default.txt". Use --INPUTFILE=myfile.txt to overwrite default.
****       $332

Conditional Compilation

GAMS offers several dollar control options that facilitate conditional compilation. In this section we will first introduce the general syntax, present an overview of all relevant options and list the conditional expressions that may be used to perform tests. Then we will give several examples to illustrate how these options are used and to demonstrate their power. This section is meant as an introduction to conditional compilation in GAMS and complements the detailed descriptions of the dollar control options listed in Table 1 below.

Conditional Compilation: General Syntax and Overviews

The dollar control option $if and its variants provide a great amount of control over conditional processing of the input file(s). The syntax in GAMS is similar to the IF statement of the DOS Batch language:

$if [not] <conditional expression> new_input_line

The dollar control statement begins with $if. Note that $if may be replaced by one of its variants that are listed in Table 1 below. The operator not is optional and makes it possible to negate the conditional expression that follows. The conditional expression may take various forms, a complete list is given in Table 2. The result of the conditional test is used to determine whether to process ir not the remainder of the line, new_input_line, which may 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 remainder 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.

Alternatively, the new_input_line may be placed in the next line. The corresponding syntax follows:

$if [not] <conditional expression> 
new_input_line

Note that in this version the space after the conditional expression is left blank. If the conditional is found to be false, either the remainder of the line (if any) will be skipped or the next line will not be processed.

The overviews in Table1 and Table 2 conclude this subsection. Examples are given in the next subsection.

Table 1: $if and Related Dollar Control Options

Dollar Control Option Description
$if This option is used to do case sensitive comparisons. Several examples are given in the next subsection.
$ifE This variant does the same as $if but allows numerical constant expression evaluation. For an example, see the detailed description of this option.
$ifI This variant is the same as $if, but it is case insensitive.
$ifThen This variant controls whether a block of statements will be processed or not. It is used to do case sensitive comparisons. Most often it is followed by one or more of the following dollar control options: $else, $elseIf, $elseIfI, $elseIfE. The option $ifThen must be matched with the option $endIf that marks the end of the block. An example is given below.
$ifThenE This is a variant of $ifThen and is used for numerical comparisons. Like $ifThen, it is often followed by the option $else or one of its variants and must be matched with the option $endIf that marks the end of the construct.
$ifThenI This is a variant of $ifThen and is used to do case insensitive comparisons. Like $ifThen, it is often followed by the option $else or one of its variants and must be matched with the option $endIf that marks the end of the construct.
$endIf This option must be matched with a preceding option $ifThen, $ifThenE or $ifThenI and marks the end of the if - then construct. Note that the option $endIf is not followed by a conditional expression, but it may be follwowed by a new_input_line. This GAMS input is restricted to other dollar control statements. An example is given below.
$else This option follows the option $ifThen, $ifThenE or $ifThenI. It is followed by an instruction which is executed if the conditional expression of the matchining $ifThen statement is not true. Note that therefore this dollar control statement does not contain a conditional expression. An example is given below.
$elseIf This option follows the option $ifThen, $ifThenE or $ifThenI. It is follwed by another conditional expression and instruction. Note that this option is case sensitive. An example is given below.
$elseIfE This is a variant of $elseIf that evaluates numerical values.
$elseIfI This is a variant of $elseIf that is case insensitive.

Table 2: Conditional Expressions in Conditional Compilation

Conditional Expression Description
acrType id True if id is an acronym.
decla_OK True if a declaration statement is permitted in the current line. Note that declaration statements are not permitted within programming flow control structures like if statements or loop statements. An example is given below.
declared id True if id was declared.
defined idTrue if id was defined. An example is given below.
dExist directoryname True if a directory with the name directoryname exists.
dimension n id True if id has n dimensions. Note that n may take values from 0 to maximum number of possible indexes (see Dimensions).
equType id True if id is an equation.
errorFree True if compilation up to this point has been free of errors.
errorLevel n True if the return code of a program called via $call is equal to or larger than n. For lists of GAMS return codes, see chapter GAMS Return Codes. An example is given below.
exist filename True if a file with the name filename exists. An example is given below.
filType id True if id is the name of a put file.
funType id True if id is a GAMS function.
gamsVersion n True if current GAMS version equals n. For example, if the current GAMS version is 24.7, then gamsVersion will equal 247. Minor version numbers, e.g. 24.7.4 do not count
macType id True if id is a macro.
modType id True if id is a model.
parType id True if id is a parameter.
preType id True if id is a one of the predefined symbols in GAMS. Details are given below.
putOpen True if both a file statement and at least one put statement have been compiled. Note that this does not guarantee that a file will be open at runtime.
readable id True if id was correctly initialized, i.e. the symbol has a data statement or appeared on the left-hand side of an assignment statement, and may therefore be used on the right-hand side of an assignment statement. An example is given below.
set varname True if the scoped compile-time variable varname was set with the dollar control option $set, $setGlobal or $setLocal.
setEnv varname True if the environment variable varname was set in the systems environment, e.g. with the dollar control option $setEnv.
setGlobal varname True if the control variable varname was set with the dollar control option $setGlobal.
setLocal var_name True if the control variable var_name was set with the dollar control option $setLocal.
setType id True if id is a set.
solver solver_nameTrue if a solver named solver_name exists in the GAMS system. An example is given below.
varType id True if id is a variable.
warnings True if the compilation until this point has been free of warnings.
xxxType id True if id is an unknown type. For more information, see below.
string1 == string2 True only if string1 matches string2 exactly. Note that the strings may be quoted or unquoted. Null (empty) strings may be indicated by an empty quote: "" or ''. The case of the strings provided either explicitly or, more likely, through a parameter substitution, is preserved and therefore will affect the string comparison. Quoted strings with leading and trailing blanks are not trimmed and the blanks are considered part of the string. Note that the string may have the form %VARNAME%, where VARNAME refers to a compile-time variable including GAMS command line parameters and system attribute. An example for a string comparison with a command line parameter is given below. An example for a string comparison with a system attribute is given below.

Conditional Compilation: Examples

File Operation Test

The operator exist may be used to test whether a given file name exists. Consider the following example:

$if exist myfile.dat $include myfile.dat

Observe that the effect of this dollar control statement is that the file myfile.dat is included if it exists. Note that the character $ at the beginning of the option $include is the first non-blank character after the conditional expression exist myfile.dat and therefore it is treated as the first column position. The statement above may also be written as follows:

$if exist myfile.dat
$include myfile.dat

Conditional Compilation and Batch Include Files

In the next example we will illustrate how the option $if is used inside a batch include file where parameters are passed through the option $batInclude from the parent file:

$if not "%1a" == a $goto labelname
$if exist %1 file.ap=1;

Note that in the first line the $if condition uses the string comparison "%1a" == a to check if the parameter is empty. This test may also be done in the following way: %1 == "". If the parameter is not empty, the option $goto is processed.

Note
The option $label cannot be part of the conditional input line. However, if the option $label appears on the next line, the condition decides once if the label is placed or not and subsequent instances of $goto will find the label without reevaluating the condition.

The second line illustrates the use of standard GAMS statements if the conditional expression is valid. If the file name passed as a parameter through the $batInclude call exists already, the GAMS will execute the file.ap=1; statement which will append to the file.

The next example demonstrates how an unknown number of file specifications may 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.gms
* include and process an unknown number of input files 
$label nextfile
* Quote everything because file name might have blanks 
$if exist "%1"  $include "%1"
$shift 
$if not "%1a" == a $goto nextfile

The call to this file in the parent file could take the following form:

$batInclude inclproc "file 1.inc" file2.inc file3.inc file4.inc

Testing Whether an Item Has Been Defined

The next example shows how to test if a named item was declared and/or defined.

Set i;
$if defined  i $log First: set i is defined
$if declared i $log First: set i is declared
Set i /seattle/;
$if defined  i $log Second: set i is defined
$if declared i $log Second: set i is declared

Note that after the first declaration of i only declared i evaluates to true when after the second declaration with a data statement both defined i and declared i are true.

Testing Whether an Item May Be Used in an Assignment

The expression readable id tests whether data were assigned to an item and therefore he item may be used on the right-hand side of an assignment statement. Consider the following example:

Scalar f;
$if not readable f $log f cannot be used on the right
Scalar f /1/;
$if readable f $log f can be used on the right
$kill f
$if not readable f $log f cannot be used on the right after clear
f = 1;
$if readable f $log f can be used on the right after assignment

Note that in the first test the set f was declared, but there was no data statement, hence it is not readable. After a declaration with a data statement the test readable f evaluates to TRUE. With $kill we can revert f to a data less state and hence not readable f is TRUE after the "$kill". The assignment statement f = 1; make the scalar f readable again.

Testing Whether an Identifier May Be Declared

In programming flow control structures, like if statements or loop statements declaration statements are not permitted. The test decla_ok may be used to test whether the current environment allows declaration statements. Consider the following example:

$if decla_ok $log declarations are possible
if(1,
$  if not decla_ok $log declarations are not allowed
);

Note that the conditional expression in the both $if tests will evaluate to TRUE. However, the second test of decla_ok itself will be FALSE because it is processed while compiling an if statement, but with the not the entire expression evaluated to TRUE. For more information, see chapter Programming Flow Control Features.

Comments in the Context of Conditional Compilation

In-line and end-of-line comments are stripped out of the input file before processing the new_input_line. If either of these forms of comments appear, they 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;

Note that the comments on line 3 are ignored and the fourth line with the assignment statement will be processed if the conditional expression is true Hence the outcome generated by the display statement will list a with a value of 4 if the file myfile.dat exists and a value of 10 if the file does not exist.

Error Level Test

Consider the following example:

$call gams mymodel.gms lo=2
$if errorlevel 1 $abort one or more errors encountered

Note tthat the errorlevel is retrieved from the previous system call via $call. The conditional statement errorlevel 1 is true if the returned errorlevel is equal to or larger than 1. In case of calling GAMS this means that something was not quite right with the execution of GAMS (either a compilation or execution error or other more exotic errors, see GAMS return codes. If this is the case, this GAMS program will be aborted immediately at compilation time.

Solver Test

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

$if solver ZOOM

Note that the conditional expression is false since the solver named ZOOM does not exists in the GAMS system (anymore).

Command Line Parameters in String Comparison Tests

Assume we include the following dollar control statements in a GAMS file called myfile.gms:

$if not '%gams.ps%'==''  $log Page size set to  %gams.ps%
$if not '%gams.pw%'==''  $log Page width set to %gams.pw%
$if not '%gams.mip%'=='' $log MIP solver default is %gams.mip%

Then we run the program with the following call:

> gams myfile pageSize=60  pageWidth=85 mip=cbc

Note that we specified values for the command line parameters pageSize, pageWidth, and MIP. We can either use the short or long name on the command line and in the compile-time variable. If we do not specify the option on the command line we will get the default value for option page size and page width. The MIP solver line will not show because gams.mip% remains empty. The log with option setting on the command line will include the following lines:

Page size set to  60
Page width set to 85
MIP solver default is cbc

Command line parameters are introduced in chapter The GAMS Call and Command Line Parameters.

System Attributes in String Comparison Tests

Compile-time system attributes may also be used in string comparison tests. The system attribute that is most useful in this context is .fileSys. It identifies the name of the operating system being used. Consider the following example:

$ifthen not %gams.logOption%==3
$  ifi %system.fileSys%==UNIX  $set nullFile > /dev/null
$  ifi %system.fileSys%==MSNT  $set nullFile > nul
$  if not set nullFile $abort %system.fileSys% not recognized
$else
$  set nullFile
$endif
$call gamslib trnsport %nullFile%

These dollar control statements allow the definition of a NULL file destination that is dependent on the operating system that is being used. Note that the control variable nullfile is set to the operating system dependent name. This makes it useful to make an external program that writes to STDOUT quiet in case the GAMS log does not go to STDOUT (logOption=3). This example could also use the system attribute system.nullFile% which is sets the operating system dependent NULL file destination:

$set nullFile 
$if not %gams.logOption%==3 $set nullfile > %system.nullFile%
$call gamslib trnsport %nullfile%

System attributes in general are introduced in chapter System Attributes.

Conditional Compilation with $ifThen and $else

Consider the following example which illustrates the use of $ifThen, $elseIf, $else and $endif:

$set x a
$label test
$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 test

Note that the resulting log file will contain the following lines:

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

Observe that the options $else and $endIf are not followed by conditional expressions and the instruction following the option $endIf contains a dollar control statement. Moreover, note that the $set x 'c' has the text to be set in quotes. GAMS needs to know where the text ends and the next dollar control option (in this case $log) starts.

Type of Identifiers

The type of a symbol can be retrieved via $if ...Type. Consider the following example:

Set diag / 1*3 /;
Parameter p(diag) / 1 1, 2 4, 3 8 /;
$if     setType diag    $log diag   is a set
$if not varType diag    $log diag   is not a variable
$if     preType diag    $log diag   is a predefined type
$if     parType p       $log p      is a parameter
$if     setType sameAs  $log sameAs is a set
$if     preType sameAs  $log sameAs is a predefined type

Note that for predefined symbols more than one type applies (e.g. sameAs is of set and predefined type). Please also note that diag is a set even though there is a predefined symbol named diag but that becomes invisible with a user defined symbols with the same name.

Normally there is no way to get a symbol into the GAMS symbols table without a proper type. However, if the dollar command line parameter multiPass is set to a value larger than zero, then the compiler will just check for some integrity and will try to deduce the symbol type from the context. If it is not able to do so, the symbol type will remain unknown. For example, compiling the following lines with multiPass=1

display x;
$if xxxType x $log x is of unknown type

result in the line x is of unknown type in the GAMS log.

Macros in GAMS

Macros are widely used in computer science to define and automate structured text replacements. The GAMS macro processors function similarly to the popular C/C++ macro preprocessor. Note that the GAMS macro facility has been inspired by the GAMS-F preprocessor for function definition developed by Michael Ferris, Tom Rutherford and Collin Starkweather, 1998 and 2005. The GAMS macro facility incorporates the major features of the GAMS-F preprocessor into the standard GAMS release as of version 22.9. GAMS macros act like a standard macro when defined. However, their recognition for expansion is GAMS syntax driven.

Syntax and Simple Examples

The definition of a macro in GAMS takes the following form:

$macro name  macro_body
$macro name(arg1,arg2,arg3,...) macro_body with tokens arg1, ...

The dollar symbol $ followed by macro indicate that this line is a macro definition. The name of the macro has to be unique, similar to other GAMS identifiers like sets and parameters. The macro name is immediately followed by a list of replacement arguments arg1,arg2,arg3,... that are enclosed in parentheses. The macro body is not further analyzed after removing leading and trailing spaces.

The recognition and following expansion of macros is directed by GAMS syntax. The tokens in the macro body to be replaced by the actual macro arguments follow the standard GAMS identifier conventions. Consider the following simple example of a macro with one argument:

$macro reciprocal(y) 1/y

Here the name of the macro is reciprocal, y is the argument and the macro body is 1/y. This macro may be called in GAMS statements as follows:

$macro reciprocal(y) 1/y
scalar z, x1 /2/, x2 /3/;
z = reciprocal(x1) + reciprocal(x2);

As GAMS recognizes reciprocal(x1) and reciprocal(x2) as macros, the assignment statement will expand to:

z = 1/x1 + 1/x2;

The next example illustrates macros with multiple arguments:

$macro ratio(x,y) x/y
scalar z, x1 /2/, x2 /3/;
z = ratio(x1,x2);

The assignment above will expand to:

z= x1/x2;

Note that the macro definition may extend over several lines with the symbol \ acting as a continuation string. Consider the following example:

$macro myxor(a,b)  (a or b) \
               and (not a or not b)
scalar z;
z = myxor(1,0); 
display z;

The z assignment expands to

z = (x1 or x2)and (not x1 or not x2);

Note that although the macro has been defined over two lines, the expansion happens by combining the lines without adding white space between end of first line and beginning of the second line. This can cause problems as demonstrated in the next example (because and has a higher precedence than or we can omit the parenthesis):

$macro myxor(a,b)  not a and b \
                or a and not b
scalar z;
z = myxor(1,0); 
display z;

The z assignment expands to

z = not 1 and bor 1 and not 0;

which result because of bor in a compilation error. The &, explained in more detail in the next section helps us to preserve white space:

$macro myxor(a,b)  not a and b \
              & or a and not b

Nested Macros

Macros may be nested. Consider the following example:

$macro product(a,b) a*b
$macro addup(i,x,z) sum(i,product(x(i),z))
set j /j1*j10/;
Parameter a1(j) / #j 1 /, z, x1 /5/;
z = addup(j,a1,x1);

Observe that the macro product is nested in the macro addup. The assignment will expand to:

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

Note that nested macros may result in an expansion of infinite length. An example follows.

$macro a  b,a
display a;

This will expand into:

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

In such a case GAMS will eventually refuse to do more substitutions and will issue a compilation error:

732  Too many edits on one single line - possible recursion in macro calls
        compilation will be terminated

Ampersands in Macro Definitions

The expansion of arguments may be more carefully controlled by the use of ampersands & in the macro body. A single ampersand & is used as a concatenation or separation symbol to indicate tokens that are to be replaced. Consider the following example:

$macro  f(i)  sum(j, x(i,j))
$macro equ(q)  equation equ_&q;  \
               equ_&q.. q =e= 0;
set i /i/, j /j/;
variable x(i,j);               
equ(f(i))

This will expand into:

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

Note that without the ampersand notation, GAMS would have recognized only the third occurrence of q and hence the expansion would have been:

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

Two ampersands && immediately preceding a token will drop the most outer matching single or double quotes of the replacement argument. This makes it possible to include expressions with spaces, commas and unbalanced parentheses. The latter one is something users should really avoid doing. An example follows.

$macro d(q) display &&q;
$macro ss(q) &&q)
set i /i/, k /k/;
parameter a1(i) / i 1/, z;
d('"here it is" , i,k')
d('"(zz"')
z=ss('sum(i,a1(i)');
z=ss('prod(i,a1(i)');

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

display "here it is" , i,k;
display "(zz";
z=sum(i,a1(i));
z=prod(i,a1(i));

Additional Macro Features

Deeply nested macros may require aliased sets in indexed operations like sum and prod. A minor syntax extension allows the implicit use of aliases. The suffix .local on a controlling set will use an implicit alias within the scope of the indexed operation. Consider the following example:

$macro ratio(a,b) a/b
$macro total(q) sum(i,q(i))
set i /i1*i15/;
parameter a(i) / #i 1 /, b(i) / #i 2 /, r(i), asum;
asum = total(a);
r(i) = ratio(total(a), b(i));

The assignment statement will expand to:

asum = sum(i,a(i));
r(i) = sum(i,a(i))/b(i);

The second line will not compile because the i in the sum is already controlled from the i on the left. The intention was the total macro is to add up the elements of a parameter indexed over i. As in the r(i) assignment the macro might be used in a statement where i is already controlled hence when doing the sum in the macro we want to use an alias of i. If we change the macro definition to

$macro total(q) sum(i.local,q(i))

The code works as expected because the i in the sum refers to the i.local and not the outside i.

Note that the the modifier .local is not limited to macros and may be used in any context. For further details and more examples, see the detailed description of the dollar command option $on/offLocal.

Another feature of macros is the implicit use of the suffix .L 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 ;
Parameter tsupply(i) total demand for report
          tdemand(j) total demand for report
$onDotL
tsupply(i)=sumIt(j, x(i,j));
tdemand(j)=sumIt(i, x(i,j));

The option $onDotL enables the implicit suffix .L for variables. This feature was introduced for macros with variables to be used in equation definitions as well as assignment statements. The matching option $offDotL will disable this feature. Similarly, $offDotScale will access the .scale suffix of a variable or equation in an assignment statement.

Three more switches are relevant to macros. The option $show will list any GAMS macros defined. The option $on/$offMacro will enable or disable the expansion of macros; the default is $onMacro. Finally, the option $on/offExpand will change 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. The option $offExpand will restore the default behavior.

Note that macro definitions are preserved in a save/restart file and are available again for a continued compilation.

Summarizing, macros shares the name space of GAMS symbols, like sets, parameters, variables, etc. Macros are recognized and expanded anywhere a proper GAMS identifier may be used. This may be suppressed with the option $on/offMacro. The body of macros is only used during expansion. Hence, macro definitions are not order dependent. Variables in macro bodies will have an implicit suffix .L when they are used in assignment statements. This GAMS feature needs to be activated with the option $onDotL.

Compressing and Decompressing Files

GAMS provides two dollar control options for compressing and decompressing GAMS input files:

Dollar Control Option Description
$compress   <source> <target> The file source is compressed into the packed file target.
$decompress   <source> <target> The compressed file source is decompressed into the unpacked file target.
Attention
Spaces are interpreted as separators between the source and target file names, hence quotes (single or double) have to be used if the file names contain spaces.

Note that GAMS will recognize whether a file is compressed and will processes it accordingly.

Note
Like any other GAMS input files, all compressed files are platform-independent.

Compressing and Decompressing Files: A Simple Example

We use the well-known transportation model [TRNSPORT] to illustrate. First we copy the model from the GAMS Model Library and then we create a compressed version of the original:

> gamslib trnsport
> echo $compress trnsport.gms t1.gms > t2.gms
> gams t2

Alternatively, the following code snippet may be used from within a GAMS file:

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

Note that the compressed input file t1.gms can be treated like any other GAMS input file. If it is executed, the listing file will be identical to the listing file of the original input file trnsport.gms, since a decompressed input is reported in the echo print. As usual, the parts of the model that are marked with the dollar control option $on/offListing will not appear in the echo print.

The compressed file t1.gms can be decompressed as follows:

> echo $decompress t1.gms. t3.gms > t4.gms
> gams t4

Alternatively, from within a GAMS file:

$decompress t1.gms t3.gms

Observe that the decompressed file t3.gms is identical to the original file trnsport.gms. This can easily be tested with the following command:

> diff trnsport.gms t3.gms

Compressing and Decompressing Files: The Model CEFILES

The following more elaborate example is self-explanatory. It is adapted from model [CEFILES] and can easily be modified to test the use of compressed files.

* --- get model
$call gamslib -q trnsport

* --- compress and run model
$compress   trnsport.gms t1.gms
$decompress t1.gms       t1.org
$call       diff trnsport.gms t1.org > %system.nullFile%
$if         errorLevel 1 $abort files trnsport and t1 are different

* --- check to see if we get the same result
$call gams trnsport gdx=trnsport lo=%gams.lo%
$if   errorLevel 1 $abort model trnsport failed
$call gams t1       gdx=t1       lo=%gams.lo%
$if   errorLevel 1 $abort model t1 failed
$call gdxdiff trnsport t1 %system.reDirLog%
$if   errorLevel 1 $abort results for trnsport and t1 are not equal

* --- also works with include files
$echo $include t1.gms > t2.gms
$call gams t2 gdx=t2 lo=%gams.lo%
$if   errorLevel 1 $abort model t2 failed
$call gdxdiff trnsport t2 %system.reDirLog%
$if   errorLevel 1 $abort results for trnsport and t2 are not equal
$terminate

Encrypting Files

When models are distributed to users other than the original developers, issues of privacy, security, data integrity and ownership arise. To address these concerns, secure work files may be used and GAMS input files may be encrypted. Note, that the encryption follows the work file security model and requires special licensing.

Note
Like any other GAMS input files, all compressed and encrypted files are platform-independent.

Encryption is only available if a system is licensed for secure work files and usually requires a target license file which will contain the user or target encryption key. Note that once a file has been encrypted it cannot be decrypted any more. GAMS provides the following dollar control option to encrypt an input file:

$encrypt <source> <target>

Here the name of the input file to be encrypted is source and the name of the resulting encrypted file is target.

Encrypting Files: A Simple Example

We use again the transportation model [TRNSPORT] to illustrate. First we copy the model from the GAMS Model Library and then we create an encrypted version of the original:

> gamslib -q trnsport
> echo $encrypt trnsport.gms t1.gms > t2.gms
> gams t2 pLicense=target lo=%gams.logOption%

Note that the first two lines are similar to the directives that we have used to compress the model above. In the third line, the command line parameter pLicense specifies the target or privacy license to be used as a user key for encrypting. Thus the new encrypted file t1.gms is locked to the license key target and it can only be executed with the license file target:

> gams t1 license=target dumpOpt=11

Note that the command line parameter license is used to override the default GAMS license file gamslice.txt that is located in the system directory. Note further that the command line parameter dumpOpt is usually used for debugging and maintenance. The value 11 causes a clean copy of the input to be written to the file t1.dmp, where all include files and macros are expanded. Observe that if some lines have been marked with the dollar control options $on/offListing in the original file, then these lines will be suppressed in the file t1.dmp.

Note
Once a file has been encrypted, it cannot be decrypted any more. There is no inverse mechanism to recover the original file from the encrypted file. An attempt to decompress it using $decompress will fail.

Observe that encrypting is done on the fly into memory when the GAMS system files are read. GAMS will recognize if a file is just plain text or compressed and/or encrypted and will validate and process the files accordingly.

Encrypting Files: The Model ENCRYPT

The following more elaborate example is self-explanatory; it is model [ENCRYPT] from the GAMS Model Library.

Note that the option license=demo is used. This overrides the license that is currently installed with a demo license that has the secure file option enabled.

$ontext
To create an encrypted file, we need a license file which has the
security option enabled. To allow easy testing and demonstration
a special temporary demo license can be created internally and
will be valid for a limited time only, usually one to two hours.

In the following example we will use the GAMS option license=demo to
use a demo license with secure option instead of our own license
file. Also note that we use the same demo license file to read the
locked file by specifying the GAMS parameter pLicence=license.
$offtext


* --- get model
$ondollar
$call gamslib -q trnsport

* --- encrypt and try to decrypt
$call rm -f t1.gms
$echo $encrypt trnsport.gms t1.gms > s1.gms
$call gams s1 license=demo pLicense=license lo=%gams.logOption%
$if   errorLevel 1     $abort encryption failed

$eolCom  //
$if not errorFree $abort pending errors
$decompress t1.gms t1.org  // this has to fail
$if     errorFree $abort decompress did not fail
$clearError

* --- execute original and encrypted model
$call gams trnsport gdx=trnsport lo=%gams.logOption%
$if   errorLevel 1 $abort model trnsport failed
* Although this reads license=demo, this license file is the one
* specified with pLicense from the s1 call
$call gams t1 license=demo gdx=t1 lo=%gams.logOption%
$if   errorLevel 1 $abort model t1 failed
$call gdxdiff trnsport t1 %system.reDirLog%
$if   errorLevel 1 $abort results for trnsport and t1 are not equal

* --- use the encrypted file as an include file
$onEcho > t2.gms
$offListing
* this is hidden
option limRow=0,limCol=0,solPrint=off;
$include t1.gms
$onListing
* this will show
$offEcho
$call gams t2 license=demo lo=%gams.logOption%
$if   errorLevel 1 $abort model t2 failed

* --- protect against viewing
*     now we will show how to protect parts of an input
*     file from viewing and extracting original source
*     via the gams DUMPOPT parameter. We just need to
*     encrypt again

* --- encrypt new model
$call rm -f t3.gms
$echo $encrypt t2.gms t3.gms > s1.gms
$call gams s1 license=demo pLicense=license lo=%gams.logOption%
$if   errorLevel 1  $abort encryption failed
$call gams t3 license=demo gdx=t3 dumpOpt=11 lo=%gams.logOption%
$if   errorLevel 1 $abort model t3 failed
$call gdxdiff trnsport t3 %system.reDirLog%
$if   errorLevel 1 $abort results for trnsport and t3 are not equal

* --- check for hidden output
$call   grep "this is hidden" t3.lst > %system.nullFile%
$if not errorLevel 1 $abort did not hide in listing
$call   grep "this is hidden" t3.dmp > %system.nullFile%
$if not errorLevel 1 $abort did not hide in dump file