Navigation

List of Pages

Meta:

Valid XHTML

Valid css

MODx

This is a macro for using GAMS (General Algebraic Modeling System) in Emacs.
The stable version is 3.2 --- 2009-12-21

Page Contents

If you want to know about GAMS and Emacs, please see the following sites.

GAMS Home Page for GAMS.
GNU project for Emacs.

Main features

GAMS mode for Emacs offers the integrated and flexible environment for using GAMS in Emacs.

When you use GAMS, you must do the following jobs:

Editing GAMS program file,
Calling GAMS to execute the program,
Reading the output file,
Debugging the program,
Examining the numerical values in the output file,

and so on... GAMS mode for Emacs offers various kinds of features which raise your efficiency in all of these jobs.

GAMS mode for Emacs offers the following four major modes (I skip the explanation of the Emacs terminology "major mode". If you cannot understand the terminology, I recommend that you read the introductory document of Emacs first).

GAMS mode: for editing GAMS program files.
GAMS-LST mode: for viewing LST files.
GAMS-TEMPLATE mode: for handling templates of programs.
GAMS-OUTLINE mode: for viewing important items of LST files.

Furthermore, the following features are included in each major mode.

GAMS mode:

This is the major mode for editing GAMS program file.

Inserting GAMS statements and dollar control options.
Automatic registering of new statements and dollar control options.
Calling GAMS from Emacs
Like GAMSIDE, it colors a program file in accordance with the GAMS syntax.
Handling templates of various programs (this is GAMS-TEMPLATE mode).
Automatic indent.
Reading GAMS manual.
Extracting models from GAMS model library.

I will explain each function in detail.

By resistering GAMS statements and dollar control options beforehand, (1) enables you to insert them into the program file easily. You can insert the long statements and dollar control options (that you are likely to mistype) without typing them by yourself. [statement.png], [dollar.png].

Although there are a lot of GAMS statements and dollar control options, only a part of them is registered by default in GAMS mode. It is because frequently used statements differ according to users, and because it is desirable to exclude rarely used statements from candidates of input function of (1). However, (2) enables you to register new statements and dollar control options. You can easily add the commands that you frequently use to the candidate for command inserting function of (1). [register.png].

(3) is the function to call GAMS directly from Emacs for executing the gms file.[process.png].

Like the GAMSIDE, (4) provides the colorization of GAMS program files accoring to GAMS syntax.

When editing GAMS program files, you may often use similar patterns frequently. In that case, you may copy and paste the program repeatedly. But it is surely more convenient if you can register frequently used patterns and select them. Or, although the pattern is not frequently used, it may be hard to remember it. Also in that case, it seems convenient if you can use registered patterns. (5) offers you the feature for registering various patterns easily. In addition to registering, you can modify, delete, rename, re-order existing templates easily. [template.png].

I think that many people agree with the opinion that the proper indent is important for writing programs that other people (or yourself) can read easily. But it is quite tedious to insert spaces and TABs manually by yourself. In GAMS mode, each line is automatically indented according to GAMS syntax.

GAMS-LST mode:

This is the major mode for viewing the output file (i.e. LST file).

Display the error place and its meaning.
Jump to the error place in the program file.
Jump to the various places in the LST file.
Color the content of the LST file.
Display the important items of the LST file (this is the GAMS-OUTLINE mode).

In editing GAMS program, one of the most important job is debugging. Your efficiency of writing program crucially depends on the efficiency of debugging. (1) and (2) are the functions for that.

With (1) and (2), you can do the following jobs quickly with simple key operation. [error.png].

Call GAMS and execute the program.
Move to the LST file.
Examine the place and meaning of errors.
Go back to the error place in the program.

You can do similar things also in GAMSIDE, but, I think GAMS mode offers the more convenient environment.

LST files often become quite large. In that case, it is hard to search the output that you want to see. (3) provides you the feature for moving to various important items (such as PARAMETER, SET, VAR, EQU) in the LST file with simple key operation.

Function (4) colors the content of LST files.

As pointed out above, LST file is often very large and it is often very diffcult to find the numerical values that you want to see. And it is also diffcult to compare the numerical values in two different parts of the LST file. Although you may be able to resolve these problems by defining parameters that display only relevant values, it is more convenient if you can examine the content of the LST file in a simple way.

(5) provides the way for that. With this feature, you can easily view the important elements (PARAMETER, VAR, EQU etc.) in LST files.

You can see where the particular PARAMETER or VAR are and can see the content of them. You can also compare the numerical values in a part of the file with that in another part. [out-basic.png], [out-view.png], [out-select.png].

These are the simple explanation of this program. Of course, there are a lot of other functions!

This program has been tested under GNU Emacs of version 20 and 21 on MS Windows Me/2000. I received a report from the person who uses this program on UNIX system that it works well in Emacs on Unix. So, this program probably works in Emacs of version 20 and 21 on any platforms. I also tested this under XEmacs 21.4 for MS Windows and it seems to work without serious problems.

Bug reports and requests, suggestions are welcome! Please email me . To report bugs, please use M-x gams-report-bug

[The top of this page]

Screenshots page

Here.

[The top of this page]

Download and installation

Download gams-3.2.zip -- 2009-12-21
Installation.
Please extract the archive and read README.txt file. If you want to know newly added functions, plese read CHAGES.txt file.

The files included in the zip archive.

README.txt	First read this file.
CHANGELOG.txt	Change log file. If you want to know changes and newly added functions, please read it.
BUGS_PROBLES.txt	Known bugs and problems
gams.el	The main lisp program.
dot-emacs-sample	A sample file for setting. Copy and paste the content of this file into your "~/.emacs.el"
gams-sample.gms	A sample file to show how to use GAMS mode for Emacs.
sample-include.gms	Put this file at the same directory as gams-sample.gms.
outline-sample.gms	A sample file to show how to use GAMS-OUTLINE mode.
.gams-template	A sample file of templates. Save this file in your HOME directory.
refcard-gams.pdf	Reference card for key-bindings.

[The top of this page]

Changelogs:

3.2: 2009-12-21

Since gams.el ver. 3.1, you can specify the name and place of the LST file. In addition, gams.el ver 3.2 enables you to specify the LST file directory (the directory where lst files are stored).
To use this feature, put the following code in your gms file.

[Example]
```
  * gams-lst-file: .\listing\sample.lst
  * gams-lst-dir: .\result
```
gams-lst-file specifies the name and place of the lst file and gams-lst-dir only specifies the directory for the lst file.

[Usage of gams-lst-file and gams-lst-dir]

Example 1:
```
  * gams-lst-file: .\listing\sample.lst
```
By this code, the lst file -> .\listing\sample.lst

Example 2:
```
  * gams-lst-file: c:\sample.lst
```
By this code, the lst file -> c:\sample.lst

Example 3:
Suppose that your gms file is "gams-sample.gms".
```
  * gams-lst-dir: .\listing\
```
Then the above code means that the lst file is ".\listing\gams-sample.lst".

Example 4:
Similarly,
```
  * gams-lst-dir: c:\
```
This code means that the lst file is "c:\gams-sample.lst".
Notes:
1. You can use both full path and relative path to specify the LST file and directory.
2. This function does not support file and directory name with spaces. It is because `o=' option of GAMS does not support such file name.
3. If gams-lst-file and gams-lst-dir are not set, gams-mode assumes that the LST file has the same name as GMS file and is placed at the same directory as the GMS file.
4. If both gams-lst-file and gams-lst-dir are set, the former overrides the latter.
5. If you want to put the LST file in another directory, that directory must be created bofore you run gams.
6. The lst file set by gams-lst-file or gams-lst-dir is overwritten with the one determined by o= setting in *#! notation.
Added the new variable `gams-lst-dir-default'. If you always want to save all lst files in a specific directory, set the directory to this variable.
For example, the following code implies that all lst files are saved in the subdirectory "lst" under the current directory:
```
  	(setq gams-lst-dir-default ".\\lst\\")
```
Similarly, the following code implies that all lst files are saved in the directory "c:\lst\".
```
  	(setq gams-lst-dir-default "c:\\lst\\")
```
If you set nil to this variable (the default setting), lst files are saved in the current directory.
Note: If gams-lst-file or gams-lst-dir are set in a GMS file, the specification of the variable 'gams-lst-dir-default' is overwritten.

