As you can see, all of the tools available to the GAMS-X user, including GAMS-X Script, GAMS-Tk, and GAMS-CGI are transparently integrated, and that cases and casebooks defined and solved in the GAMS-X scripting environment are mirrored in the GAMS-Tk and GAMS-CGI visual environments, and vice-versa.

As GAMS-Tk and GAMS-CGI are robust enough to justify their own chapters, the remainder of this chapter will focus on GAMS-X Script, the real power behind GAMS-X. Those users who are just getting started are encouraged to visit chapter 4 on GAMS-Tk and to explore GAMS-Tk to get a feel for the GAMS-X environment before continuing with the remainder of this chapter.

The remainder of this chapter will introduce a simple example of the power and flexibility of GAMS-X scripting, provide an introduction with all you need to know about the Perl scripting language to use the GAMS-X scripting environment, and then work through a fully developed example utilitizing the Ramsey model. Both the Ramsey model and the sample script detailed in this chapter are provided with the basic GAMS-X installation.

5.2  Programming in GAMS-X

GAMS-Tk and GAMS-CGI provide visual interfaces that allow modelers, users, and webmasters to create and manage GAMS models. However, model developers require much more versatility in their modeling tools than can be provided with a visual environment. GAMS-X scripting is the answer to that need, providing all of the tools available in GAMS-Tk and GAMS-CGI in a scripting environment, as well as all of the advantages of a high-level programming language such as advanced data structures, control flow procedures, easy formatting of textual output, and access to a well-developed and well-documented module library with such tools as PDL (Perl Data Language), OLE⁹, and Windows COM objects.

As a Perl module, GAMS-X supports a rich programming environment for those who are willing to learn just as much Perl as can be explained in a few pages.

For example, suppose you want to analyze the sensitivity of a model to its parametrization. Once the model has been installed in GAMS-X, a modeler can create a short text file that will not only generate a hundred cases, but graph them and generate a data file so that the same set of cases can be instantly reproduced at any GAMS-X (and hence GAMS-CGI) site around the world. All that is required is

use GAMS::Script;

$GAMS = new GAMS::Script;

$GAMS->Set( -User => 'Grog', -Model => 'Ramsey' );

for $i (1..100) {

  $GAMS->Set( -Case => "Case $i", -Inputs { K => $i / 100 } );
  $GAMS->AddCase;

}

Then to print out the results from all of the cases which returned a value of UTILITY.L greater than 8.0, a simple snippet of code such as the following would do the trick:

foreach $Case (grep $_->{Output}->->{'UTILITY.L'} > 8.0, @{$GAMS->UserState}) {

  print "Intertemporal utility for case $Case->{Name} is $Case->{Output}->{'UTILITY.L'}.\n"

}

Much more powerful feats are possible in the GAMS-X programming environment, but before going on more serious business, we should take a very brief diversion into Perl-style syntax.

5.3  A Perl Primer

As you know if you have already installed GAMS-X, Perl is an extremely powerful, popular, and free programming language. It was created by Larry Wall, endowed with a C-style syntax with an almost free-form programming feel.

Perl can be either scripted or compiled, unlike many programming languages such as C++ or Java. Scripted languages are those that simply accept a text file as input and execute the input contained therein, much like GAMS. GAMS-X, as a child of Perl, is itself scripted in the Perl syntax. Compiled languages, on the other hand, must be passed through a compiler, which turns the code into an executable format understandable by the computer. GAMS-X Lite is the compiled version of GAMS-X, and therefore has no scripting capabilities.

