ShellExecute

A Tool for Launching External Programs.

Date
March 25, 2004

# 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


> 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 '=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

GAMS Development Corp.
GAMS Software GmbH

General Information and Sales
U.S. (+1) 202 342-0180
Europe: (+49) 221 949-9170