OxEdit+GAMS : Another GAMS IDE

Philip A. Viton

November 9, 2001

Contents

1  Introduction
2  Updates
3  Get the files
4  Install the Components
5  Configure the System
     5.1  Configure OxEdit
     5.2  Configure the batch files
     5.3  Configure GAMS
6  Testing OxEdit+GAMS
7  Using the System
8  Extensions
     8.1  Comments —gamscom
     8.2  Postprocessing the .lst file —gamsrd.exe
     8.3  Dating your GAMS run
9  Conclusions

1 Introduction

For some time now my preferred environment for editing and running GAMS programs under Windows has been Alan Phillips’ PFE editor (see PFEGAMS for more on this). But a couple of years ago Alan Phillips announced that he was no longer developing PFE; and ever since, I’ve been on the lookout for a substitute. I think I’ve found one, using Jurgen Doornik’s OxEdit; and this note describes how to obtain and set up this environment, which I call OxEdit+GAMS.

OxEdit+GAMS has some nice features:

Here’s a picture of what you get.

Graphic: oxgams

The top window contains your GAMS program (source code), and the syntax is colored. The bottom window contains output from an unsuccessful GAMS run. If you put the cursor on the line flagging the first error, c:\gams\work\weber\weber1.gms (11) in that window and double-click, the focus will change to (you will be transferred to) line 11 in the source-code window, which, as you can see, contains an obvious error. It’s now easy to fix the error and try again.

Why not use GAMSIDE? Good question: the GAMSIDE is certainly a very nice environment for working with GAMS. For me the drawback to GAMSIDE is that it can be used only for GAMS: I’d prefer an environment that I can use in much the same way whether I’m working with GAMS, C, Perl or whatever. In addition, I typically post-process my GAMS .lst file to extract just the stuff I’m interested in. I can’t do this with the GAMSIDE.

What’s the downside? There are a couple of things you need to be aware of when considering whether to give OxEdit+GAMS a try.

If you’re convinced that this is worth a try, section 3 tells you how to get started.

2 Updates

This section lists updates to the instructions, for easy reference.

Novermber 9, 2001:
Because GAMS was designed as a command-line system, you should ensure that neither the path to your source (.gms) files nor the names of those files, contains a space. Otherwise, the batch files will interpret the space as delimiting a separate parameter, which will typically be unknown to GAMS, generating an error. Long names without a space are OK, though, so instead of (say) my gamsfile.gms you could call your source my_gamsfile.gms.

Added a note on how to tell GAMS that you will be using a non-standard comment character.

September 12, 2001:
Initial release.

3 Get the files

First, do you need to obtain a scripting engine? Start a DOS session. Then

If you do need a scripting engine, then:

The other files you need are:

4 Install the Components

Now install the various parts of the system.

5 Configure the System

We now configure the OxEdit+GAMS system.

5.1 Configure OxEdit

We shall set up OxEdit so that clicking on one icon causes GAMS to compile your file, check for errors, and if any are found, load the error report. A second icon will tell GAMS to run the file, and load either the .lst file or (if you choose) a post-processed version of the .lst file. Note that if the GAMS run produces errors, you’ll still be able to see them from the .lst file, but you won’t be able to jump between the listing and the source. So the preferred sequence is to compile until everything is OK, and then run the program.

Start OxEdit. The first thing is to add the icons to the main toolbar.

Now we’ll set up a couple of useful features (you can add more later as you become familiar with the program).

Next, we set up the ability to run GAMS programs. In OxEdit, this is called “adding a module”.

Next, we’ll set up the Run 2nd Default module. This is pretty much like the one you just set up, so select the Gams Compile entry and click the Clone Entry button. A new entry appears, called something like Tool2. If this appears above the Gams Compile entry, click the Move Down button: it is important that this one appear second.

You may ask: how does the program know which icon is associated with which batch file? The answer is that it depends on the order in which they appear in the module listing. The first module designed for .gms files will be executed with the Run Default icon, while the second one will be executed as the Run 2nd Default icon. So all you need to do to make Run Default actually run your program is to switch the order in the Modules listing box; and as you see, there are buttons provided to do just that.

Lastly, if you don’t like the colors, you can change them: click View -> Preferences -> Colors and syntax highlighting.

That’s it for OxEdit.

5.2 Configure the batch files

We’ll now configure the batch files which will be called by OxEdit to process our GAMS programs. As we’ve seen, there are two sets of files, depending on which scripting engine you’re using. For Perl, we have OxGams1P.bat and OxGams2P.bat; while for VBScript we have OxGams1V.bat and OxGams2V.bat We’ll refer to these generally as OxGams1x.bat, and OxGams2x.bat.

Open OxGams1x.bat in a text editor (of course you can use OxEdit for this).

Next, we configure the file used to run GAMS programs. We’ll install a bare-bones version of this; section 8 explains how to set up enhancements like post-processing. Open OxGams2x.bat in a text editor.

5.3 Configure GAMS

Finally, we need to ensure that GAMS writes its error messages after the line causing the error, rather than at the end of the program listing. You may already have done this.

We’re now ready to test the new system.

6 Testing OxEdit+GAMS

The distribution comes with a simple test file, weber1.gms, which we can use to demonstrate the features of OxEdit+GAMS.