At one time, scripted languages were considered the poor cousins of compiled languages, mostly due to the fact RAM was in short supply, making the use of an extra meg for a script interpreter impractical, and processors were slow, resulting in significant performance losses due to the parsing of scripts prior to their execution. However, with the cheap memory and ultra-fast processing available to modern PCs, scripting languages have come into their own, and are almost ubiquitous (though most people don't actually know when they are running a script!) due to their suitability for web applications.

In order to use the GAMS-X scripting capabilities, you really only need to know a few Perl commands which are easily recognizable by anyone with even a passing knowledge of programming and easily understandable by those with no programming knowledge at all.

NB: Before continuing, please note that your humble programmer has noticed that Netscape Navigator 3.04 (but, mysteriously, not Netscape Communicator 4.5) tends to have problems with some sections of the code examples (i.e., the occasional word in the code examples disappears), and that it is best to use the PDF version of this document rather than the HTML version to learn the information in this section and the next if you suspect that some words are missing from the code examples.

The first two commands, use and new , will appear at the top of every GAMS-X script. Use simply informs the compiler that one of either the GAMS, GAMS-Ini, GAMS-Tools, or GAMS-CGI modules will be used. Note that GAMS-Ini is a part of GAMS and that GAMS is a part of GAMS-Tools and GAMS-CGI. Thus, anything available in the GAMS-Ini or GAMS modules is available when you use the GAMS-Tools or GAMS-CGI modules.

The new command simply informs the module that you are getting ready to do something, and that it should load the appropriate routines and environment. In technobabble, it instantiates a blessed reference to a named anonymous hash.¹⁰ You could also say that it instantiates a thingy that knows what it is.

Let's call our example script myexample.pl. Simply open a file in your favorite text editor, such as Emacs or Windows Notepad, type the following lines, and save the file with the name myexample.pl.

use GAMS::Script;
$GAMS = new GAMS::Script;

We now have a GAMS object ready to work with, though we haven't actually done anything with it yet. (More on that later ...) The GAMS object itself is the $GAMS in the code above. $GAMS is an example of a scalar, one of three data types available in Perl. A scalar can consist of a string of characters, such as ``Grog'', a number, such as 5, or a reference to another data type, such as an object (in this case the GAMS object). If you don't know what a reference is, don't worry. You won't need to know what one is in order to use it.

So to define a simple scalar such as the message ``Hello World!'' in Perl, you would type

$scalar = "Hello World!";

Note that all statements in Perl, as in GAMS, are terminated by a semicolon.

The other two data types in Perl are lists and associative arrays. A list is exactly what it sounds like, an ordered list of things, and is differentiated from a scalar by the use of an @ rather than a $. The things in the list are scalars, which in turn can be references to other lists or objects or whatever.

Thus to define a list, you would type

@list = ( "I am a string", "The next item is a number", 5);

To look at a particular item in the list, for example the first entry of the above list, use the syntax $list[·], where the · represents the index of the list starting from 0. To print The next item is a number from the above list, the print command could be used as follows:

print $list[1];

A convenient Perl construction that can be used in tandem with the print command is the << operator, which causes Perl to replace the << with all of the lines of text that follow up to a line with only the string following the << on it.

For example, the statement

print <<"EndOfHTML";
<HTML>
<BODY>

Hi there.  I am an HTML document.

Everything will be printed up to a line containing only "EndOfHTML".

</BODY>
</HTML>
EndOfHTML

With the << operator, it is easy to nest HTML documents in your Perl script.

Furthermore, a list can be looped over using a foreach statement. For example, the command

foreach $item (@list) { 

   print $item, "\n"; 

}

would print each item in the list. In the example, the foreach command causes Perl to start at the beginning of the list and put each item in the list in the scalar $item. Then the first print command prints the item ($item). The second print command uses a newline character \n to create a new line before going through the next iteration of the loop to keep all of the things being printed from bunching up on the same line. The newline character is an example of an escape character, which include tabs and backspaces, among others.

Note that loops can also be created with the standard C syntax, where the first statement in parenthesis initializes a scalar ($i=0), the second declares a condition which, when false, causes the loop will be exited ($i<100), and the third which increments or decrements the looping scalar ($i++, which, in C syntax, is the same as the statement $i=$i+1). For example:

for ($i=0;$i<100;$i++) { 

   print $i;  
   print "\n"; 

}

which would print the numbers 0 to 99.

Two important commands used with lists are sort and reverse. The sort command sorts the list alphabetically while reverse sort reverses the order of the sort command.

The third Perl data type, an associative array, is simply a collection of key-value pairs, and is differentiated from scalars and lists by means of a %.¹¹ If, for example, there are people named Joe and Mary with IDs 1 and 2, their IDs could be put into an associative array as follows:

%array = ( "Joe" => 1, "Mary" => 2 );

This statement indicates that the key Joe is to be associated with the value 1 and Mary is to be associated with the number 2.

Now to print the value associated with the name Joe, the command

print $array{"Joe"};

would print the number 1.

Notice that curly brackets, rather than the square brackets of lists, are used to index items in associative arrays.

Three important commands used with associative arrays are keys, values, and exists. The keys command returns a list of all of the keys in an associative array.

Thus the code

@keys = keys %array;
foreach $key (@keys) {
   print "The key is $key\n";
   print "The value is $array{$key}\n";
}

will print all of the keys in the array %array. Note in this example the ability of Perl to nest variables in strings. Here, the value of $array{$key} is put into the string before the string is printed. This is called string interpolation. In Perl, the primary difference between using single and double quotes is string interpolation: When a string is defined using double quotes, any variables contained within it are interpolated, whereas when a string is defined using single quotes, variables are not interpolated. Thus the commands

$string = "World";
print "Hello $string!";

would print Hello World! whereas the commands

$string = "World";
print 'Hello $string!';

would print Hello $string!.

Also note that to print the names in alphabetical order, the command

@keys = keys %array;

could be replaced with

@keys = sort keys %array;

The values command is much like the keys command, only a list of the values of an array are returned.

The exists command seems unimportant, but is very useful when working with GAMS-X scripts. Perl dynamically creates variables as they are used; that is, just typing $var creates the variable $var. Similarly, if the key to an associative array doesn't exists, and you want to see if it does with a statement like

if (not $array{'mykey'}) { print "I can't find mykey!" }

then you have just defeated the purpose of your if statement, as the $array{'mykey'} dynamically created a variable called %array if one didn't already exist and then created a key called mykey in %array with a blank value. Instead, you should use

if (not exists $array{'mykey'}) { print "I can't find mykey!" }

This is useful in GAMS-X scripting, for example, if you want to check whether a user exists. Then the command would be

if (not exists $GAMS->Users->{'ID'}->{'Grog'}) { 
   print "Grog does not have an account on this site!"
}

If, instead, you had used the statement

if (not $GAMS->Users->{'ID'}->{'Grog'}) { 
   print "Grog does not have an account on this site!"
}

then you have just created a blank user account for Grog if one did not already exist.

Finally, we will discuss pointers. Pointers are simply scalars that point at another type of variable. There are many technical advantages to using pointers which are beyond the scope of this little tutorial; thus, only their use will be described.

Pointers basically point at a memory address, which may be the start of a list or an associative array or object or whatever. In fact, in the example above, the statement $GAMS = new GAMS, $GAMS is a pointer, or a scalar that points at a GAMS object. In order to use them, you need to indicate what you want the pointer to point at. So, for example, if you have a pointer $pointer that points at a list , to look at the third element of using the variable, you would type

print $list[2];

Recall that the first element of a list is 0, a convention that follows from the C programming language.

On the other hand, if you want to look at the third element of using the pointer variable $pointer, you need to show that you are pointing at something with an ->:

print $pointer->[2]

Similarly, if $pointer points at an associative array, to look at the value of the array corresponding to the key Grog, you would use the following syntax:

print $pointer->{"Grog"};

To create a pointer to a list, use square brackets instead of parentheses, and to create a pointer to an associative array, use curly braces instead of parentheses. For example:

$list_pointer = [ "I", "am", "a", "pointer", "to", "a", "list" ];

and

$associative_array_pointer = { "I am a key" => "I am a value" };

You will notice throughout the documentation on GAMS-X scripting that pointers are used. Thus, when you use the command

print $GAMS->Cases->{'HIGHB'}->{Output}->{'UTILITY.L'}

you are actually printing the value of the UTILITY.L key of the Output pointer, which is the value of the Output key of the 'HIGHB' pointer, which the the value of the 'HIGHB' key of the pointer to an array returned by the Cases method. It almost makes my head spin, but I hope you get the idea.

One note of caution to those who have not used pointers before: Because they point at a memory address rather than an actual chunk of data, you can inadvertantly modify something that you did not intend to if you are not careful. For example,

@list1 = ( 1, 2 );
@list2 = @list1;
$list2[0] = "Hello World!";
print $list1[0];

simply prints the number 1, whereas the script

@list1 = ( 1, 2 );
$pointer = \@list1;
$pointer->[0] = "Hello World!";
print $list1[0];

prints "Hello World!".¹² Thus the following caveat: If you are not comfortable working with pointers, don't make any changes to variables that are pointers or variables set equal to pointers! You will not need to worry about this when working with GAMS-X scripts unless you are doing something out of the ordinary. If you just rely on the GAMS-X methods to make changes in cases and casebooks, you should have no problems.

One last note on pointers: You will find it extremely useful to be able to extract the lists and associative arrays which GAMS-X methods return. To do this, simply surround the method name with curly braces { and } and put an @ (for a list) or % (for an associative array) in front. For example,

@list  = @{$GAMS->UserState('Grog','Ramsey')->{Case}};
%array = %{$GAMS->Cases('Grog','Ramsey')};

So far, the use and new commands have been described, along with three Perl data types and the for, print, sort, reverse, keys, and values commands have been covered. Furthermore, pointers to lists and associative arrays have been discussed. This finishes off our brief tour of ``everything you need to know about Perl to use GAMS-X.''

We are now ready to move on to a few quick examples of GAMS-X scripts. These snippets of code are just to whet your appetite. A fully developed example script, included in the scripts subdirectory of the basic GAMS-X installation, is described in the next section.

All of the actions performed by these example scripts are accomplished by the use of is called a method, which is simply something that an object, such as the GAMS or GAMS-CGI object, does. To invoke a method, simply follow the name of the object (e.g., $GAMS in the example above) with an arrow -> and the name of the method. You may want to at some point peruse the list of all of the GAMS methods given in appendix .

Now let's say you want to know what the output UTILITY.L is for a case called HIGHB corresponding to a high capital value share. You know that the case HIGHB is contained in your user Grog's account. Then all that is required is a simple and intuitive statement using the Cases method. The complete script would be

use GAMS::Script;
$GAMS = new GAMS::Script;
print "The utility for the user Grog's case HIGHB in the model Ramsey is:  ";
print $GAMS->Cases("Grog","Ramsey")->{"HIGHB"}->{Output}->{"UTILITY.L"} 

Once you have saved the file as myexample.pl, you can type

myexample.pl

from the command line to see the results. If you are using Windows 95/98, you will have to type

perl myexample.pl

if you are at a DOS prompt to see the results.

That's all there is to it! Now let's do a couple of quick examples that make use of the real power of GAMS-X scripting.

These examples are just for show. A full-blown example, including just about all of the basics you need to know to work with models, will be presented in the next section.

Suppose that now you want to generate 100 cases in GAMS-X. Doing so through either of the visual interfaces, GAMS-Tk or GAMS-CGI, would take a prohibitive amount of time. But with GAMS-X, there is no fussing with batch files or using put statements to create data files for graphing or presentations. Simply use the Set and NewCase methods:

use GAMS::Script;

$GAMS = new GAMS::Script;

$GAMS->Set( -User => "Grog", -Model => "Ramsey" );

for ($i=0;$i<100;$i++) {

  $GAMS->Set( 
    -Case => "Case $i",
    -CaseInputs => { "BET" => ( 0.9 + $i / 7500) }
  );
  $GAMS->NewCase;

}

Now the cases have been created in GAMS-X.¹³

Suppose now that you now wanted to plot consumption, given by the GAMS parameter UTILITY.L, over all 100 cases in groups of three. You could simply append the following lines to the above script:

for ($i=0;$i<97;$i++) {

   $File  = "Plot$i.gif";
   $User  = "Grog";
   $Model = "Ramsey";
   $Cases = ["Case $i","Case ".$i+1,"Case ".$i+2]; 
   $Plot  = "KK.M";
   $PlotOptions = { 
      "type" => "bars", 
      "height" => 400,
      "width"  => 600
   };
   $GAMS->MultiPlot($File,$User,$Model,$Cases,$Plot,$PlotOptions);

}

You will notice the dot operator . in the above example (e.g., "Case ".$i+2). This is simply the Perl concatenation operator, and joins two strings as one.

As will be discussed in chapter , the scripting capabilities of GAMS-X also provide administrators with almost total control over their online modeling environment and web programmers the ability to completely customize an online modeling environment. For example, if a webmaster wants to restrict access to the model Ramsey to the user Grog, the GAMS-CGI script gams-cgi.pl could be modified with the following snippet of code:

if ($GAMS->Model eq 'Ramsey') {
   unless ($GAMS->User eq 'Grog') {
      $GAMS->Gripe("Access is denied.");
   }
}

Keep in mind that the information on Perl presented here only scratches the tippy tip of the tip of the iceburg that is Perl. Once your model has been put into GAMS-X, you have all the considerable power of Perl at your fingertips, from the mathematical functions of the PDL (Perl Data Language) module to the graphics abilities of JPL (Java Perl), a module which allows for Perl to be nested in Java, to Windows object linking and embedding and COM objects through the Win32::OLE and PerlCOM packages, to the email and web facilities abilities of Perl through the Net::SMTP, Net::FTP, and LWP modules.

For more information, I recommend that you visit the Perl website http://www.perl.com , and, if you are a Windows user, the ActiveState website http://www.activestate.com , and check out any of the Perl books available in bookstores. For those who are not already proficient programmers, I recommend []. [] is also an excellent reference. For experienced programmers, [] is a excellent and comprehensive, albeit technically sophisticated, overview of the Perl programming language.

5.4  A Brief GAMS-X Scripting Tutorial

The purpose of this section is to lead you through a small GAMS-X script which will perform a number of operations that you will find useful when using GAMS-X, including creating a new user, installing a model, creating a new casebook for the model, creating some new cases for the model, solving the cases, sorting the cases, putting the sorted cases in the casebook, saving a GAMS-X data file, creating some customized plots for your model, and exiting GAMS-X. It sounds like quite alot of work, but as you'll see, it really is not.

In the course of the script, all of the cases and casebooks that are created when the Ramsey model, included with the default GAMS-X installation, is installed through GAMS-Tk, will be generated.

These activities will familiarize you with the most important GAMS-X methods, though there are many, many others at your disposal.

You should read through the example in full, then go back and try it out if you want. If you would like to see the full text of the example, see appendix .

For a full listing of the GAMS-X data structures, see appendix . There are also many examples in this appendix that you might find useful.

For a full listing of available GAMS-X methods, see appendices through

Before getting started, if you have a GAMS-Tk window open, you should be sure to pause GAMS-Tk using the Tools.Site.Pause GAMS-Tk menu option before running any GAMS-X scripts. For more information on pausing GAMS-Tk, see chapter 4.

5.4.1  Getting Started

We first need to inform Perl that we are working with the GAMS methods. Thus, start your script with two lines you will come to know very well as you work more with GAMS-X:

use GAMS::Script;
$GAMS = new GAMS::Script;

Now, as the GAMS-Tools module inherits the GAMS-Ini and GAMS objects, you have all of the GAMS-Ini, GAMS, and GAMS-Tools methods available at your disposal.

5.4.2  Creating a New User

The first thing you will want to do is create a new user. Since the GAMS-Tk and GAMS-CGI visual environments are built around user accounts, you need to have created a user account to be able to view your model using the GAMS-X visual tools.

You can use the AddUser method to create a new user, which takes as arguments the user's name, the user's password, a password confirmation (just to make sure!), the user's affiliation, the user's email address, and the user's home IP (used by GAMS-CGI).

So to create our user, we can use the GAMS Set method in conjunction with the AddUser method as follows to create a user named Grog by adding the following lines to the script:

$GAMS->Set( 

     -User => "Grog",
     -Password => "grog!",
     -PasswordConfirmation => "grog!",
     -Affiliation => "University of Grog",
     -Email => 'grog@spot',
     -UserHome => "Local Host"

);

$GAMS->AddUser;

Note the use of single quotes in defining the email address. This is because lists are defined by the @ symbol in Perl. If double-quotes are used, Perl would try to find a list called @spot and interpolate it into the email string. With single quotes, no interpolation is performed.

If you need to have an @ symbol in a double-quoted string, you can escape the @ character by using the forward-slash like so: "grog\@spot".

Equivalently, we could have used the lines

$GAMS->AddUser( 

     "Grog",
     "grog!",
     "grog!",
     "University of Grog",
     'grog@spot',
     "Local Host"

);

Note that the UserHome parameter is optional.

5.4.3  Installing a Model

Now that you have a user account to work in, you will want to install a model. For this example, the Ramsey model provided with the default GAMS-X installation will be used. If you have already installed the Ramsey model, you can uninstall it in GAMS-Tk by using the Tools.Model.Uninstall menu option, or by reading the next section on uninstalling models with GAMS-X scripts.

The GAMS-Tools method Install is used to install a model, and takes as arguments the model name, the description, the name of the GAMS file to associate with the model, the name of an HTML file to associate with the model documentation, and the name of a GAMS-X data file. Note that the last two arguments are optional. If the documentation argument is not included, a simple HTML file will be created informing users that no documentation is associated with the model, and if the GAMS-X data file is not included, the default case (that is, the case which takes as its inputs the default input values) will simply be generated.

So now to install our model (assuming that the file Ramsey.gms is located in the C:\gams-x\working directory, which is the case if GAMS-X is installed in the C:\gams-x directory on your computer), include the following lines with the script:

$GAMS->Install(

   'Ramsey',
   'Ramsey Model of Optimal Economic Growth',
   'C:\gams-x\working\Ramsey\Ramsey.gms'

);

You have now installed the model Ramsey.

Uninstalling a Model

If now at some point you need to uninstall the Ramsey model, simply include the model name as an argument to the Uninstall method:

$GAMS->Uninstall( 'Ramsey' );

You can also remove the user account for the user Grog with the Kill method:

$GAMS->Kill( 'Grog' );

There is a nice trick you can use to do the same thing from the command line: The M flag causes Perl to automatically load the module whose name follows the M, and the e flag causes Perl to automatically execute the command that follows the e.

Thus you could also uninstall the Ramsey model by typing, from the command line,

perl -MGAMS::Tools -e "$GAMS=new GAMS::Tools;$GAMS->Uninstall('Ramsey');"

Similarly, you could remove the user Grog's account by typing from the command line

perl -MGAMS::Tools -e "$GAMS=new GAMS::Tools;$GAMS->Kill('Grog');"

5.4.4  Creating a New Casebook for the Model

We now want to create a couple of casebooks for the Ramsey model. To create new casebooks, the GAMS NewCasebook method can be used.

The NewCasebook method takes as arguments a user name, a model name, the name of the casebook, and, optionally, a description of the casebook.

So to create two new casebooks named STUDY1 and STUDY2, we can add the following lines to our little script:

$GAMS->Set(
     -User => "Grog",
     -Model => "Ramsey",
     -Casebook => "STUDY1",
     -Description => "Comparing a high capital value share and high labor growth rate" 
);
$GAMS->NewCasebook;

$GAMS->Set(
     -Casebook => "STUDY2",
     -Description => "Comparing a high labor growth rate and low discount factor" 
);
$GAMS->NewCasebook;

Note that the second Set method call does not include the User and Model arguments, as those parameters have already been set by the first call.

5.4.5  Creating Some New Cases for the Model

Now we want to create some new cases for the model. In order to create a new case, we have to define a set of inputs.

Normally we would have to set a user and model for which a case is defined, but we already did that in section above. Note that only the input that differs from the default is set. All of the inputs not explicitly defined are set to their defaults.

print "Creating case HIGHB . . .\n";
$GAMS->Set(
     -Case => "HIGHB",
     -CaseInputs => { "B" => 0.30 }
);
$GAMS->NewCase;

print "Creating case HIGHG . . .\n";
$GAMS->Set(
     -Case => "HIGHG",
     -CaseInputs => { "G" => 0.06 }
);
$GAMS->NewCase;

print "Creating case LOWBET . . .\n";
$GAMS->Set(
     -Case => "LOWBET",
     -CaseInputs => { "BET" => 0.90 }
);
$GAMS->NewCase;

NB: While GAMS syntax is case-insensitive, GAMS-X syntax, consistent with that of Perl, is not. Therefore if you create a GAMS-X input with a GAMS statement like

$libinclude X INPUT BET 0.95 "Discount Factor" MAX 0.975 MIN 0.95

you can refer to the input later in your GAMS file with a statement like

SCALARS  BET    DISCOUNT FACTOR           /%bet%/

whereas in GAMS-X, you must use the capitalization used in declaring the input in GAMS (i.e., BET rather than bet). For example,

print $GAMS->Inputs('Grog','Ramsey')->{'bet'}->{Default};

would print nothing whereas

print $GAMS->Inputs('Grog','Ramsey')->{'BET'}->{Default};

would print the default value of the input BET (i.e., 0.95).

If you want to define multiple inputs, simply separate them by a comma. For example,

$GAMS->Set(
     -Case => "HIGHB&LOWBET",
     -CaseInputs => {  "G" => 0.6, "BET" => 0.90 }
);

Notice the use of curly braces following the CaseInputs option. While reading the documentation on GAMS-X scripting, pay close attention to whether parentheses, curly braces, or square brackets are used. They each carry a quite different meaning.

5.4.6  Solving the Cases

Now that the cases have been created, we need to submit them to GAMS by calling the Solver method. The Solver method does a couple of things: First, it looks for any cases that have not been submitted to GAMS and submits them to GAMS. Second, it updates that GAMS-X database to reflect the solutions of the cases, including any plots that have been defined.

To invoke the Solver method, we need only include the line

$GAMS->Solver;

5.4.7  Putting the Cases in the Casebooks

Now that we have a batch of freshly solved cases to work with, we need to bundle them somehow for viewing. To be able to see cases in GAMS-Tk and GAMS-CGI, they need to be included in casebooks.

$GAMS->Set(
     -Case => "HIGHB",
     -Casebook => "STUDY1"
);
$GAMS->Book;

$GAMS->Set(
     -Case => "HIGHB"
);
$GAMS->Book;

The Book method does not generate the casebook plots, so it is important if you have plots to be seen, that when you finish putting cases into a casebook, you create new plots for the casebook with the CasebookPlot method

$GAMS->CasebookPlot;

Now let's put some cases into the casebook STUDY2 ...

$GAMS->Set(
     -Case => "HIGHG",
     -Casebook => "STUDY2"
);
$GAMS->Book;
$GAMS->Set(
     -Case => "LOWBET"
);
$GAMS->Book;
$GAMS->CasebookPlot;

Now if you were to run the little script we have so far, then start GAMS-Tk (or open a web browser and log in to your GAMS-CGI site), you would see the user Grog with all of the Ramsey cases and casebooks installed as they have been defined. However, to finish with our example, we will have our script do some things that really show off the abilities of GAMS-X scripting.

5.4.8  Sorting the Cases

Suppose that now you want to sort the cases. With three cases, this is not such an important task, but with a hundred or a thousand cases, this can be quite important.

To accomplish this task, we use the Perl grep function in combination with the Perl $_ variable and Perl's pattern matching facility. These are fairly advanced concepts, and so won't be discussed here except via the example that follows.

Suppose that you want to look for all of the cases that were submitted to GAMS and did not result in a GAMS error (all of the cases should meet this criteria if your GAMS solvers are correctly installed), have a capital value share greater than 0.25 (the case HIGHB meets this criteria), an output of intertemporal utility greater than 1 (all of the cases will meet this criteria) and includes the letter H in the case name in either upper or lower case (just for kicks!). This can be done with just one statement:

@MySortedCases = 

   grep $_->{'Status'} eq 'Solved', 
   grep $_->{'Input'}->{'B'} > 0.25,
   grep $_->{'Output'}->{'UTILITY.L'} > 1,
   grep /H/i, @{$GAMS->UserState->{'Case'}};

Just to confirm that we have got what we are looking for, we should print out the case names:

if (@MySortedCases) {
# . . . that is, if there are any cases in the @MySortedCases list
  foreach $Case (@MySortedCases) {
    print "The case $Case->{'Name'} meets my sorting criteria.\n";
  }
} else {
  print "No cases meet my sorting criteria!\n";
}

Here the UserState->{'Case'} reference returns a pointer to the list of cases for the current user and model. The surrounding @{·} turns the pointer into a list.¹⁴ Then the last grep statement extracts all of the cases that have an H in their name, and hands that list (in this case, HIGHB and HIGHG) off to the second grep statement. The second grep statement finds all of the cases in that list that have output of intertemporal utility greater than 1 and hands that list (still including HIGHB and HIGHG, since they both meet the utility criteria) off to the first grep, which finds all of the cases with a capital value share greater than 0.25. The print statement should print the statement

The case HIGHB meets my sorting criteria.

5.4.9  Saving a GAMS-X Data File

Now suppose that you want to bundle up your cases and casebooks with your model and send them off to your friend Wonk in Reykjavik, Iceland. You can just save the current case and casebook configuration as a GAMS-X data file, then forward that with your GAMS model, and he can install and play with it on his own GAMS-X installation.

To do so, simply invoke the WriteData method, included with the GAMS-Tools module, with a filename as an argument.

The WriteData method also takes a user name and model name as its second and third argument, but since that has already been set with the Set method above, they can be omitted.

Here's the code:

$MyDataFile = 'C:\temp\Ramsey.gmx';
print "Writing GAMS-X data file to $MyDataFile . . .\n";
$GAMS->WriteData( $MyDataFile );

You will note that single-quotes were used rather than double-quotes in defining the string containing the file name. That is because Perl uses the DOS directory divider (the forward-slash) as an escape character when double-quotes are used.

If you need to include the forward-slash in a double-quoted string (if you are using string interpolation, for instance), you can do something like this:

$MyDataFile = "C:\\temp\\Ramsey.gmx";

I prefer to use the single-quotes for readablity.

5.4.10  Creating Some Customized Plots for Your Model

Now you notice that the plots provided by default are not exactly what you want. Instead, you would like to plot many series across a single case.¹⁵ To do so, you can use the MultiPlot method.

First, you will want to define a pointer to a list of the plot series that you would like to see. You can do that with the statement

$Plots = [ "C.L", "I.L", "CC.M" ];

which creates a list of plot series whose names correspond to the ``Consumption (trillion rupees per year)'', ``Investment (trillion rupees per year)'', and ``Present value of consumption'' plot series.

Next, if you want any of the plot options set to anything other than their defaults, you should set the plot options. The plot options are defined by a pointer to an associative array in the same way the the CaseInputs option was defined above.

$PlotOptions = { 
   "height" => 400, 
   "width" => 500, 
   "type" => "bars" 
};

Now you can create the plot with the following statements:

$GIFFile = 'C:\temp\MyPlots.gif';
print "Generating customized plot in file $GIFFile . . .\n";
$GAMS->MultiPlot(
     $GIFFile,
     "Grog",
     "Ramsey",
     "HIGHB",
     $Plots,
     $PlotOptions
);

5.4.11  Printing Formatted Output

Perl, which is reputed to stand for Pathologically Eclectic Rubbish Lister, was originally conceived as the Practical Extraction and Report Language. This means that you can easily generate nicely formatted output through the C-style printf commands as well as the Perl format command.

An example might go something like:

print <<"eop";

Here is a listing of the cases I have just generated as well as the
value of the output UTILITY.L, all nicely formatted for my viewing
pleasure: 

Case            UTILITY.L CONSUM(1990) CONSUM(2050) KK(1990) KK(2050)
----            --------- ------------ ------------ -------- --------
eop

format MYFORMAT = 
@|||||||||||||| @###.#### @###.####    @###.####    @##.#### @##.####
$Name,          $UTILITY, $CONSUM1990, $CONSUM2050, $KK1990, $KK2050
.

$~ = MYFORMAT;

for $Case (@{$GAMS->UserState("Grog","Ramsey")->{'Case'}}) {
   $Name = $Case->{'Name'};
   $UTILITY = $Case->{'Output'}->{'UTILITY.L'};
   $CONSUM1990   = $Case->{'Output'}->{'CONSUM(1990)'};
   $CONSUM2050   = $Case->{'Output'}->{'CONSUM(2050)'};
   $KK1990       = $Case->{'Plot'}->{'KK.L'}->[0];
   $KK2050       = $Case->{'Plot'}->{'KK.L'}->[60];
   write;
}

This example uses some fairly esoteric Perl commands such as format and $~. For more information on formatting output in Perl, please refer to your Perl documentation.

5.4.12  Exiting GAMS-X

As a last step, we need to invoke the Quit method. This method makes sure that all of the new information generated by the script is saved. As a rule, you should end any GAMS-X scripts that make changes in a user or model state with the Quit method.

To finish the script, add the following lines:

print "Quitting . . .\n";
$GAMS->Quit;

We now have a simple script, no more than a couple pages long including print statements, that creates a new user account, installs a model, creates some cases and solves them, creates some casebooks, sorts the cases and puts them in the casebooks, and generates a customized plot. Not too bad for a few minutes of typing!

The full text of the script is given in appendix and is included in the scripts subdirectory of the GAMS-X distribution. After running the example, you might enjoy running GAMS-Tk and viewing the results.

5.5  Send Me Your Code!

As this example demonstrates, GAMS-X scripting gives those who are willing to learn just a little bit of programming syntax the power to easily create personalize GAMS-X reports and utilities. In fact, Tom Rutherford both learned the GAMS-X scripting system and created the case.bat and book.bat utilities included in the scripts directory of the GAMS-X distribution in less than an hour!

If you find the GAMS-X scripting system useful, and create scripts that you think would be helpful to other GAMS-X users, please forward them to me at .

Chapter 6
The GAMS-X Administrator's Guide

This chapter will discuss GAMS-X administration from two perspectives: Administration using the GAMS-X scripting language and administration using the GAMS-Tk visual interface. The visual interface is much more convenient to use for mundane administrative tasks, but the scripting capabilities provide a much wider range of functionality to the administrator.

6.1  Your GAMS-X Site Configuration

The GAMS-X site configuration includes all of the configuration variables defined in the GAMS-X initialization file (see section ), and controls such widely diverse aspects of the GAMS-X environment as the directory structure, the appearance of GAMS-Tk, the appearance of GAMS-CGI, and the location of the GAMS-X help files.

To retrieve and/or modify configuration variables in GAMS-Tk, use the Tools.Site.Configure menu option. A window will appear with all of your configuration variables (see figure ). Simply click on the name of a configuration variable if you want to change its value.

To retrieve them in the form of an associative array in GAMS-X script, use the Configuration method. For example:

print "All of the GAMS-X configuration variables are as follows:\n\n"; 
foreach $key (sort keys %{$GAMS->Configuration}) {
   print "$key:  ";
   print $GAMS->Configuration->{$key};
   print "\n";
}

To change the value of a configuration (also changing its value in the GAMS-X initialization file), use the Configure method. For example:

$GAMS->Configure(
   -Logo => "mylogo.gif",
   -LogoHeight => 100,
   -LogoWidth => 150
);

6.2  Administering Models

6.2.1  Obtaining Model Information

Two basic model summaries for models installed on a GAMS-X site are available in GAMS-Tk: The model index and the model summary.

To view the model index (figure ), select the View.Model Index menu option. This will present a list of the installed models together with their descriptions.

To view the model summary (see figure ), select the Tools.Model.Summary menu option.

A list of the installed models together with the number of solved cases, the number of cases which have generated GAMS errors, and the number of cases which have not yet been submitted to GAMS will be provided.

From the model summary, you may click on the name of any of the models to be provided with more detail regarding the model cases (see figure ).

When viewing the resulting window with the list of model cases, you may click on any of the case tags to view more detail on that particular case or edit the case (see figure ).

More detailed model information can be obtained through GAMS-X scripting with the Models and ModelState methods.

The Models method returns a pointer to an associative array with the keys ID, Installed, Description, File, Base, Root, GXFile, and Documentation.

The ID key provides the internal GAMS-X ID number of the model.

The Installed key returns the time and date of the model installation.

The Description key returns the description of the model.

The File key returns the full filename of the GAMS file associated with the model. The Base and Root keys return the file name (without the full path) of the File key, and the Root key returns the path (without the file name) of the File key.

The GXFile key returns the full filename of the GAMS-X datafile associated with the model, whereas the GXBase key returns only the filename of the GXFile key.

The Documentation key returns the file name of the HTML file associated with the model.

Example:

print "Here is the information associated with the model Ramsey:\n\n"; 
print "The GAMS-X model ID:  ", $GAMS->Models->{ID}->{"Ramsey"}, "\n";
print "The installation date and time:  ", $GAMS->Models->{Installed}->{"Ramsey"}, "\n";
print "The model description:  ", $GAMS->Models->{Description}->{"Ramsey"}, "\n";
print "The GAMS file associated with the model:  ", $GAMS->Models->{File}->{"Ramsey"}, "\n";

Thus, to obtain a list of the models currently installed on the site, you may simply check which models have been issued an ID:

print "The following models are installed:\n\n";
for $Model (sort keys %{$GAMS->Models->{ID}}) {
   print $Model, "\n";
}

ModelState method takes a model name as an argument (provided a model has not been set with the Set method) and returns a reference to a ModelState data structure containing information on all of the cases, including those that have been submitted to GAMS and those pending submission, associated with the model. This data structure is described in full detail in section , and so will not be described here.

6.2.2  Installing Models

To install a model from GAMS-Tk, use the Tools.Model.Install menu option. You will be queried for model installation information by the model installation window (see ).

To install a model from a GAMS-X script, use the Install method, which takes as arguments the model name, a description, the file name (with a full absolute path) of the GAMS file, and, optionally, the file name (with full absolute path) of the model documentation and the file name (with full absolute path) of a GAMS-X data file to associate with the model. Example:

$GAMS->Install(
   'Ramsey',
   'Ramsey Model of Optimal Economic Growth',
   'C:\gams-x\working\Ramsey\Ramsey.gms',
   'C:\gams-x\working\Ramsey\X.gmx'
   'C:\gams-x\working\Ramsey\Ramsey.html'
);

6.2.3  Uninstalling Models

To uninstall a model from GAMS-Tk, select the Tools.Model.Uninstall menu option. For help, click on the Help button at the bottom of the model uninstall window (see figure ).

To uninstall a model using a GAMS-X script, use the Uninstall method with the model name as the argument. For example:

$GAMS->Uninstall( 'Ramsey' );

6.2.4  The GAMS-X Data File

The GAMS-X data file is the means by which models can be easily transferred between GAMS-X sites. The GAMS-X data file preserves the configuration of casebooks and cases for a particular user, allowing the same casebooks and cases to be installed at another site.

Thus, if you send someone who is running GAMS-X your GAMS code and a GAMS-X data file, they can install your model with the precise configuration of casebooks and cases that are currently associated with a user.

Note that when you install a model with a GAMS-X data file, GAMS-X resolves all of the model cases. Thus, a case might solve normally on the computer that generated the GAMS-X data file, but generate a GAMS error on your computer if, for example, you are supporting a different set of GAMS solvers.

To generate a GAMS-X data file in GAMS-Tk, select the File.Save.Model As.GAMS-X Data File menu option. The configuration of cases and casebooks affiliated with the user and model that is currently loaded will be saved.

To generate a GAMS-X data file from a GAMS-X script, use the GAMS-Tools method WriteData using a file name, user name, and model name as arguments. For example:

$GAMS->WriteData( 'C:\gams-x\temp\Ramsey.gmx', 'Grog', 'Ramsey' );

or, equivalently,

$GAMS->Set( -User => 'Grog', -Model => 'Ramsey' );
$GAMS->WriteData( 'C:\gams-x\temp\Ramsey.gmx' );

For example, if you are running GAMS-Tk, and you select File.Save.Model As.GAMS-X Data File, then send your model code and the GAMS-X data file to your friend in Copenhagen, when they install your model with the GAMS-X data file, they will find themselves looking at the same assortment of cases and casebooks that you were when you saved the file. Think of it as taking a snapshot of the user's account for that model.

6.3  Administering Users

6.3.1  Obtaining User Information

In GAMS-Tk, user information can be obtained through the Tools.User.Summary menu option (see figure ). If need more user information, you can click on the user name in the user summary, and a window will be opened containing all of the user's profile information, including the user's ID, email address, affiliation, etc.

A list of users can similarly be obtained as the keys to the ID key of the reference to the associative array returned by the Users method, similarly to obtaining a list of models.

print "The following users have accounts on this site:\n\n";
for $User (sort keys %{$GAMS->Users->{ID}}) {
   print $User, "\n";
}

Information on an individual user can be obtained through the UserProfile method, which returns a reference to an associative array containing the keys Name, Affiliation, Created, Email, Home, ID, LastLogin, and Password.

The Name key returns the user's name.

The Affiliation key returns the user's affiliation, as specified by the user when the user's account was created.

The Created key returns the date and time of the creation of the user's account.

The Email key returns the user's email address.

The Home key returns the user's remote host (typically the user's IP address) at the time that the user account was created. If the user account was created through GAMS-Tk or a GAMS-X script, Home returns ``Local Host.''

