Dollar Control Options

# 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, Macros in GAMS, Compressing and Decompressing Files, and Encrypting Files. ## 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
offMargin Turn margin marking off
offText Turn text mode off
onMargin Turn margin marking on
onText Turn text on: the following lines are comment

## 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
offExternalInput End of external input section
offGlobal Disallow inheritance of parent file settings
offIDCProtect Allow to change external input symbols at execution time
offSuffixDLVars Do not allow domain limited variables with suffixes in model
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 zero as EPS
onExternalInput Start of external input section
onGlobal Force inheritance of parent file settings
onIDCProtect Protect external input symbols from being changed at execution time
onSuffixDLVars Allow domain limited variables with suffixes in model
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
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
offExternalOutput End of external output section
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
offUpper Following print to listing file is mixed cased
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
onExternalOutput Start of external output section
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
onUpper Following print to listing file is all upper cased
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
call.checkErrorLevel Execute another program during compilation and raise error in case of problem
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
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
hiddenCall.checkErrorLevel Execute another program (hidden) during compilation and raise error in case of problem
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 offCheckErrorLevel Do not check errorLevel automatically after$[hidden]call
offEmbeddedCode Ends embedded code section
offFiltered Turn behavior of $load* to domain checked read 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 onCheckErrorLevel Throw compilation error, if errorLevel is not 0 after$[hidden]call
onEmbeddedCode Starts embedded code section with substitution
onEmbeddedCodeS Starts embedded code section with substitution
onEmbeddedCodeV Starts embedded code section without substitution
onFiltered Turn behavior of $load* to filtered read onMulti Turn redefinition of data on (merging into existing data) onMultiR Turn redefinition of data on (replacing existing data) onOrder lag and lead operations on constant and ordered sets only onRecurse Enable recursive include files onStrictSingleton Error if data statement for singleton set has multiple elements maxGoTo Maximum number of jumps to the same label phantom 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 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 loadFiltered Load symbols from GDX file - domain filtered loadFilteredM Load symbols from GDX file - domain filtered - merge loadFilteredR Load symbols from GDX file - domain filtered - replace loadM Load symbols from GDX file - merge loadR Load symbols from GDX file - replace offExternalInput End of external input section offExternalOutput End of external output section offFiltered Turn behavior of$load* to domain checked read
onExternalInput Start of external input section
onExternalOutput Start of external output section
onFiltered Turn behavior of $load* to filtered read 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 eval.Set Evaluate and define a scoped compile-time variable based on a GAMS set evalGlobal Evaluate and define a global compile-time variable evalGlobal.Set Evaluate and define a global compile-time variable based on a GAMS set evalLocal Evaluate and define a local compile-time variable evalLocal.Set Evaluate and define a local compile-time variable based on a GAMS set prefixPath Prefix the environment variable PATH. scratchFileName Set a name for a temporary file in the scratch directory using the scratch file extension setArgs Define local compile-time variables using argument list setComps Unpack dotted names into compile-time variables setDDList Check double dash GAMS parameters setDDList.Cont Start list of identifiers to 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).
• One has to take special care when the first argument of the command contains spaces (for example an executable with absolute path), e.g.:
    $call C:\path with spaces\gams.exe trnsport.gms This would fail, since the command processor would try to call C:\path as the executable. So, one might think that protecting the spaces using quotes will resolve this problem: $call "C:\path with spaces\gams.exe" trnsport.gms
However, the quotes delimit the entire $call command, so that trnsport.gms gets interpreted as new dollar control option instead of an argument for the executable. The solution is to use nested quotes: One pair to delimit the $call command and another one to protect the spaces of the executable like this:
    $call '"C:\path with spaces\gams.exe" trnsport.gms' It gets even more complicated if the argument contains spaces as well, e.g. if we have my model.gms instead of trnsport.gms. On UNIX, another pair of quotes solves this: $call '"C:\path with spaces\gams.exe" "my model.gms"'
However, this does not work on Windows. Here, even one more pair of quotes is needed (which does not work on UNIX):
    $call '""C:\path with spaces\gams.exe" "my model.gms""' A platform independent solution for this issue looks like this: $call 'cd . && "C:\path with spaces\gams.exe" "my model.gms"'