3.1.1: 2009-10-11

Fixed bugs in coloring and `gams-show-identifier'.
Added `gams-sample-ja.gms' for Japanese users.

3.1: 2009-08-03

A new feature: To move from the GMS file to the corresponding LST file, the previous gam-mode premises that both files have the same name (expect for the extension) and are placed in the same directory. In the new gams-mode, you can use the different name for the LST file and put it in the different directory.

For example, if you want to let `sample.lst' be the name of the LST and and put it in the subdirectory `listing'. Then, add the following code somewhere in the gms file:
```
  * gams-lst-file: .\listing\sample.lst
  
```
This code has two effects:
1. gams is executed with option 'o=.\listing\sample.lst'
2. You can switch from the gms file to .\listing\sample.lst by C-cC-v (or F10).
Notes:
1. To specify the LST file, use the *relative* path and do not use *absolute* (full) path.
2. This function does not support file and directory name with spaces.
3. If gams-lst-file is not set, gams-mode assumes that the LST file has the same name and is placed at the same directory as the GMS file.
4. If you want to put the LST file in another directory, that directory must be created bofore you run gams.
5. The lst file set by gams-lst-file is overwritten with the one determined by o= setting in *#! notation.
The default key-binding for `gams-show-identifier' is changed from `C-c..' to `C-cC-.'.
Added the more explanation on *#! notation to gams-sample.gms. *#! notation is a way for changing a command line easily (this is a function like #!/usr/bin/perl or #!/bin/sh for shell scripts). For the details, see gams-sample.gms file.

3.0: 2009-07-19

Added the new mode called GAMS-LXI mode. This mode provides a function that resembles the GAMSIDE listing function (see the screen-shot page). For the details, see /lxi/gams-lxi-sample.gms file. Note: To implement GAMS-LXI mode, the following code is added to gams.el.
```
  (add-to-list 'warning-suppress-types '(undo discard-info))
  
```
This code might cause some problems.
Minor change on `gams-start-menu'.
The value of `truncate-lines' in GAMS-LST mode changes from nil to t. This means that continuation lines are not displayed in GAMS-LST mode. If you like the old behavior, use the following hook setting:
```
  (add-hook 'gams-lst-mode-hook
            '(lambda ()
               (setq truncate-lines nil)
               ))
```
Minor change on `gams-show-identifier-list' (the command evoked by C-cC-a). $prod, $demand and $constraint blocks in MPS/GE are displayed in GAMS-SIL mode.
Added the new command `gams-lst-file-summary' in GAMS-LST mode (the default key-binding is ".").

2.7.1: 2009-03-13

Fixed the bug related to GAMS process.

2.7: 2009-03-10