The ID key returns the internal user ID used by GAMS-X.

The LastLogin key returns the last login host of the user, typically the user's IP address.

The Password key returns the encrypted password of the user. Note that the actual (i.e., non-encrypted) password of the user is not stored internally, and is thus not accessible by the GAMS-X site owner.

6.3.2  Creating a User

User accounts can be created through three sources: Remotely through GAMS-CGI or locally through GAMS-Tk or a GAMS-X script.

Creating a user through GAMS-CGI is discussed in section .

To create a user through GAMS-Tk, use the Tools.User.Create menu option (see figure ).

To create a user within a GAMS-X script, use the AddUser method with the user's name, password, password confirmation, affiliation, and email address as arguments. Example:

$GAMS->Set( 
     -User => "Grog",
     -Password => "grog!",
     -PasswordConfirmation => "grog!",
     -Affiliation => "University of Grog",
     -Email => 'grog@spot',
     -UserHome => "Local Host"
);
$GAMS->AddUser;

or, equivalently,

$GAMS->AddUser( 
     "Grog",
     "grog!",
     "grog!",
     "University of Grog",
     'grog@spot',
     "Local Host"
);

Note that the user's email address should be enclosed in single quotes, or, if it is enclosed in double-quotes, should have the @ escaped.

6.3.3  Killing a User