See also $call.Async,$call.checkErrorLevel, $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.$call.checkErrorLevel

Syntax:

$call.checkErrorLevel [=]command  $call.checkErrorLevel works like $call but checks the errorLevel implicitly and raises a compilation error, if that is not 0. Example: $call.checkErrorLevel gams trnsport


This is doing the same as:

$call gams trnsport$ifE errorLevel<>0 $abort 'Problem calling gams trnsport' $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$eval.Set, $evalGLobal,$evalLocal, $ifE, and$set.

$eval.Set Syntax: $eval.Set VARNAME SETID[.[First|Last]TE|[First|Last]TL|[First|Last]TN|TS]


This option evaluates an attribute of a GAMS set at compile time and places it into a scoped compile-time variable. VARNAME is the name of a compile-time variable and SETID is the identifier of a GAMS set. The following attributes are allowed in this context:

Attribute Description
[First OR Last]TE Explanatory text of the first or last element of the set SETID
[First OR Last]TL Label of the first or last element of the set SETID
[First OR Last]TN Set identifier with with element labels of the first or last element of the set SETID
TS Explanatory text of the set SETID. This is also the default, if no attribute is specified
Note
• First?? and ?? are synonyms in the table above. It always accesses the first element of the referenced set.
• Last?? always accesses the last element of the referenced set.
• For Singleton Sets First??, Last?? and ?? are synonyms.

Example:

Singleton Set h Greeting / Hello          'Welcome' /;
Set           p Person   / Mr.President   'Male'
Mrs.Chancellor 'Female'  /;

$eval.Set X h.TE$log %X%
$eval.Set X p.lastTL$log %X%
$eval.Set X p.FirstTN$log %X%


This will generate the following in the log:

Welcome
Mrs.Chancellor
p('Mr','President')


See also $eval,$evalGLobal.Set, $evalLocal.Set, 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.$evalGlobal.Set

Syntax:

$evalGlobal.Set VARNAME SETID[.[First|Last]TE|[First|Last]TL|[First|Last]TN|TS]  This option evaluates an attribute of a GAMS set at compile time and places it into a global compile-time variable. The syntax and behavior otherwise is identical to$eval.Set.

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

Syntax:

$evalLocal.Set VARNAME SETID[.[First|Last]TE|[First|Last]TL|[First|Last]TN|TS]  This option evaluates an attribute of a GAMS set at compile time and places it into a local compile-time variable. The syntax and behavior otherwise is identical to$eval.Set.

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

Syntax:

$hiddenCall.checkErrorLevel [=]command  This option does the same as$call.checkErrorLevel 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. Note that text files that have been compressed with Posix utility gzip or have been encrypted with tool ENDECRYPT are also allowed. 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.

$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 standard locations. Note that the list of default directories searched may be prepended with the command line parameter libIncDir.

Example:

$libInclude abc x y  This call will first look for the include file inclib/abc in the standard locations. If this file does not exist there GAMS will look for the file inclib/abc.gms in the standard locations. 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 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

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. This is basically the opposite of$loadFiltered. 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.$loadFiltered

Syntax:

$loadFiltered [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]  This option is an alternative form of$load, in particular, it works like $load while$onFiltered is set. That means, when items are loaded, domain violations are not flagged as compilation errors, but items violating the domain definition are just filtered out. This is basically the opposite of $loadDC. 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 / seattle /
j / new-york, chicago /;
Parameter a(i), b(j);
$gdxIn transsol$loadFiltered a
$loadDC b$gdxIn


While $loadFiltered a does not generate an error, but just ignores the data that does not match the defined domain, $loadDC b triggers a domain violation error.

See also $loadFilteredM and$loadFilteredR.

$loadFilteredM Syntax: $loadFilteredM [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]


This option combines the functionality of merging as in $loadM and domain filtering as in$loadFilterd.

Example:

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

