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.
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.
The only way I know to handle this at the moment is to use GAMS’s facility for redefining the comment symbol. The setup files for OxEdit assume that % is the comment character, and I provide scripts to convert existing GAMS files.
The scripts are important to OxEdit+GAMS, since they read GAMS’s .lst file and extract the error messages. Of course, you could dispense with the script, and simply load the entire .lst file when GAMS finishes; but then you lose the interaction between errors and the source.
If you’re convinced that this is worth a try, section 3 tells you how to get started.
This section lists updates to the instructions, for easy reference.
Added a note on how to tell GAMS that you will be using a non-standard comment character.
First, do you need to obtain a scripting engine? Start a DOS session. Then
If you do need a scripting engine, then:
— of course, you want the MS Windows version. If you are not running on Windows 2000 or Windows ME, you also need the Microsoft Installer (MSI): at the ActiveState site, at the right-hand part of the page, click on Release Notes -> Windows(x86) to download this. The total download (Perl + MSI) is about 10 MB.
The download is about 850K, so it’s a lot smaller than Perl. If you think you might want to write your own scripts, you might also want to obtain the documentation.
The other files you need are:
— click on “OxEdit” in the left-hand frame, and go from there.
Now install the various parts of the system.
We now configure the OxEdit+GAMS system.
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.
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.
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.
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.
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
at the top of the file. See the next section for how to convert the comments in an existing GAMS file.
This section discusses a few features which may make the system a bit more useful.
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
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
(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.
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
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
So for example, if I want to process road1.lst and create road1.res when I’ve used the keyword ZQQ I’d say
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.
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.
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.