User accounts can be removed from the GAMS-X system through three sources: Remotely through GAMS-CGI or locally through GAMS-Tk or a GAMS-X script.

A user can eliminate their own user account through the GAMS-CGI Edit Account Information button on the GAMS-CGI login.

In GAMS-Tk, user accounts can be eliminated through the Tools.User.Kill menu option (see figure ).

In a GAMS-X script, a user account can be killed through the Kill method, taking the user name as an argument. Example:

$GAMS->Kill( 'Grog' );

or, equivalently,

$GAMS->Set( -User => 'Grog' );
$GAMS->Kill;

6.3.4  Editing a User

A user's profile information can be edited through three sources: Remotely through GAMS-CGI or locally through GAMS-Tk or a GAMS-X script.

In GAMS-CGI, a user can edit their account through the Edit Account Information button on the GAMS-CGI login page.

To edit a user through GAMS-Tk, the Tools.User.Edit menu option (see figure ) may be selected. A list of the users will be presented from which a user may be selected.

Figure

Upon selecting a user through the User Editing window, you will be provided with a window that allows you to change all of the user's profile information, including the user's password (see figure ).

To change a user's profile information through a GAMS-X script, use the UserProfile option in conjunction with the Set method. The UserProfile option should point at a reference to an associative array whose keys are users' names and whose values are references to associative arrays whose keys are user profile keys and whose values are the values you are setting.