Set i, uni 'all labels';
Parameter abFilter(i), ab(uni) 'capacity and demand';
$gdxIn transsol$load          i abFilter=a
$loadFilteredM abFilter=b$loadFilteredM uni=i uni=j ab=a ab=b
$gdxIn Display uni, ab, abFilter;  Here we try to merge parameters a and b together into one parameter. The first attempt (to merge it into parameter abFilter) does not add anything, since the elements in b do not match the defined domain i (compare$loadFilterd). 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. The Display statement produces the following output:

----     31 SET uni  all labels

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

----     31 PARAMETER ab  capacity and demand

seattle   350.000,    san-diego 600.000,    new-york  325.000,    chicago   300.000,    topeka    275.000

----     31 PARAMETER abFilter  capacity of plant i in cases

seattle   350.000,    san-diego 600.000


$loadFilteredR Syntax: $loadFilteredR [sym1[,] sym2=gdxSym2[,] sym3<[=]gdxSym3[.dimI][,] ...]


This option combines the functionality of replacing data as in $loadR and domain filtering as in$loadFilterd.

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$loadFilteredM uni=i uni=j ab=a
$loadFilteredR 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:

----     31 SET uni  all labels

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

----     31 PARAMETER ab  capacity and demand

new-york 325.000,    chicago  300.000,    topeka   275.000


$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]CheckErrorLevel ($offCheckErrorLevel)

Syntax:

$onCheckErrorLevel$offCheckErrorLevel


If the option $onCheckErrorLevel is active, the errorLevel is checked implicitly after$call and $hiddenCall and a compilation error is triggered if it is not 0. With $offCheckErrorLevel, this is not done, but one can do it explicitly. So, with $onCheckErrorLevel$call behaves like $call.checkErrorLevel and$hiddenCall behaves like $hiddenCall.checkErrorLevel.$[on][off]Delim    ($offDelim) Syntax: $onDelim
$offDelim  This option controls whether data in table statements may be entered in delimited format. As delimiter one can use ".", ",", or "TAB". 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  Historically, GAMS has run on widely different platforms where even the floating-point arithmetic varied. To ensure the precision specified in the GAMS input didn't exceed what could be stored and computed with as GAMS ran, we limited the precision (i.e. the number of significant digits used for numbers) that could be specified in the GAMS source. This limit could be relaxed by using the $offDigit control.

Modern computers all support IEEE double-precision arithmetic, and GAMS uses this internally. It's a well-accepted and familiar standard, and the current behavior - to convert the decimal value in the GAMS source into the nearest double-precision value, regardless of the number of digits in the GAMS source - is what is generally expected. There is a limit (currently 40) on the number of digits treated as potentially significant: digits beyond this point are quietly treated as zero.

The $offDigit control remains useful for changing how GAMS handles numbers with very large or small magnitude. With $onDigit, GAMS throws compiler warnings/errors for these values. With $offDigit, GAMS quietly converts them to UNDF or EPS, respectively. Example: scalar aboveTheLimit / 222e299 /; scalar tiny / 1.0e-275 /; scalar tinier / 1.0e-285 /;$offdigit
scalar uberTheLimit / 222e299 /;
scalar klein   / 1.0e-275 /;
scalar kleiner / 1.0e-285 /;


The resulting listing file will contain the following lines:

   1  scalar aboveTheLimit / 222e299 /;
****                               $106 2 scalar tiny / 1.0e-275 /; ****$595
3  scalar tinier / 1.0e-285 /;
****                         $594 5 scalar uberTheLimit / 222e299 /; 6 scalar klein / 1.0e-275 /; 7 scalar kleiner / 1.0e-285 /; Error Messages 106 abs(number) out of range abs(number) must be less than 1E300$offdigit can be used to replace large numbers with UNDF
594  Exponent very very small - rejected
$offdigit can be used to replace with EPS 595 Exponent very small$offdigit can be used to quietly accept very small values


