Executing an external application

Copyright © 2000 Ernesto De Spirito

ShellExecute

Many times we need to execute another program from ours. To do this, we can use the ShellExecute function declared in the ShellAPI unit. The syntax is:

ShellExecute(Handle, Operation, FileName, Params, Folder, ShowCmd)

• Handle (HWND) is the window handle of the parent window, for instance the window handle of the main form of our application.
• Operation (PChar) is a pointer to a null terminated string that contains the name of the operation to perform, which can be 'edit' (launches an editor and opens the document for editing), 'explore' (explores the specified directory), 'find' (opens the find window starting from the specified directory), 'open' (executes or opens the file with the associated application), 'print' (printes the specified file) or 'properties' (displays the file or folder's properties). This parameter can also be nil and in this case 'open' will be assumed.
• FileName (PChar) is a pointer to a null terminated string that contains the path and the name of the application to execute, the document to open or print with its associated application, or the folder to open or explore.
• Params (PChar) is a pointer to a null terminated string that contains the parameters that will be passed to application specified in FileName. If FileName doesn't indicate an executable file but a document, then Params should be nil.
• Folder (PChar) is a pointer to a null terminated string that contains the path that will be taken as the application's folder by default. This parameter can be nil.
• ShowCmd (Integer) indicates the way the application specified in FileName will be shown. There are various possible values:

  SW_HIDE SW_RESTORE SW_SHOW SW_SHOWNA

  SW_SHOWNORMAL SW_SHOWDEFAULT SW_MAXIMIZE SW_MINIMIZE

  SW_SHOWMAXIMIZED SW_SHOWMINIMIZED SW_SHOWMINNOACTIVE SW_SHOWNOACTIVATE

  The documentation states that if FileName refers to a document, ShowCmd should be 0, but if you try other values you will see they work.

Return value: If ShellExecute succeeds, it returns a value of type HINST (a LongWord) with the instance handle of the application that was run, or the handle of a dynamic data exchange (DDE) server application. If it fails, it returns an error code from 0 to 32.

Examples

uses ShellAPI;

...

if ShellExecute(Form1.Handle, nil,
    'c:\windows\general.txt', nil, nil, SW_SHOW) <= 32 then
  Application.MessageBox('Couldn''t execute the application',
    'Error', MB_ICONEXCLAMATION);

ShellExecute(Form1.Handle, nil, 'c:\windows\notepad.exe',
  'c:\windows\general.txt', nil, SW_SHOWMAXIMIZED);

ShellExecute(Form1.Handle, 'open', 'c:\windows\notepad.exe',
  'general.txt', 'c:\windows', SW_SHOWNORMAL);

ShellExecute(Form1.Handle, nil, PChar(fname + '.txt'),
  nil, nil, SW_MAXIMIZE);

ShellExecute(Form1.Handle, nil, 'c:\windows\notepad.exe',
  nil, nil, SW_SHOWNORMAL);

Note

An application called by ShellExecute will run asynchronously, that is, the execution of our application continues without waiting the end of the called application that will run simultaneously. If you need to run an application synchronously, please read Waiting till an application ends.