Welcome To The Home Of The Visual FoxPro Experts  
home. signup. forum. archives. search. google. articles. downloads. faq. members. weblogs. file info. rss. print.

Forget the ancient RUN command. If you need to invoke an external application from within VFP, this handy API call is all you'll need.

Have you ever needed to run an external program from within your Visual FoxPro application? Or pop up an email message window? Or play a sound file? Or display a web page in the user's browser? Or open a file folder? Or launch the Find File dialogue? Or print an RTF document? Or do just about anything else that involves running another process or application on the user's computer?

You can perform all these tasks - and many more - by courtesy of a versatile API function called ShellExecute(). The function has dozens of uses, and, if you have not yet made its acquaintance, we strongly recommend that you do so now.

What does it do?
At its simplest, ShellExecute() lets you programmatically launch any application which is installed on the user's computer. So, let's say you want to run Winzip from within your Visual FoxPro program, this is how you would go about it with ShellExecute():

DECLARE INTEGER ShellExecute IN shell32.dll ; 
	INTEGER hndWin, ; 
	STRING cAction, ; 
	STRING cFileName, ; 
	STRING cParams, ; 
	STRING cDir, ; 

cFileName = "c:\Program Files\Winzip\Winzip32.Exe" 
cAction = "open" 

Because ShellExecute() is an API function, you need to declare it before you can call it. The DECLARE statement establishes the number and data types of the parameters, and also the data type of the returned value. You only need to execute the DECLARE statement once, but you must do so before the first time you call ShellExecute().

As you can see in the above code, ShellExecute() takes six parameters. These are as follows:

The handle of the program's parent window. In VFP, you will usually set this to 0.

The action which is to be performed (see below).

The file (or other 'object') on which the action is to be performed (see below).

If the file is an executable program, these are the parameters (if any) which are passed to it in the command line.

If the file is an executable program, this is the program's default or start-up directory.

The program's initial window state (1 = normal, 2 = minimised, 3 = maximised).

Note that the parameter names shown here are for illustration only. Within the DECLARE statement, you can give the parameters any names you like, or you can omit the names completely. But you must specify the data types. Note also that the function name, ShellExecute, is case-sensitive within the DECLARE statement.

The most important parameters are the action and the filename. If you want to use ShellExecute() to launch a specific program, the action is the word 'open' and the filename is the fully-qualified filename of the EXE file, as in the above example.

Make it generic
Although the above code works fine on our system, it might not work on yours. That's because the code assumes that Winzip is located in the c:\Program Files\Winzip folder, which is not necessarily the case. For that matter, it also assumes that Winzip is installed on the user's computer and that its executable filename is Winzip32.Exe.

A more generic approach would be to specify, not the name of the Winzip program, but that of the zip file that you want to open. In that case, the call to ShellExecute() would look something like this:

cFileName = "f:\Data\Archive.Zip" 
cAction = "open" 

The advantage of this approach is that it will work regardless of where Winzip is located. It will even work if the user has installed a different utility to process zip files - provided that the utility in question is associated with the ZIP file extension.

Similarly, if you wanted to let the user edit a DOC file, you could do so like this:

cFileName = "d:\MyDocs\Chase.Doc" 
cAction = "open"

Again, not only don't you have to know the path and filename of the Microsoft Word executable program, you don't even need to know if Word is installed. If it is not, the above code will open Wordpad or whatever other word processor is associated with DOC files on the user's system.

Nor are you limited to opening the file. ShellExecute() can perform any action which is registered for the relevant document type. In the case of a DOC file, you could just as easily print the file. To do so, simply change the action parameter from 'open' to 'print', like so:

cFileName = "d:\MyDocs\Chase.Doc" 
cAction = "print"

More possibilities
Here are some more ideas for putting ShellExecute() to work:

cFileName = "www.ml-consult.co.uk" 
cAction = "open"

This will display the specified web page in the user's default web browser.

cFileName = "mailto:john@mycompany.com" 
cAction = "open"

Here, we are launching a message composing window in the user's default mail client, with the specified email address already entered in the To line. Going further, you can also fill in the CC and BCC lines, as well as the actual message text. For more details of this technique, see the article, An easy way to send email from a Visual FoxPro application.

cFileName = "c:\data" 
cAction = "open"

This simply opens the specified folder window. If you change the action to 'explore', it will open Windows Explorer with the specified folder in focus. Or you could specify 'find' as the action. That would launch the Windows Find File dialogue, with the folder name entered in the Look In box.

cFileName = "quikview.exe" 
cAction = "open"

This opens the specified document in the Word QuickView window, which is handy if you want to let the user see the document but not edit it. Of course, this assumes that Quikview.exe is installed on the user's computer (but you don't have to specify its path as it is usually held in the System folder).

In that last example, the document name is passed as a command-line parameter, that is, as the fourth parameter to ShellExecute(). Note that you have to provide the full path to the document, even if the file is in the VFP search path. ShellExecute() doesn't know anything about VFP's DEFAULT or PATH settings. However, if the file in question is in the VFP search path, you can always use FULLPATH() to establish the fully-qualified filename.

Here are two final examples:

cFileName = "c:\music\Mozart.Wav" 
cAction = "play"

This will play the specified wave file. Your program doesn't need to know which wave-playing utility is installed on the user's system.

And finally, this opens the property sheet for a given shortcut:

cFileName = "c:\Windows\Desktop\Word.Lnk" 
cAction = "properties"

Remember, in all these examples, you must already have executed the DECLARE statement. If you plan to call ShellExecute() from different parts of your application, you will probably run the DECLARE near the top of your main program.

Registered actions
How do you know what actions are available for a given file or document?

One way to find out is to look in the Folder Options window. You get to this window from the Tools menu in Windows Explorer or in any folder window. Go to the File Types tab (Figure 1) and scroll down until you see the file type that you are interested in. Select it, then click the Edit button (this is labelled Advanced in some versions of Windows). The Edit File Type dialogue (Figure 2) will show you all the registered actions - New, Open, Print and Printto in this example.

Figure 1: The File Types tab lists all the registered document types.

Figure 2: Use this dialogue to view the registered actions.

Another method is to look in the Registry. The actions are specified as sub-keys of HKEY_CLASSES_ROOT\


Mike Lewis Mike Lewis is a Visual FoxPro developer and trainer. His company, Mike Lewis Consultants Ltd., runs training courses at clients' sites throughout Europe and North America. Please visit his company's web site at www.ml-consult.co.uk for company and contact information.
© Copyright Mike Lewis Consultants Ltd.


vatch @ 12/18/2006 6:55:02 PM
wow this is simply perfect..ty

Didik Rhd @ 8/1/2010 4:44:22 AM
please give me sample to find out a program already in open or not?

ramesh m @ 12/24/2011 2:48:51 PM
Thread ID: 330836 ramesh m Esc key problem Sir, I have created a personalised package using VFP6. The OS is Windows 7. The main screen shows a menu system & a bmp file. When I mouse click or press 'Esc', the menu system disppears & the screen freezes. I have to press the close button to get out of the package. When I press 'Esc' key or mouse click at a region other than where pads are shown, nothing should happen.
Please help.

haejosh haejosh @ 4/27/2018 3:59:05 AM

Your Name: 
Your Feedback: 

Spam Protection:
Enter the code shown: