3.1 Introduction
This chapter provides a look at the structure of the GAMS language and its components. It should be emphasized again that GAMS is a programming language, and that programs must be written in the language to use it. A GAMS program is contained in a disk file, which is normally constructed with a text editor of choice. When GAMS is “run”, the file containing the program (the input file) is submitted to be processed. After this processing has finished the results, which are in the output file(s), can be inspected with a text editor. On many machines a few terse lines appear on the screen while GAMS runs, keeping the user informed about progress and error de-tection. But it is the responsibility of the user to inspect the output file carefully to see the results and to diagnose any errors.
The first time or casual reader can skip this chapter: the discussion of specific parts of the lan-guage in the next Chapters does not assume an understanding of this chapter.
3.2 THE STRUCTURE OF GAMS PROGRAMS
GAMS programs consist of one or more statements (sentences) that define data structures, initial values, data modifications, and symbolic relationships (equations). While there is no fixed order in which statements have to be arranged, the order in which data modifications are carried out is important. Symbols must be declared as to type before they are used, and must have values as-signed before they can be referenced in assignment statements. Each statement is followed by a semicolon except the last statement, where a semicolon is optional.
3.2.1 FORMAT OF GAMS INPUT
GAMS input is free format. A statement can be placed anywhere on a line, multiple statements can appear on a line, or a statement can be continued over any number of lines as follows:
statement;
statement;
statement; statement; statement;
the words that you are now reading is an example of a very long statement which is stretched over two lines;
Blanks and end-of-lines can generally be used freely between individual symbols or words.
GAMS is not case sensitive, meaning that lower and upper case letters can be mixed freely but are treated identically. Up to 255 characters can be placed on a line and completely blank lines can be inserted for easier reading.
GAMS PROGRAMMS 30
Not all lines are a part of the GAMS language. Two special symbols, the asterisk '*' and the dol-lar symbol '$' can be used in the first position on a line to indicate a non-language input line. An asterisk in column one means that the line will not be processed, but treated as a comment. A dollar symbol in the same position indicates that compiler options are contained in the rest of the line.
Multiple files can be used as input through the use of the $include facility described in Ap-pendix C. In short, the statement,
$include file1
inserts the contents of the specified file (file1 in this case) at the location of the call. A more complex versions of this is the $batinclude which is described in Appendix C.
3.2.2 CLASSIFICATION OF GAMS STATEMENTS Each statement in GAMS is classified into one of two groups:
• declaration and definition statements; or
• execution statements
A declaration statement describes the class of symbol. Often initial values are provided in a dec-laration, and then it may be called a definition. The specification of symbolic relationships for an equation is a definition. Execution statements are instructions to carry out actions such as data transformation, model solution, and report generation.
Declarative Statements Execution Statements
Although there is great freedom about the order in which statements can be placed in a GAMS program, certain orders are commonly used. The two most common arrangements are discussed in the next sub-section.
3.2.3 ORGANIZATION OF GAMS PROGRAMS
The two most common ways of organizing GAMS programs are shown below. The first style places the data first, followed by the model and then the solution statements. In this style of or-ganization, the sets are placed first. Then the data are specified with parameter, scalar, and table statements. Next the model is defined with the variable, equation declaration, equation definition, and model statement. Finally the model is solved and the results are displayed.
3.3 DATATYPES AND DEFINITIONS 31
A second style emphasizes the model by placing it before the data. This is a particularly useful order when the model may be solved repeatedly with different data sets. There is a separation between declaration and definition.
For example, sets and parameters may be declared first with the statements
set c "crops" ;
parameter yield "crop yield" ;
and then defined later with a statement:
set c / wheat, clover, beans/ ; parameter yield / wheat 1.5
clover 6.5 beans 1.0 / ;
The first statement declares that the identifier c is a set and the second defines the elements in the set
Sets and parameters used in the equations must be declared before the equa-tions are specified; they can be defined, however, after the equation specifica-tions but before a specific equation is used in a solve statement. This gives GAMS programs substantial organizational flexibility.
3.3 DATA TYPES AND DEFINITIONS
There are five basic GAMS data types and each symbol or identifier must be declared to belong to one of the following groups:
GAMS PROGRAMMS 32
sets
parameters acronyms
variables equations models
scalars and tables are not separate data types but are a shorthand way to declare a symbol to be a parameter, and to use a particular format for initializing the numeric data.
Definitions have common characteristics, for example:
parameter a (i,j) input-output matrix
data-type-keyword identifier domain list text
The domain list and the text are always optional characteristics. Other examples are:
set time time periods;
model turkey turkish fertilizer model ; variables x,y,z ;
In the last example a number of identifiers (separated by commas) are declared in one statement.
3.4 LANGUAGE ITEMS
Before proceeding with more language details, a few basic symbols need to be defined and the rules for recognizing and writing them in GAMS established. These basic symbols are often called lexical elements and form the building blocks of the language. They are:
characters text
reserved words and tokens numbers identifiers (indents) delimiters
labels comments
Each of these items are discussed in detail in the following sub-sections.
As noted previously, we can use any mix of lower and upper case. GAMS makes no distinction between upper and lower case.
3.4.1 CHARACTERS
A few characters are not allowed in a GAMS program because they are illegal or ambiguous on some machines. Generally all unprintable and control characters are illegal. The only place where any character is legal is in an ‘$ontext-$offtext’ block as illustrated in the section on comments below. For completeness the full set of legal characters are listed below. Most of the uncommon punctuation characters are not part of the language, but can be used freely in text or comments.
3.4 LANGUAGE ITEMS 33 A to Z alphabet a to z alphabet 0 to 9 numerals
& ampersand " double quote # pound sign
* asterisk = equals ? question mark
@ at > greater than ; semicolon
\ back slash < less than ' single quote
: colon - minus / slash
, comma ( ) parenthesis space
$ dollar [ ] square brackets _ underscore
. dot { } braces ! exclamation mark
+ plus % percent ^ circumflex
3.4.2 RESERVED WORDS
GAMS, like computer languages such as C and Pascal, uses reserved words (often also called keywords) that have predefined meanings. It is not permitted to use any of these for one's own definitions, either as identifiers or labels. The complete list of reserved words are listed below. In addition, a small number of symbols constructed from non-alphanumeric characters have a meaning in GAMS.
Identifiers are the names given to sets, parameters, variables, models, etc. GAMS requires an identifier to start with a letter followed by more letters or digits. The length of an identifier is currently limited to 10 characters. Identifiers can only contain alphanumeric characters (letters or numbers). Examples of legal identifiers are:
a a15 revenue x0051
GAMS PROGRAMMS 34
whereas the following identifiers are incorrect:
15 $casg muchtoolong milk&meat
A name used for one data type cannot be reused for another.
3.4.4 LABELS
Labels are set elements. They may be up to 31 characters long and can be used in quoted or un-quoted form.
The unquoted form is simpler to use but places restrictions on characters used, in that any un-quoted label must start with a letter or digit and can only be followed by letters, digits, or the sign characters + and - . Examples of unquoted labels are:
Phos-Acid 1986 1952-53 A September H2S04 Line-1
In quoted labels, quotes are used to delimit the label, which may begin with and/or include any legal character. Either single or double quotes can be used but the closing quote has to match the opening one. A label quoted with double quotes can contain a single quote (and vice versa). Most experienced users avoid quoted labels because they can be tedious to enter and confusing to read.
There are a couple of special circumstances. If one wants to make a label stand out, then one can, for instance, put asterisks in it and indent it. A more subtle example is that GAMS keywords can be used as labels if they are quoted. If one needs to use labels like no, ne or sum then they will have to be quoted. Examples of quoted labels are:
'*TOTAL*' 'MATCH' '10%INCR' '12”/FOOT' 'LINE 1'
Labels do not have a value. The label '1986' does not have the numerical value 1986 and the label '01' is different from the label '1'.
The rules for constructing identifiers and labels are as shown below.
Identifiers Unquoted Labels Quoted Labels
Number of Characters 10 31 31
Must Begin With A letter A letter or a number Any character Permitted Special Characters None +or – characters Any but the starting
quote 3.4.5 TEXT
Identifiers and simple labels can also be associated with a line of descriptive text. This text is more than a comment: it is retained by GAMS and is displayed whenever results are written for the identifier.
Text can be quoted or unquoted. Quoted text can contain any character except the quote character used. Single or double quotes can be used but must match. Text has to fit on one line and cannot exceed 80 characters in length. Text used in unquoted form must follow a number of mild re-strictions. Unquoted text cannot start with a reserved word, '..' or '=' and must not include semi-colon ';', commas ',', or slashes '/'. End of lines terminate a text. These restrictions are a direct consequence of the GAMS syntax and are usually followed naturally by the user. Some examples are:
3.4 LANGUAGE ITEMS 35
this is text
final product shipment (tpy)
“quoted text containing otherwise illegal characters ; /,”
'use single quotes to put a "double" quote in text'
3.4.6 NUMBERS
Numeric values are entered in a style similar to that used in other computer languages Blanks can not be used in a number: GAMS treats a blank as a separator.
.
The common distinction between real and integer data types does not exist in GAMS. If a number is used without a decimal point it is still stored as a real number.
In addition, GAMS uses an extended range arithmetic that contains special symbols for infinity (INF), negative infinity (-INF), undefined (UNDF), epsilon (EPS), and not available (NA). One cannot enter UNDF; it is only produced by an operation that does not have a proper result, such as division by zero. All the other special symbols can be entered and used as if they were ordinary numbers.
The following example shows various legal ways of entering numbers:
0
The letter e denotes the well-known scientific notation allowing convenient representation of very large or small numbers.
For example:
1e-5 = 1 * 10-5 = 0.00001 3.56e6 = 3.56 *106 = 3,560,000
GAMS uses a smaller range of numbers than many computers are able to han-dle. This has been done to ensure that GAMS programs will behave in the same way on a wide variety of machines, including personal computers. A good general rule is to avoid using or creating numbers with absolute values greater than 1.0e+20.
A number can be entered with up to ten significant digits on all machines, and more on some.
3.4.7 DELIMITERS
As mentioned before, statements are separated by a semicolon ';'. However, if the next statement begins with a reserved word (often called keyword in succeeding chapters), then GAMS does not require that the semicolon be used.
The characters comma ',' and slash '/' are used as delimiters in data lists, to be introduced later.
The comma terminates a data element (as does an end-of-line) and the slash terminates a data list.
GAMS PROGRAMMS 36
3.4.8 COMMENTS
A comment is an explanatory text that is not processed or retained by the computer. There are three ways to include comments in a GAMS program.
The first, already mentioned above, is to start a line with an asterisk '*' in the first character po-sition. The remaining characters on the line are ignored but printed on the output file.
The second is to use special ‘block’ delimiters that cause GAMS to ignore an entire section of the program. The $ symbol must be in the first character position. The choice between the two ways is a matter of individual taste or utility. The example below illustrates the use of the block comment.
$ontext
Following a $ontext directive in column 1 all lines are ignored by GAMS but printed on the output file until the matching $offtext is encountered, also in column 1.This facility is often used to logically remove parts of programs that are not used every time, such as statements producing voluminous
reports.Every $ontext must have a matching $offtext in the same file
$offtext
The third style of comment allows embedding a comment within a line. It must be enabled with the compiler option $inlinecom or $eolcom as in the following example.
$eolcom #
$inlinecom {}
x = 1 ; # this is a comment
y = 2 ; { this is also a comment } z = 3 ;
3.5 SUMMARY
This completes the discussion of the components of the GAMS language. Many unfamiliar terms used in this chapter have been further explained in the Glossary.