System Attributes

Introduction

System attributes give access to string constants in the GAMS system environment. We will refer to these string constants as system suffixes. Moreover, there are attributes that can be used as data elements for user symbols. This way one can get access e.g. to the solvers (as set elements) in the system. We will refer to these data elements as system data. Two special system data attributes, namely powerSetLeft and powerSetRight, for a three dimensional set setName(n,s,b) create data which can be interpreted as a numbering system with base b and s digits. Finally, a system attribute can provide access to a system function that was hidden by the compiler because of a name conflict with a user symbol.

System Suffixes

System suffixes contain information about the GAMS system environment during a run. There are two ways to reference them: system.suffix and %system.suffix%. Here system is a keyword and .suffix is the name of the system suffix. A full list is given in section List of all System Suffixes below. Note that system.suffix references the execution-time version of the system suffix and %system.suffix% references the compile-time version resulting in a textual replacement. The execution-time system suffix can only be used in the context of put files. Consider the following example where both versions are used:

file fx;
put fx 'lp:' system.LP;
option lp=gurobi;
put  / 'lp:' system.LP
put  / 'lp:%system.LP%';

Observe that the compile-time string %system.LP% is evaluated at compile time and does not change. However, the execution-time system suffix system.LP is evaluated at execution time and it does change. It is first CPLEX, since CPLEX is the default LP solver. Then it changes to GUROBI as a result of the execution-time command option LP=gurobi;. The resulting put file fx.put follows:

lp:CPLEX
lp:GUROBI
lp:CPLEX

In the following two subsection we will discuss execution-time suffix in more detail.

Execution-Time System Suffixes

Execution-time system suffixes are only used in the context of the put writing facility with commands like put , putclose and put_utility. Consider the following simple example. We have the files x.gms and dummy.gms, where x.gms contains just the following line:

file fx; put fx system.version;

The file dummy.gms contains the following:

$exit;

We run these files with the following calls:

  > c:\gams\win64\24.7\gams x.gms action=c s=putVersion

Note that the value c for the command-line parameter action causes the first input file to be compiled only. The result is saved in the work file putVersion. Then we restart and execute dummy.gms. Now, depending on the GAMS release version, the put file fx will have a different content:

c:\gams\win64\24.7\gams dummy.gms r=putVersion // this produces a put file with content "GAMS Rev 247"
c:\gams\win64\24.8\gams dummy.gms r=putVersion // this produces a put file with content "GAMS Rev 248"

In contrast, the value of the compile-time system suffix %system.version% is determined at compile time. Suppose we change the file x.gms to contain the following line:

file fx; put fx "%system.version%";

The file dummy.gms is not changed and we use the same calls as above. Note that the put file will have the same content for both versions of GAMS:

c:\gams\win64\24.7\gams dummy.gms r=putVersion // this produces a put file with content "GAMS Rev 247"
c:\gams\win64\24.8\gams dummy.gms r=putVersion // this produces a put file with content "GAMS Rev 247"

Compile-Time System Suffixes

Compile-time system suffixes may be placed anywhere a compile-time variables makes sense, including code for conditional compilation. The quoting of these compile-time system suffixes depends on their use in the code. Consider the following example:

$set systemDATE %system.date%
display "system.date", "%system.date%";
$ifi %system.LP% == Xpress $log "LP solver is Xpress."

The resulting output generated by the display statement follows:

----      3 system.DATE
            11/07/16

List of all System Suffixes

In the following table all system suffixes are listed.

System Suffix Description
BuildCode System build code
CNS CNS solver that is active for CNS model type
ComputerName Operating system computer name
Date Job date
Date1 Job date format
DirSep File or directory separator in file names
DNLP DNLP solver that is active for DNLP model type
Elapsed Elasped time in seconds since start of job
EMP EMP solver that is active for EMP model type
Error Used to indicate unknown suffix
ErrorLevel System Errorlevel
FE File extension
FileSys Name of the operating system (MSNT for Windows, UNIX for Linux and macOS)
FN File name
FP File path
GamsRelease GAMS Release number
GamsReleaseMaint GAMS Release number with maintenance number suffix
GamsVersion GAMS version number
GdxFileNameIn GDX file name for input, set by put_utility command gdxin
GdxFileNameOut GDX file name for output, set by put_utility command gdxout
GString GAMS system audit string (exact GAMS version being used)
HostPlatform Host platform
IFile Input file
ILine Current source line number beeing executed
IncLine Include file line
IncName Include file name
IncParent Include file parent
IncParentL Include file parent line number
IsAlphaBeta Indicates an Alpha or Beta bulid
JobHandle Job handle of last async call
LicenseFileName The file name of the license file currently used
LicenseLevel GAMS license level
Line Line number in source code
ListLine Line number on listing file
LP LP solver that is active for LP model type
MACAddress MAC address of the first network adapter
MaxInput Max input line length that can be processed
MCP MCP solver that is active for MCP model type
Memory Memory (in Mb) in use
MINLP MINLP solver that is active for MINLP model type
MIP MIP solver that is active for MIP model type
MIQCP MIQCP solver that is active for MIQCP model type
MPEC MPEC solver that is active for MPEC model type
NLP NLP solver that is active for NLP model type
NullFile The null filename
OFile Output (Listing) file
OPage Current page number in output (listing) file
Page Current page number
PFile Current put file
Platform Job platform (DEX for macOS, LEX for Linux, WEX for Windows)
PrLine Line on listing page
Procname Model types LP MIP etc
PrPage Listing page number
PutFileName The filename of the currently active PUT file
QCP QCP solver that is active for QCP model type
RDate Restart file date
ReDirLog Append redirection string into the logfile
RFile Restart file name
RMINLP RMINLP solver that is active for RMINLP model type
RMIP RMIP solver that is active for RMIP model type
RMIQCP RMIQCP solver that is active for RMIQCP model type
RMPEC RMPEC solver that is active for RMPEC model type
RTime Restart file time
SFile Save file name
SString Subsystem (Solver) audit (last solver used)
Tab Tab character
TClose Time to save GAMS
TComp Time to compile
TExec Time to execute
Time Job time
Title Current listing title
TStart Time to restart GAMS
UserConfigDir User writable directory that is searched for gamsconfig.yaml
UserDataDir User writable directory that is searched for gamslice.txt and others
UserName Operating system user name
VerID GAMS version ID
Version GAMS compiler version

A model that prints all system suffixes with its current values to a put file can be found in model [SSUFFIX].

System Data

Some of the system relevant information does not fit into a single string. Such system data can be stored in GAMS symbols. The system data for this symbol can be accessed in the data statement of the symbol, e.g. set allSolvers / system.solverNames /;. Now you can work with the solver names as you can work with any set. The system data can be viewed as an internal set, so it can be you can to create more complex GAMS symbols with this information. For example:

set seq / 1*1000 /;
set solvermap(seq,*)   / set.seq:system.solverNames /;
parameter solverpar(*) / system.solverNames 1 /;

Here is the list and dimensionality of the system data:

System Data Dimension Description
dollarOptions 1 Dollar control options
empty 1 Empty label
gamsFunctions 1 Intrinsic functions
gamsParameters 1 Command line parameters
gamsParameterSynonymMap 2 Map between command line parameters and their synonyms
gamsParameterSynonyms 1 Synonyms for command line parameters
GUSSModelAttributes 1 Model attributes stored for GUSS scenarios
modelTypes 1 Model types, e.g. LP, MIP, ...
platforms 1 Platform code
powerSetLeft 3 Numbering system with base b and s digits
powerSetRight 3 Numbering system with base b and s digits
predefinedSymbols 1 Predefined symbols, e.g. SameAs, Diag, ...
setConstants 1 System data names (this list)
solverNames 1 Names of solvers and tools
solverPlatformMap 2 Map between solvers and platforms
solverTypePlatformMap 3 Map between solvers, model types and platforms
systemSuffixes 1 System suffixes

Power Set

The very special system attribute powerSetLeft and powerSetRight do not provide access to static data relevant to the system but produce data based on existing sets b and s. This system data produced can be interpreted as a numbering system with base b and s digits. The total number of tuples created is power(card(b),card(s)). The first index of the resulting set has to have at least this size. The following small example demonstrates the functionality of powerSetRight:

$set digits 3
set s / s1*s%digits% /, b / 0,1 /;
$eval nMax power(card(b),card(s))
set n        / n1*n%nMax% /
    x(n,s,b) / system.powerSetRight /;
option x:0:0:%digits%; display x;

With 3 digits the display results in the following output:

----      6 SET x
n1.s1.0,    n1.s2.0,    n1.s3.0
n2.s1.0,    n2.s2.0,    n2.s3.1
n3.s1.0,    n3.s2.1,    n3.s3.0
n4.s1.0,    n4.s2.1,    n4.s3.1
n5.s1.1,    n5.s2.0,    n5.s3.0
n6.s1.1,    n6.s2.0,    n6.s3.1
n7.s1.1,    n7.s2.1,    n7.s3.0
n8.s1.1,    n8.s2.1,    n8.s3.1

Changing powerSetRight to powerSetLeft reassigns the order of the digits. So the lowest digit is on the left:

----      6 SET x
n1.s1.0,    n1.s2.0,    n1.s3.0
n2.s1.1,    n2.s2.0,    n2.s3.0
n3.s1.0,    n3.s2.1,    n3.s3.0
n4.s1.1,    n4.s2.1,    n4.s3.0
n5.s1.0,    n5.s2.0,    n5.s3.1
n6.s1.1,    n6.s2.0,    n6.s3.1
n7.s1.0,    n7.s2.1,    n7.s3.1
n8.s1.1,    n8.s2.1,    n8.s3.1

Access to Hidden Functions

Intrinsic functions are not keywords but they are stored in a list of predefined names. If a user program uses such a predefined name of a function for a user symbol, GAMS will hide the original function. For example,

set uniform 'School Uniform' / skirt, blouse, blazer, socks, shoes /;
scalar randomNumber; 
randomNumber = uniform(0,1);

will result in a compilation error in the second line because GAMS expects uniform to be a set. The function uniform is hidden for this GAMS program. Renaming the user symbol that hides a function is often the best solution for this, but there are a few cases (including GAMS code already compiled and stored in a restart file) where renaming is not an option. A hidden function can be accessed via the system attribute system.functionName. So the following will successfully compile and execute:

set uniform 'School Uniform' / skirt, blouse, blazer, socks, shoes /;
scalar randomNumber; 
randomNumber = system.uniform(0,1);