The OpenEdge Hive

ShellExecute is the procedure that is called by the Desktop or Windows Explorer when you double-click an item: if the item is an executable it will run it, if the item is a Word-document it will open it in MS-Word, etc.
There is a lot you can do with this easy-to-use procedure. Let's have a look at the parameters:

PROCEDURE ShellExecute{&A} EXTERNAL "shell32" :
     DEFINE INPUT PARAMETER HWND AS LONG.
     DEFINE INPUT PARAMETER lpOperation AS CHARACTER.
     DEFINE INPUT PARAMETER lpFile AS CHARACTER.
     DEFINE INPUT PARAMETER lpParameters AS CHARACTER.
     DEFINE INPUT PARAMETER lpDirectory AS CHARACTER.
     DEFINE INPUT PARAMETER nShowCmd AS LONG.
     DEFINE RETURN PARAMETER hInstance AS LONG.
  END.

The parameters are:
* hwnd : parent window that will receive a possible messagebox. This parameter is usually 0
* lpOperation : "open" or "print"
"print" is only valid if lpFile is a document
* lpFile : name of an executable or name of a document
* lpParameters : command-line parameters for the executable in lpFile
* lpDirectory : default directory to execute lpFile in
* nShowCmd : Same as in winexec: hidden=0 normal=1 minimized=2 maximized=3
* hInstance : If function succeeds hInstance will be the instance handle of the executed program. If the value is >=0 and <=32 the function failed.

As you can see there are different ways to perform "notepad.exe c:\readme.txt" :

RUN ShellExecute{&A} IN hpApi(0,
                              "open",
                              "notepad.exe",
                              "c:\readme.txt",
                              "",
                              1,
                              OUTPUT hInstance).

RUN ShellExecute{&A} IN hpApi(0,
                              "open",
                              "c:\readme.txt",
                              "",
                              "",
                              1,
                              OUTPUT hInstance).

The second example shows an important feature of ShellExecute: opening a document. It uses associations to find the matching executable. Both examples will have the exact same result if the extention ".txt" is associated with "notepad.exe".

Examples

The following examples, submitted by Rob den Boer, show how ShellExecute can be used to send email, or to open the default browser for a particular website:

Sending email

  DEFINE VARIABLE email AS CHARACTER NO-UNDO.
  email =   "mailto:rc.den.boer@hccnet.nl"
          + "?cc=piet@nowhere.nl"
          + "?Subject=Test%20by%20Rob"  /* notice %20 instead of space */
          + "?Body=How are you doing".
 
  RUN ShellExecute{&A} IN hpApi 
                   (0,
                    "open",
                    email,
                    "",
                    "",
                    1,
                    OUTPUT hInstance).

open a website in your default browser

  RUN ShellExecute{&A} IN hpApi 
                   (0,
                    "open",
                    "ftp://zdftp.zdnet.com",
                    "",
                    "",
                    1,
                    OUTPUT hInstance).
/* or: */ 
  RUN ShellExecute{&A} IN hpApi 
                   (0,
                    "open",
                    "http://home.hccnet.nl/rc.den.boer/progress/index.html",
                    "",
                    "",
                    1,
                    OUTPUT hInstance).