That’s it — you now see how it all works.

7 Using the System

The only trick to note here concerns comments. If you are writing a new GAMS program and starting with a blank document in OxEdit, you need to tell GAMS that you will be using a non-standard comment character. You do this by putting the line

$COMMENT %

at the top of the file. See the next section for how to convert the comments in an existing GAMS file.

8 Extensions

This section discusses a few features which may make the system a bit more useful.

8.1 Comments — gamscom

As mentioned previously, one problem with OxEdit+GAMS is that the editor doesn’t recognize that a * in the first column of your code is a comment. I provide scripts, gamscom.pl or gamscom.vbs, which can convert this (or any) comment to the % character assumed by OxEdit’s GAMS support. The syntax (in a DOS session, from the directory containing the source to be converted, and assuming that the scripts are  in c:\gams\utility) is

Perl:
perl c:\gams\users\gamscomm.pl gamsfile.gms [orig_chr [new_chr]]

VBScript:
cscript c:\gams\use\gamscom.vbs gamsfile.gms [orig_chr [new_chr]]

where orig_chr is the comment character used in gamsfile.gms (default: *) and new_chr is the comment character you wish to use instead (default: %). If you want to use the defaults, both of these may be omitted. The script changes only comments with the current comment character in column 1; and inserts the necessary dollar-control directive ($COMMENT) to support it under GAMS. It also makes a copy of your original file as gamsfile.gms.bak.

You can see how this works by looking at weber2.gms. This is just like weber1.gms except that the comment character is ;. If you load it into OxEdit, you will not get the correct syntax coloring. To fix it, start a DOS session, switch to the gams\users directory and run

Perl:
perl gamscom.pl weber2.gms ;

VBScript:
cscript gamscom.vbs weber2.gms ;

(note that we use the default replacement character). weber2.gms now uses % as a comment character; a copy of the old version is saved as weber2.gms.bak. The new weber2.gms should display correctly in OxEdit.

Note that this is purely cosmetic: GAMS itself knows nothing about coloring. Even if the syntax coloring doesn’t display “correctly”, GAMS will still be able to compile and run your file, provided that it is syntactically correct. And OxEdit’s Run Default and Run 2nd Default icons work whether or not the coloring is correct.

8.2 Postprocessing the .lst file — gamsrd.exe

As we all know, GAMS can produce very large .lst files, and while there are ways to reduce the size, I often find it useful to post-process the .lst file and extract just a summary of what I need to know. The utility program gamsrd.exe is designed to help with this. It scans the .lst file, looking for a unique keyword; when it finds that word, it copies the rest of the .lst file to a new — typically much shorter — file.

I generate the listing by putting a series of display statements at the end of my GAMS program, to report the information I’m interested in. Then I precede these by a special display statement which prints the keyword. The keyword should be a word which doesn’t appear anywhere else in the output. For example, I’ve gotten into the habit of preceding my display statements at the end of the GAMS program by one which says

display "ZQQ - Summary of results" 

with ZQQ being the keyword which flags the beginning of the material to be extracted.

Once this is done, a call to gamsrd extracts the information. The syntax is

gamsrd source_file result_file keyword

So for example, if I want to process road1.lst and create road1.res when I’ve used the keyword ZQQ I’d say

gamsrd road1.lst road1.res ZQQ

The OxGams2x.bat batch files contain built-in support for this, provided that you use the keyword ZQQ, and you want the new file to have the same name as the .lst file, but with extension .res, as in the above example. (Obviously you can change this in the batch files; the important thing is to decide, and stick to that decision). We also deal with the case where your GAMS code does not use this feature, by first creating a .res file, and then checking whether the file is too short (default: 10 bytes or less) to be meaningful. This is done by a program called minsize.exe (also part of the OxEdit+GAMS distribution).

To enable this support:

The file weber1.gms is already set up to support this, so if you now run the file in OxEdit+GAMS you’ll see that we load weber1.res rather than the larger weber1.lst.

8.3 Dating your GAMS run

One problem with this post-processing is that there’s typically no information in the .res file reminding you just when the GAMS run took place. (The .lst file contains this, of course; but the post-processing via gamsrd doesn’t extract that). There appears no way to put this information into a display statement, so we need another strategy. What I do is include a few put statements at the end of my GAMS code to write the date and time of the run into a special file called datime.txt; and then append this to the .res file created with gamsrd.exe.

All this is also supported by OxGams2x.bat. To enable it:

To create datime.txt you should insert the following code snippet at the end of your main GAMS program:

 file datime / datime.txt / ;
 put datime /// "GAMS Run: ", system.date,"   time: ",system.time;
 putclose datime;

the file \users\weber3.gms has done this, and you can run it in OxEdit+GAMS and see what you get.

9 Conclusions

I hope you find this useful; if you do, I’d appreciate hearing from you. You may also want to check this note every so often in case there are changes or bug-fixes. In particular, Jurgen Doornik may implement a first-character-is-a-comment support in a forthcoming revision of OxEdit, in which case conversion of GAMS programs via gamscom.pl will no longer be necessary. If and when this happens, I’ll note it in the Updates section.


Last Revised: November 9, 2001 at 09:55 AM