Changed the default value of `gams-recenter-font-lock' to t (you can recolor the block around the cursor by `C-l').
Fixed the bug in coloring.
The new gams.el displays last modification time of LST file in the minibuffer when you move from GMS file to LST.
The previous gams.el cannot handle multi-character inline and end-of-line comment symbols like "/*", "*/" "//". In the new gams.el, you can use multi-character comment symbols. In addition, the default inline comment symbols are changed to "/*" and "*/".
```
(setq gams-inlinecom-symbol-start-default "/*")
(setq gams-inlinecom-symbol-end-default "*/")
  
```
Function `gams-lst-jump-to-input-file' (key `i' in GAMS-LST mode) in the previous gams.el often fails when an input file name includes spaces. The new gams.el fixed this bug.
Added function `gams-lst-next-elt', `gams-lst-previous-elt', `gams-lst-next-clt', `gams-lst-previous-clt' in GAMS-LST mode (the default keybindins are `x' and 'c'). By these commands, you can move to `Equation Listing' and `Column Listing' part in the LST file.
Bug fix for the pretest version of Emacs23 (Emacs 23.0.9x). The GAMS-OUTLINE mode in the previous gams.el does not work well in pretest version of Emacs 23.
In the new Emacs (ver 23.0.9), the default value of `comment-style' changed from `plain' to `indent'. By this change, `gams-comment-region' (and `comment-region') command fails. To avoid this, please set plain to comment-style as the old Emacs:
```
  (setq comment-style 'plain)
  
```
Added function `gams-report-bug'. This command outputs information for debugging GAMS mode. This command must be executed in a GAMS mode buffer. Please use this `gams-report-bug' function when you encounter some bugs.

2.6.1: 2009-01-07

Fixed the bug in coloring.
`gams-show-identifier-list' now displays identifers defined by table.
GAMS-OUTLINE mode in the previous versions has a serious bug. This bug is fixed in the new version.
The new gams.el can handle a file name with spaces like "foo bar 1.gms".

2.6: 2008-12-20

Added the new function `gams-ol-toggle-display-style' which is binded to `x' in the GAMS-OUTLINE mode. By this command, you can toggle the display style (vertical or horizontal style) in the GAMS-OUTLINE mode (see the screen-shot page). If you have a wide display, you had better select the horizontal style where two (or three) windows are arrayed horizontally.

The default style is determined by the variable `gams-ol-display-style'. The width of the left column in the horizontal style is determined by the variable `gams-ol-width'.
Added the new variable `gams-process-log-to-file' (the default value is nil). If you set non-nil to this variable, GAMS log is written to the log file even without lo=2 option. GAMS log in this context means the content of GAMS process buffer. The extention of log file is determined by the variable `gams-log-file-extension' ("glg" by default).
Added `gams-toggle-hide/show-comment-lines', which is binded to `C-cC-h'. This command enables you to hide (or show) all comment lines (lines started with * and lines enclosed by $ontext-$offtext pair) in the buffer. Note that this command only hide lines and makes no modification to the buffer.
The GAMS-OUTLINE mode displays more items (for example, Compilation, Include File Summary etc.). The new GAMS-OUTLINE mode is not compatible with the old one. So, please delete the following part in ~/.gams-statement" if it exist:
```
  (setq gams-user-outline-item-alist '(
  ....
  ))
```
In addition, please change the setting for the variable `gams-ol-view-item'.
Fixed the bug in `gams-show-identifier'.
Fixed the error in the sample template file ".gams-template".
Fixed the bug in font-lock (coloring) for gams mode.
A minor change to `gams-show-identifier-list'.
Changed GAMS-SIL mode. Explanatory text for equations in equation declaration part (EQU part) is displayed also in equation definition part (DEF part). Similarly, explanatory text for model in model declaration part (MOD part) is displayed also in solve statement part (SOL part).
Added the function `gams-change-gams-command'. You can change GAMS command name in the process menu as you can change gams commad line option. Try `C-cC-tc'. The registered GAMS command name is stored in the file determined by `gams-statement-file'.
Changed `gams-show-identifier'. Now, you can extract (copy) the explanatory text from the identifier declaration part. Try `C-c..' and type `e'.

Four display styles for the GAMS-OUTLINE mode.

2.5.1: 2008-07-22

Fixed the error in the sample template file ".gams-template".

2.5: Sat Mar 29 2008

Added the new variable `gams-docs-directory'. This variable determines the GAMS document directory. By default, it is set to `gams-system-directory' + docs.
Fixed bugs in the function `gams-view-docs'.

2.4: Sun Dec 17, 2006

Modified the indentation function. The new gams mode makes cleverer indentation.
Supported Emacs 22. Now, you can use gams.el in Emacs22.
Modified `gams-show-identifier-list' command. Now, `gams-show-identifier-list' command list wider variety of identifers.

