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
computerName Operating system computer name
date Job date
date1 Job date (different format)
dirSep File or directory separator in file names, either \ or /
elapsed Elapsed time in seconds since start of job
FE File extension of input file
fileSys Name of the operating system
FN File name stem of input file
FP File path of input file
gamsReleaseMaint GAMS Release number with maintenance number suffix
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 Main input file
iLine Current source line number being executed
incLine Line number of include file being executed
incName Name of include file
incParent Parent file of include file
incParentL Line number of parent file of include file
isAlfaBeta Indicates an Alfa or Beta distribution
lice1 License display line 1
lice2 License display line 2
licenseDateEvalN Evaluation date (serial number)
licenseDateEvalS Evaluation date (date format)
licenseDateMaintN Maintenance date (serial number)
licenseDateMaintS Maintenance date (date format)
licenseDateN License date (serial number)
licenseDateS License date (date format)
licenseDateSysN GAMS module system date (serial number)
licenseDateSysS GAMS module system date (date format)
licenseDaysEval License evaluation days left
licenseDaysMaint License maintenance days left
licenseDC License number
licenseEval License is eval license
licenseID License ID string
licenseInstitution License holding institution
licenseLevelText GAMS license level text
licenseLicensee License Holder
licenseMudText License MUD type
licensePlatform License Platform abbreviation
licensePlatformText License Platform Text
licenseStatusText License validation status text
licenseType License type
licenseVendor License Vendor
line Line number in source code
listLine Line number on listing file
maxInput Max input line length that can be processed
memory Memory (in Mb) in use
model_type (LP, MIP, ...) Solver that is active for the respective GAMS model type (for example, LP or MIP)
nullFile The null filename (e.g. on Unix /dev/null)
oFile Output (Listing) file
oPage Current page number in output (listing) file
page Current page number
pFile Current put file
platform Job platform (computer type)
prLine Line on listing file page
prPage Listing file page number
putFileName The filename of the currently active put file
rDate Restart file date
reDirLog Append redirection string into the logfile, e.g. >> mylog.log
rFile Restart file name
rTime Restart file time
sFile Save file name
sString Subsystem (Solver) audit string (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
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
gamsParameters 1 Command line parameters
gamsParameterSynonyms 1 Synonyms for command line parameters
gamsParameterSynonymMap 2 Map between command line parameters and their synonyms
gamsFunctions 1 Intrinsic functions
modelTypes 1 Model types, e.g. LP, MIP, ...
platforms 1 Platform code
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

Here is a secondary list of system attributes provide access to system data. This information allows to print the license memorandum [LICEMEMO] and is only used for internal purposes:

System Data Dimension
clipCodes 1
components 1
clipComponentMap 2
componentSolverMap 2
gamsLicenseTypes 1
gamsLicenses 1
vendors 1

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
sets s / s1*s%digits% /, b / 0,1 /;
$eval nMax power(card(b),card(s))
sets 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);