For example:

$GAMS->Set( -UserProfile => { 
                               'Grog' => { 'Password' => 'grog!' },
                               'Wonk' => { 'Email'    => 'wonk@spot'}
                            }
);

6.4  Some Important GAMS-X Files

6.4.1  The GAMS-X Initialization File

GAMS-X configuration variables are defined in a file called gams-x.ini located in the directory listed by the environment variables HOME in Unix and WINDIR in Windows. To check what your WINDIR is in Windows, you can type

echo %WINDIR%

at a DOS prompt.

The file consists of name=value pairs and comment lines, the latter of which start with a pound sign (#). For example, a gams-x.ini file may look something like the following:

#   The GAMS-X Initialization File
  
#   The directory structure

Shebang=#!C:/Perl/bin/perl.exe
GXHome=http://economics.colorado.edu/gams-x
GXRoot=c:/gams-x
GXDir=c:/zbs/html/gams-x
CGIRoot=c:/zbs/cgi
CGILoc=/cgi

. . . etc . . .

If you would like a value to be available to the GAMS-X system, you can edit this file to add a name=value pair.

Note that to change the values of items in the configuration file, you can use the Tools.Site.Configuration menu option in GAMS-Tk.

See also the Configure and Configuration methods.

6.4.2  The GAMS-X Log File

Included in the GAMS-X root directory is a log file called gams-x.log that contains a log of all of the various comings and goings of GAMS-X users. If there is a great deal of activity on the system over a long period of time, the file can become quite large. Thus, on a particularly busy site, the GAMS-X administrator may want to manually edit the file every few months to eliminate old entries.

Chapter 7
The GAMS-CGI User's Guide

7.1  Overview

GAMS-CGI (General Algebraic Modeling System Common Gateway Interface) is a user interface designed to allow users operate remote models over the web by specifying model inputs and to present users with a compact and convenient presentation of model results.

Users should note that the GAMS-CGI environment is fully customizable, so while the figures included in this user's guide represent the default GAMS-CGI environment, depending on the creative flair of the webmaster, users may be presented with pages that look more or less like the ones seen here.

Central to understanding the GAMS-CGI system are the concepts of casebook and case. When a user selects a set of inputs to a GAMS model, she is creating a case. Casebooks are simply sets of cases. Thus, a user may create as many cases as she likes, which represent solutions of a model with various sets of inputs, and bundle them in casebooks to represent different sets of scenarios as she sees fit.

The central pages of the GAMS-CGI environment are as follows:

• Login page, from which a user accesses her account, edits her profile information, or creates a new account
• The Model Index page, which a user uses to access any of the various models installed on the site
• The Casebook Index page, from which users access casebooks that have been created for a model
• The Casebook page, which displays case information, including inputs, outputs, and plots, allows users to create new cases and view the GAMS listing files associated with the various cases.

If a user is interested in viewing the documentation associated with a model or viewing the GAMS code associated with a model, this can be accomplished through the Casebook Index or Casebook page.

7.2  Logging In

When a user first encounters the GAMS-CGI environment, she will be presented with the GAMS-CGI login page (figure ). If the user has already established an account, then the user fills in her user name and password and is taken to an index of the installed models. If not, the user may provide a user name and password and click on the new user button, in which case she will be brought to the New Account Creation page (figure ).

The login page is also the page which allows a user to either edit his or her account profile (the information such as email address associated with a user) or remove her account from the GAMS-X system. This can be accomplished by entering a user name and password and clicking on the Edit Account Information button (see figure ).

Note that users may view the documentation associated with any model on the site from the login page by clicking on any of the buttons displaying a model name.