$[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 {symbol[<[=]embSymbol[.dimX]]}


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. The syntax symbol<[=]embSymbol[.dimX] allows to load a one dimensional set from a symbol which was set in the embedded code that has even a higher dimensionality (here we call <[=] the projection operator). GAMS tries to find the set symbol as a domain in the symbol embSymbol 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 .dimX allows to pick a fixed index position (X needs to be replaced by the desired index position). 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]))
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  Using the projection operator the same task could be done like this: 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 = []
for cc in gams.get("cc"):
r = str.split(cc, " - ", 1)
mccCountry.append((cc,r[0]))
mccCity.append((cc,r[1]))
gams.set("mccCountry",mccCountry)
gams.set("mccCity",mccCity)
$offEmbeddedCode country<mccCountry city<mccCity mccCountry mccCity Option mccCountry:0:0:1, mccCity:0:0:1; Display country, city, mccCountry ,mccCity;  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" /  / ;
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" /  / ;
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 interpret zero values as EPS when non-scalar parameters, variable attributes, or equation attributes are defined or loaded (e.g. from GDX or embedded code ) at compile time. This can for example be useful if the value of zero is overloaded with existence interpolation. See option zeroToEps for the execution-time equivalent. Example 1: Consider the following example where zero values are defined for a one dimensional parameter, once under $onEps and $offEps. 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 as EPS. Example 2: Consider the following example where zero values are loaded from a GDX file, once under $offEps (default) and $onEps (derived from test library model [ZEROTOEPS1] ). Set s,t; Parameter p(s<,t<) pOnEps(s,t);$gdxIn zeropar.gdx
$onText P looks like this: t1 t2 t3 s1 0 0.843267 s2 0.224053 0.349831 0 s3 0 5$offText
$load p$onEps
$load pOnEps=p display p, pOnEps;  The outcome generated by the display statement follows: ---- 15 PARAMETER p t1 t2 t3 s1 0.843 s2 0.224 0.350 s3 5.000 ---- 15 PARAMETER pOnEps t1 t2 t3 s1 EPS 0.843 s2 0.224 0.350 EPS s3 EPS 5.000  Example 3: Consider the following example where zero values are loaded from embedded Python code, once under $offEps (default) and $onEps (derived from test library model [ZEROTOEPS1] ). Set s / s1*s3 /; Parameter pEC(s) pECOnEps(s);$onEmbeddedCode Python:
p = [('s1',1), ('s3',0)]
gams.set('pEC',p)
$offEmbeddedCode pEC$onEps
$onEmbeddedCode Python: p = [('s1',1), ('s3',0)] gams.set('pECOnEps',p)$offEmbeddedCode pECOnEps

display pEC, pECOnEps;


The outcome generated by the display statement follows:

----     14 PARAMETER pEC

s1 1.000

----     14 PARAMETER pECOnEps

s1 1.000,    s3   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]ExternalInput ($offExternalInput) Syntax: $onExternalInput
$offExternalInput  $onExternalInput and $offExternalInput mark the beginning and end of a well defined section in which data is loaded implicitly from an external data source, namely from a GDX file specified by the command line parameter IDCGDXInput. Note • If none of the command line parameters IDCGDXInput, IDCGenerateGDXInput, IDCJSON, IDCGenerateJSON, or IDCGenerateGDX is set, nothing - but a few checks for consistency - will happen by setting $onExternalInput and $offExternalInput. • If at least one of the before mentioned command line parameters is set, an additional license check will be triggered: Without the MIRO Connector License not more than 5 indexed symbols can be declared as external input or external output. For symbols, which are declared, while $onExternalInput is active, data in data statements of the declaration is ignored. Instead, the data is loaded from the GDX file specified by IDCGDXInput. Also for those symbols, if they are referenced with $load* or$offEmbeddedCode while $onExternalInput is active, the data is loaded from the GDX file specified by IDCGDXInput instead of the defined data source and symbol renaming as well as the projection operator are ignored in this case. In addition, the following dollar control options are ignored, while $onExternalInput is active and IDCGDXInput is set:

Example:

Lets look at a modified version of the simple example presented here:

Set
i 'canning plants'
j 'markets';

$onExternalInput$call mdb2gms I=Sample.mdb Q="SELECT city1, city2, distance FROM distances" O=distances.inc
Parameter d(i<,j<) 'distance in thousands of miles' /
$include distances.inc /;$offExternalInput