2.3: Sat Nov 5, 2005

Fixed bugs for XEmacs.
Fixed bug in GAMS-OUTLINE mode.

2.2: Sun Sep 4, 2005

Fixed bugs in coloring of MPSGE block.
Fixed bug in `gams-insert-statement-extended'. Now, `gams-insert-statement-extended' works well also in the case that `gams-statement-upcase' is non-nil.

2.1: Sat Nov 6, 2004

Added the new function `gams-show-identifier-list' (binded to C-cC-a by default. This command displays the list of all GAMS identifers existing in the gms buffer.
Abolished the variable `gams-docs-dir'. You must assigne a proper value to `gams-system-directory' if you want to use `gams-view-docs'. `gams-view-docs' does not work in some versions of
Added the new variable `gams-special-comment-symbol' (default is "com:").
Fixed bugs in `gams-lst-jump-to-error-file'.
Fixed many bugs in coloring.

2.0: Tue Sep 9, 2003

Abolished the command `gams-show-identifier-defintion' (C-c.) and added the new function `gams-show-identifie'. Try "C-cC-." and "C-uC-cC-." in GAMS mode. See also "gams-sample.gms".
Added the new command `gams-insert-statement-extended'. Try "C-cC-n" in GAMS mode.
Exchange the role of "l" key and that of "L" key in GAMS-LST mode.
Changed indentation pattern and added the new variable `gams-indent-more-indent' (default value is nil). If you want to use the previous type of indentation, set t to the variable `gams-indent-more-indent'. If `gams-indent-more-indent' is nil, the following indentation is realized.

set
    i   Sector index / agr, man1, man2, ser /,
    f   Primary factor index
    / cap, lab, lan /
    c   Commodity index /
    agr, man, ser /;

set
    i   Sector index / agr, man1, man2, ser /,
    f   Primary factor index
        / cap, lab, lan /
    c   Commodity index /
        agr, man, ser /;

Changed some keybindins. See gams-refcard.pdf.

1.10: Sun Feb 16, 2003

Added the new function `gams-comment-region' (C-cC-;). This function is an alias for `comment-region'. Select an region and type C-cC-;, then you can comment out it. You can also uncomment the commented-out region by attaching the universal argument like (C-uC-cC-;).
Added the new function `gams-replace-statement' which replaces the existing statements or dollar control options with the new one. If you execute this command on the existing GAMS statements or dollar control options, you can replace them with the new onew. To execute this command, attach the universal argument to C-cC-k and C-cC-d (i.e. C-uC-cC-k, C-uC-cC-d).
Added the new function `gams-ol-refresh' (binded to r in GAMS-OUTLINE mode). Refresh the GAMS-OL buffer if the LST file is updated.
Modified `gams-insert-parens'. In the previous version, typing `(' inserted a pair of parenthesis if `gams-close-paren-always' is non-nil. Now, if you attach the prefix argument to `(' [i.e. typing `C-u ('], just insert `('.
Added the new variable `gams-ol-item-name-width' (its default value is 18). The width of item name field in GAMS-OUTLINE.
Modified display in GAMS-OUTLINE mode.

1.9: Tue Jan 14, 2003

Added the new variable `gams-sd-included-file' (its default value is t). If this variable is assigned non-nil, `gams-show-identifier-defintion' searches the identifier definition also in the files included through $include or $batinclude. If nil, search the identifier definition only in the current file.
Fixed the bug in coloring.
Fixed the bug in `gams-show-identifier-defintion'.

The older changelogs are found here.

[The top of this page]