Overview

shellexecute is a small wrapper program for the ShellExecute Windows API call. It allows you to spawn an external program based on the file type of the document to open.

GAMS provides the execute statement to execute external programs. In some cases we want to let the system figure out what application to start for a given document. This can be accomplished with shellexecute. For instance, when we call:

> shellexecute demo.html

Windows will launch the web browser and show demo.html. This works correctly, irrelevant whether the user installed Microsoft Internet Explorer or Netscape's web browser.

Usage

The command line for shellexecute looks like:

shellexecute [/verb=vvv] [/showcmd=flag] [/dir=ddd] filename args

The filename is either a document (e.g. demo.html or book1.xls) or an application (e.g. winword.exe or notepad). If a document is provided, the associated application will be launched. If a directory name is provided the windows explorer will be launched.

If additional parameters are specified they are considered as command line parameters for the process to be spawned.

The following options are recognized:

/verb=vvv Specifies the action to be performed. The allowed actions are application dependent. Some commonly available verbs include:

verb	Description
edit	Launches an editor and opens the document for editing.
find	Initiates a search starting from the specified directory.
open	Launches an application. If this file is not an executable file, its associated application is launched.
print	Prints the document file.
properties	Displays the object's properties.

If no verb is specified the default command for the file class will be used (in many cases this is open).

/showcmd=flag Flag that specifies how an application is to be displayed when it is opened. The actual behavior is up to the launched program. The possible values are:

showcmd	Description
SW_HIDE	Hides the window and activates another window.
SW_MAXIMIZE	Maximizes the specified window.
SW_MINIMIZE	Minimizes the specified window and activates the next top-level window in the $z$-order.
SW_RESTORE	Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW	Activates the window and displays it in its current size and position.
SW_SHOWMAXIMIZED	Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE	Displays the window as a minimized window. The active window remains active.
SW_SHOWNA	Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.

The default is SW_SHOWNORMAL.

/dir=ddd the default directory for the sub-process.

In many cases you will not need to use any options.

Examples

Below are some examples of ShellExecute. It is noted that much of the behavior is depending on the file associations that are installed on your machine. These file associations can be inspected and changed with the Windows Explorer, see Figure 1.

Figure 1. File associations in the Windows Explorer

Spawning a web browser

> shellexecute turkey.html

Spawning notepad

> shellexecute trnsport.txt

If a different program is associated with a .TXT file, a different program will be launched. In my case notepad will be launched due to the file association shown in Figure 1.

Spawning the GAMS IDE to view a GDX file

> shellexecute trnsport.gdx

Spawning Excel

> shellexecute test.xls

Calling shellexecute from GAMS

execute '=shellexecute trnsport.html';

A complete GAMS example

The following model is the trnsport model from the model library. We write the solution both to an HTML file and a CSV file. HTML is standard ASCII and is easily written using the PUT facility. CSV is even easier, as setting the FILE suffix csv.pc=5; will automatically generate comma separated values. The web browser is launched to view the HTML file, while Excel will be spawned to view the CSV file.

Figure 2. HTML report rendered by web browser

Figure 3. CSV file as displayed by Excel

$title A Transportation Problem (TRNSPORT,SEQ=1)

$onText
Write a solution report in HTML and CSV and spawn
a browser and Excel to view the results.

Erwin Kalvelagen, May 2004
$offText

Set
   i 'canning plants' / seattle,  san-diego /
   j 'markets'        / new-york, chicago, topeka /;

Parameter
   a(i) 'capacity of plant i in cases'
        / seattle    350
          san-diego  600 /

   b(j) 'demand at market j in cases'
        / new-york   325
          chicago    300
          topeka     275 /;

Table d(i,j) 'distance in thousands of miles'
              new-york  chicago  topeka
   seattle         2.5      1.7     1.8
   san-diego       2.5      1.8     1.4;

Scalar f 'freight in dollars per case per thousand miles' / 90 /;

Parameter c(i,j) 'transport cost in thousands of dollars per case';
c(i,j) = f*d(i,j)/1000;

Variable
   x(i,j) 'shipment quantities in cases'
   z      'total transportation costs in thousands of dollars';

Positive Variable x;

Equation
   cost      'define objective function'
   supply(i) 'observe supply limit at plant i'
   demand(j) 'satisfy demand at market j';

cost..      z =e= sum((i,j), c(i,j)*x(i,j));

supply(i).. sum(j, x(i,j)) =l= a(i);

demand(j).. sum(i, x(i,j)) =g= b(j);

Model transport / all /;

solve transport using lp minimizing z;

display x.l, x.m;

*--------------------------------------------------------------------------
* write a solution report in HTML and launch the browser
*--------------------------------------------------------------------------

File html / 'results.html' /;
put  html;

put '<H1>Solution Report</H1>'/;
put 'Optimal objective:',z.l/;
put '<p>'/;

put '<table border="1" cellpadding="3" cellspacing="0">'/;

put '<tr><td></td>';
loop(j, put '<th>',j.tl,'</th>' );
put '</tr>'/;

loop(i,
put '<tr><th>',i.tl,'</th>';
loop(j, put '<td>',x.l(i,j),'</td>' );
put '</tr>'/;
);

put '</table>'/;

putClose;

execute '=shellexecute results.html';

*--------------------------------------------------------------------------
* write a solution report in CSV and spawn Excel to view it
*--------------------------------------------------------------------------

File csv /results.csv/;
csv.pc=5;
put  csv;
put "Optimal Objective","",z.l/;
put /;
put '';
loop(j, put j.tl);
put /;

loop(i,
   put i.tl;
   loop(j, put x.l(i,j));
   put /;
);

putClose;
execute '=shellexecute results.csv';

Exporting to MS Access

This example will launch MS Access after exporting a parameter to a MDB file.

$onText
Test of GDX2ACCESS. Dumps a symbol to an Access Database,
and launches MS ACCESS.
$offText

Set i / i1*i100 /;
Alias (i,j);

Parameter p(i,j);
p(i,j) = uniform(-100,100);
execute_unload 'test.gdx',p;

execute '=gdx2access test.gdx';
execute '=ShellExecute test.mdb';

Common error messages

File does not exist

E:\wtools\ver000\examples>shellexecute xxxx.html
ShellExecute Version 1.0
The system cannot find the file specified

No file association

E:\wtools\ver000\examples>shellexecute table02.dbf
ShellExecute Version 1.0
No application is associated with the specified file for this operation

Table of Contents