display d;


Without setting a command line parameter, this runs in the same way as described in the other chapter, so by default, setting $onExternalInput and $offExternalInput does not make much of a difference. Now, lets run it with IDCGDXInput being set to transsol, which is a GDX file generated by running the transportation model [TRNSPORT]. There will be some new messages in the log:

--- GDXin=transsol.gdx
--- Distances1.gms(7) 2 Mb
--- Ignoring $call in externalInput section --- Distances1.gms(9) 2 Mb --- Ignoring$include in externalInput section


First, we notice, that the file transsol.gdx will be opened for input. This happens implicitly with $onExternalInput. Then, both the $call as well as the $include lines were ignored, since we do not want to query the data source explicitly defined in the model, but the GDX file defined by IDCGDXInput. Note, that the data statement in the declaration of d is actually empty when we ignore the $include statement. While $onExternalInput this does not lead to an error, but behaves as if$onEmpty was set. Looking at the output of the display statement in the lst file, one can see that the expected data was loaded:

----     13 PARAMETER d  distance in thousands of miles

new-york     chicago      topeka

seattle         2.500       1.700       1.800
san-diego       2.500       1.800       1.400


If any of the options IDCGDXInput, IDCGDXOutput, IDCJSON or their Generate versions, e.g. IDCGenerateGDXInput, has been set, a MIRO connector license is required.

See also $[on][off]ExternalOutput.$[on][off]ExternalOutput ($offExternalOutput) Syntax: $onExternalOutput
$offExternalOutput  $onExternalOutput and $offExternalOutput mark the beginning and end of a well defined section in which data is written implicitly to an external data file, namely to a GDX file specified by the command line parameter IDCGDXOutput or IDCGenerateGDXOutput. Note • If none of the command line parameters IDCGDXOutput, IDCGenerateGDXOutput, IDCJSON, IDCGenerateJSON, or IDCGenerateGDX is set, nothing - but a few checks for consistency - will happen by setting $onExternalOutput and $offExternalOutput. • If at least one of the before mentioned command line parameters is set, an additional license check will be triggered: Without the MIRO Connector License not more than 5 indexed symbols can be declared as external output or external input. Example: This is a slightly modified code snippet of the transportation model [TRNSPORT]: ...$onExternalOutput
Parameter c(i,j) 'transport cost in thousands of dollars per case';
c(i,j) = f*d(i,j)/1000;

Variable
x(i,j) 'shipment quantities in cases'
$offExternalOutput z 'total transportation costs in thousands of dollars'; Positive Variable x; Equation$onExternalOutput
cost      'define objective function'
$offExternalOutput supply(i) 'observe supply limit at plant i' demand(j) 'satisfy demand at market j'; ...  Without setting a command line parameter, this runs in the same way as the original model, so by default, setting $onExternalOutput and $offExternalOutput does not make much of a difference. Now, lets run it with IDCGDXOutput being set to transOut.gdx. This generate the file transOut.gdx with the following content: So, this implicit generation of the output file is basically equivalent to the following explicit statement: execute_unload 'transOut.gdx', c, x, cost;  If any of the options IDCGDXInput, IDCGDXOutput, IDCJSON or their Generate versions, e.g. IDCGenerateGDXInput, has been set, a MIRO connector license is required. See also$[on][off]ExternalInput.

$[on][off]Filtered ($onFiltered)

Syntax:

$onFiltered$offFiltered


This dollar control option controls how GAMS loads data from GDX with $load,$loadR, and $loadM. With $onFiltered the $load* calls behave like$loadFiltered* calls. With $offFiltered the $load* calls behave like $loadDC* calls. This dollar control option also controls how GAMS loads symbols on the$offEmbeddedCode line. With $onFiltered data is read filtered while $offFiltered triggers a domain check of the data. The gams.set Python function allows to overwrite the setting of this dollar control option with the argument domCheck=DomainCheckType.CHECKED or domCheck=DomainCheckType.FILTERED.

$[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]IDCProtect    ($onIDCProtect) Syntax: $onIDCProtect
$offIDCProtect  This controls if symbols which are declared as external input can be changed at execution time. With $onIDCProtect external input symbols are protected from being changed; $offIDCProtect allows it. The initial state of this can be set with the command line parameter IDCProtect.$[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
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.

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

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

Note
• There is also $onMultiR, which behaves similarly, but replaces existing data instead of merging into it. Compare the example here and there to see the difference. • When $onMulti is active $load behaves like a$loadM.

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.$onMultiR|offMulti ($offMulti) Syntax: $onMultiR
$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 replace the previous ones. Note that all multiple data statements are performed before any other statement is executed. Note • There is also$onMulti, which behaves similarly, but merges into existing data instead of replacing it. Compare the example here and there to see the difference.
• In contrast to $onMulti, $onMultiR also allows to redefine an equation and a macro.

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/$onMultiR
Parameter x(i) / i7*i9  2 /   // /i7 2,i8 2,i9 2/
Parameter x(i) / i2*i6  3 /   // /i2 3,i3 3,i4 3,i5 3,i6 3/
Parameter x(i) / i3*i5  0 /   // ( ALL       0.000 )
$offMulti display x;  Note that the repeated parameter statements would have resulted in a compilation error without the presence of the option $onMultiR. The result of the display statement in the listing file follows:

----      9 PARAMETER x

( ALL       0.000 )

Note
• When using a redefinition with $onMulitR to remove elements from a set, which was used as domain of another symbol, also the dependent symbol gets reduced. This can happen through data statements, but also with$clear and $load/$loadDC.
• When $onMultiR is active$load behaves like a $loadR. Example: Set i / i1*i5 /; Parameter p(i) / #i 3 /;$onMultiR

Set i          / i3*i6 /;
Display p;


Looking at the output from the Display statement one can see, that the entries for i1 and i2 were removed by the second definition of i:

----      7 PARAMETER p

i3 3.000,    i4 3.000,    i5 3.000

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 $onMultiR 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;$onMultiR
Scalar a /20/;
display a;


Note that the two scalar data initialization statements and the option $onMultiR 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 $onMultiR 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]Upper ($offUpper) Syntax: $onUpper
$offUpper  GAMS code echoed to the listing file is written in upper case after $onUpper. The default of mixed code echoing is restored with $offUpper. Note The default case of the echo print can be set using the command line option case. Example: Set i 'Canning plants' / seattle, san-diego / j 'Markets' / new-york, chicago, topeka /;$onupper
Parameter
a(i) 'Capacity of plant i in cases'
/ seattle    350
san-diego  600 /

$offupper b(j) 'Demand at market j in cases' / new-york 325 chicago 300 topeka 275 /;  The generated listing file looks like this:  1 Set 2 i 'Canning plants' / seattle, san-diego / 3 j 'Markets' / new-york, chicago, topeka /; 4 6 PARAMETER 7 A(I) 'CAPACITY OF PLANT I IN CASES' 8 / SEATTLE 350 9 SAN-DIEGO 600 / 10 12 b(j) 'Demand at market j in cases' 13 / new-york 325 14 chicago 300 15 topeka 275 /; $[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]SuffixDLVars ($offSuffixDLVars)

Syntax:

$onSuffixDLVars$offSuffixDLVars


This option controls if it is allowed to use suffixes on variables with limited domains in a model. By default this is not allowed but this can be changed by setting $onSuffixDLVars. Example: Set n / n1*n100 / t / t1*t10 / sub(n,t) / #n:#t /; Variable z, x(n,t); Equation obj; x.up(n,t) = uniformInt(7,13); obj.. z =e= sum((n,t),x(n,t)/x.up(n,t)); Model m / all, x(sub) /; Solve m min z use lp;  This causes the following error by default: *** Problem in Model Generation: Variable "x" appears with suffix "Up". *** Error at line 12: Cannot use domain limited variables with suffix in model - use$onSuffixDLVars to allow this


The purpose is to make the user aware of the fact, the she uses x.l, which would also be affected by the domain restriction of x(sub) in the model statement. So, if the user made sure, that this is all intended, setting $onSuffixDLVars before the solve statements overcomes this error. Though, with the example given here, this would actually lead to a "division by zero" error, since some x.up were excluded leaving a 0 as divisor. See also related command line parameter SuffixDLVars.$[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.

$[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
• The options $on/offVerbatim are only recognized for DumpOpt $$\geq$$ 10 and apply only to lines in the file between the two options • If $onVerbatim is active, DumpOpt = 11 behaves like DumpOpt = 21 (comments are kept)

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

Syntax:

$scratchFileName VARNAME [fileStem]  This option establishes or redefines the content 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; fileStem is optional and used to built the name for a file in the scratch directory with a scratch extension (unless an extension is set explicitly). If it is omitted, the system will make up a random file name. So, $scratchFileName fn abc


is equivalent to

$set fn %gams.scrDir%abc.%gams.scrExt%  Example: * Set fileStem explicitly$scratchFileName fn1 abc
$log %fn1% * Omit fileStem$scratchFileName fn2
$log %fn2%  The log will show: C:\Data\t m p\225a\abc.dat C:\Data\t m p\225a\__sFN__-0_313342928588555.dat  See also$set and section Compile-Time Variables.

$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[.Cont] Syntax: $setDDList.Cont id1 id2 ...
$setDDList id3 id4 id5 ...  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  $setDDList.Cont can be used to define a list of parameters to be checked over multiple lines. So, the following two examples do the same thing:

$setDDList one two three four  $setDDList.Cont one
$setDDList.Cont two three$setDDList      four

Note
$setDDList.Cont does not do anything without a $setDDList statement.

$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: $setLocal 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 nothing
$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=some things" -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:>some things< 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 id True 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 in the working directory or an input file directory. If no extension is specified, also filename.gms is checked. 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 is greater than or equal to n. GAMS versions are referenced with a single number. For example, if it should be tested whether the current GAMS version is 24.7 or newer, n will equal 247. Maintenance version numbers, e.g. 24.7.4 do not count.
gdxDimension n id True if id exists in a GDX file previously opened with $gdxIn and has n dimensions. Note that n may take values from 0 to maximum number of possible indexes (see Dimensions). gdxEquType id True if id exists in a GDX file previously opened with$gdxIn and is an equation.
gdxParType id True if id exists in a GDX file previously opened with $gdxIn and is a parameter. gdxSetType id True if id exists in a GDX file previously opened with$gdxIn and is a set.
gdxSymExist id True if id exists in a GDX file previously opened with $gdxIn. gdxVarType id True if id exists in a GDX file previously opened with$gdxIn and is a variable.
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_name True if a solver named solver_name exists in the GAMS system. An example is given below.
uelExist id True if unique element id exists in current GAMS database.
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 the 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

### 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 that 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.

Usually programs return 0 on success and non-zero on failure. The $if errorlevel 1 checks for strictly positive return codes. There are rare cases with failures and negative return codes (e.g. on Windows if some DLL dependencies of the program can't be resolved). In such a case $if errorlevel 1 will evaluate to false and not continue with the $abort instruction. It might be better to access the program return code via the errorLevel function in the following way: $call gams mymodel.gms lo=2
$ifE errorLevel<>0$abort one or more errors encountered


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

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;


Note that the macro use cannot be spread over multiple lines. Single line use with more complex arguments as in

z = reciprocal(x1+x2);


is recognized and will expanded to:

z = 1/x1+x2;


Note that z will be equal to 3.5 in this example as division takes precedence over addition. But breaking the argument of the macro over multiple lines as follows will trigger a macro expansion error:

z = reciprocal(x1
+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 after stripping leading white spaces of the second line 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 this: z = not 1 and 0 or 1 and not 0;  The &, explained in more detail in the next section can be used to preserve (some of the) leading white spaces (but not the line breaks) if that is desired: $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/;


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. There are two way to encrypt a file: Encryption for a particular user group that is identified by a target license file or for a general wide audience. In the prior case the key for encryption and decryption is extracted from the target license (specified by command line parameter pLicense) while for the latter the key for encryption and decryption is passed to GAMS via the command line parameters encryptKey and decryptKey. 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 via a target license: > gamslib -q trnsport > echo$encrypt trnsport.gms t1.gms > t2.gms


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 can be located in various system wide and user locations. 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. An alternative approach to encrypt GAMS source file without a target license is done by the pair of command line parameters encryptKey and decryptKey: > gamslib -q trnsport > echo$encrypt trnsport.gms t1.gms > t2.gms


In the third line, the command line parameter encryptKey specifies the encryption key. Thus the new encrypted file t1.gms is locked and requires this key to successfully decrypt via command line parameter decryptKey:

> gams t1 decryptKey=ThisIsAPasswordSomeoneNeedsToRunTheModel


Anyother key will result in a failure with the message Integrity check failed.

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 decrypting 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. $title Input File Encryption Demo (ENCRYPT,SEQ=318)

$onText Input files can be encrypted with an encryption key. Either the privacy license file mechanism or the command line parameter pair encryptKey/decryptKey can be for managing the password. Similar to compression, we offer an$encrypt utility to lock any file to a
specific key. Once a file has been encrypted it can only be read
by a gams program that has the matching license file or the matching
decryption key. There is no inverse operation possible: you cannot recover
the original GAMS file from the encrypted version.

To create an encrypted file, we need a license file which has the
security option enabled.

Keywords: GAMS language features, input file encryption
$offText$if not set MYPLICENSE $set MYPLICENSE "%gams.sysdir%plicense.txt"$ifthen not exist "%MYPLICENSE%"
$log *** Target license file "%MYPLICENSE%" does not exist.$   log *** Specify via --MYPLICENSE=...
$log *** Encryption only via en/decryptKey$   drop MYPLICENSE
$endif * --- get model$onDollar
$call gamslib -q trnsport$ifthen.MYPLICENSE set MYPLICENSE
* --- encrypt and try to decrypt
$call rm -f t1.gms$echo $encrypt trnsport.gms t1.gms > s1.gms$call gams s1 plicense="%MYPLICENSE%" lo=%gams.lo%
$ifE errorLevel<>0$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.lo%
$ifE errorLevel<>0$abort model trnsport failed
$call gams t1 license="%MYPLICENSE%" gdx=t1 lo=%gams.lo%$ifE  errorLevel<>0 $abort model t1 failed$call gdxdiff trnsport t1 %system.reDirLog%
$ifE errorLevel<>0$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="%MYPLICENSE%" lo=%gams.lo%
$ifE errorLevel<>0$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 plicense="%MYPLICENSE%" lo=%gams.lo%
$ifE errorLevel<>0$abort encryption failed
$call gams t3 license="%MYPLICENSE%" gdx=t3 dumpopt=19 lo=%gams.lo%$ifE errorLevel<>0 $abort model t3 failed$call gdxdiff trnsport t3 %system.reDirLog%
$ifE errorLevel<>0$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
$endif.MYPLICENSE * Same with encryptKey/decryptKey * --- encrypt and try to decrypt$call rm -f t1.gms
$echo$encrypt trnsport.gms t1.gms > s1.gms
$call gams s1 encryptKey=ThisIsMyPassword lo=%gams.lo%$ifE  errorLevel<>0     $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.lo%$ifE  errorLevel<>0 $abort model trnsport failed$call gams t1 decryptKey=ThisIsMyPassword gdx=t1 lo=%gams.lo%
$ifE errorLevel<>0$abort model t1 failed
$call gdxdiff trnsport t1 %system.reDirLog%$ifE  errorLevel<>0 $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 decryptKey=ThisIsMyPassword lo=%gams.lo%$ifE  errorLevel<>0 $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 encryptKey=ThisIsMyPassword lo=%gams.lo%$ifE errorLevel<>0  $abort encryption failed$call gams t3 decryptKey=ThisIsMyPassword gdx=t3 dumpopt=19 lo=%gams.lo%
$ifE errorLevel<>0$abort model t3 failed
$call gdxdiff trnsport t3 %system.reDirLog%$ifE errorLevel<>0 $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
`