GUI ScreenIO for Windows

 ScreenIO.com


ShellExecute

This API lets you process a file (or URL) using the system's file associations to determine and launch the default application for the type of file that you supply.  Optionally you can cause GUI ScreenIO to suspend operations until the launched application exits.  The default is for the launched task to operate asynchronously and for GUI ScreenIO to return directly to your program while the task continues to run.

We don't actually invoke the ShellExecute API with this function, we emulate it.  The actual ShellExecute API will not work on Windows 9x systems unless you install the Microsoft Layer for Unicode, and we wished to avoid forcing you to do that.   Our implementation does more than the ShellExecute API, too.

Application notes

This function calls WinExec to launch the appropriate application once it has identified it.  See WinExec for details.

Our implementation works by examining the system registry to obtain the default application for a given filetype.  The registry supplies the complete path to the executable, so it does not need to be on the PATH.

File associations/default applications

Note that the default application can vary according to the software installed on a system, and according to the user's preferences. 

For example, do not assume that .txt files are always associated with Notepad.  Some users may have altered their default application to use a different text editor.  Likewise, the default browser could be any of several browsers; Internet Explorer, Netscape, Mozilla, Opera, etc. 

If your application requires the use of a specific, be sure to load SHELLEXE-FILETYPEID with the file type identifier for the package that you require.

SHELLEXE-FILETYPEID is returned to your program so that you will know what FileTypeId was used.  Be sure to set or clear this for each use.

Finding the default application

Finding the default application is a two-step process.  You can verify this by examining the registry yourself, using Regedit.exe, which is present on all systems running Windows 95 and above.

First, obtain the file type identifier using this registry key:

HKEY_CLASSES_ROOT\.ext

where .ext is the file extension you're interested in; .txt, for example.  The default value is most likely txtfile, which is the file type identifier for the Notepad application. 

Now, use that to locate the application for this filetype:

HKEY_CLASSES_ROOT\txtfile\shell\open\command

and you'll probably find it contains this value:

%SystemRoot%\system32\NOTEPAD.EXE %1

The token %SystemRoot% occurs on Windows NT-based systems, and will be replaced by the value for the environmental variable SystemRoot.  Windows 9x-based systems may contain the pathspec to the location of the executable file. 

Your file will be substituted for the argument %1.

Verbs

Many applications can perform operations against your file; print it, for example.  In the example above, the verb is open, which simply runs Notepad and loads your file so that you can edit it. 

If you'd requested the verb print, Notepad would load and print your file for you.  This is potentially quite useful, and you can find out what verbs are available by examining the registry entries for the application of interest.

You can often view the possible verbs for a given file type by right-clicking on the file in Windows Explorer.

Client/Server issues

No issues; this API will behave as if it were running locally on the client.  You must specify the location of the target file on the server machine, not the client. 

File caching

GUI ScreenIO saves some files in a cache directory on the client computer; the default location is:

C:\Windows\Temp_GUI_ScreenIO_Cache

GUI ScreenIO will transfer the file from the server to the client's cache, and then play the cached file. 

Files

Files available to copy to your system:

Usage

     COPY WIN32API.
     COPY SHELLEXE.


     
* ------------------------: Call the API.
*
     SET FUNC-SHELLEXECUTE TO TRUE.

     MOVE LOW-VALUES TO

     CALL 'GSWINAPI' USING WIN32API-PARMS
                           SHELLEXE-CMDSHOW
                           SHELLEXE-FILETYPEID
                           SHELLEXE-VERB
                           SHELLEXE-FILE-URL
                           SHELLEXE-ARGUMENTS
                           WIN32API-F.

Parameters specific to this function

SHELLEXE-CMDSHOW

This value determines the show state of the new application that you launched.  Set the desired value to TRUE:

     SET SE-SW-SHOWNORMAL TO TRUE.

Value Description
SE-SW-SHOWNORMAL Launch and display the new application.
SE-SW-HIDE Launches the new application but hides it. 

CAUTION: A hidden window does NOT show in the taskbar, so you should AVOID using this setting.

SE-SW-SHOWMINIMIZED Launches the application and displays it as a minimized window.
SE-SW-SHOWMAXIMIZED Launches the application and displays it as a maximized window.
SE-SW-SHOWNOACTIVATE Same as SHOWNORMAL except the window is not activated.
SE-SW-SHOWMINNOACTIVE This value is similar to SHOWMINIMIZED,except the window is not activated.
SE.....WAIT There is one of these for each of the above CMDSHOW options.

See the comments in the copybook.  These options cause your GUI ScreenIO application to wait for the invoked application to exit before returning to your program.

SHELLEXE-FILETYPEID

File type identifier for the application to be launched. 

If this contains spaces or LOW-VALUEs, the default application is launched. 

If the file type is associated with more than one application, and you do not want to use the default application, specify the file type identifier for the desired application here.  See the registry to find the file type identifier for the desired application, as discussed above.

This field is filled in upon return, so be sure to initialize it each time you call this API.  For instance, calling the API with a text file one time, and a zip file the next time without re-setting this file may yield undesirable results.

SHELLEXE-VERB

Operation that the application is to perform against the file specified file or URL.  Commonly encountered verbs are:

The implementation of verbs is platform and application-specific.  Inspect the application's registry entries as discussed above to see which verbs are supported.

SHELLEXE-FILE-URL

Filespec or URL of the file to launch; up to 1024 bytes.  If you supply a URL, the default browser will be launched.

SHELLEXE-ARGUMENTS

Six values (255 bytes each) which will be passed to the application.

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all Calls to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success.

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

* ------------------------: If function failed,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.  If it worked, this will contain the command string that was passed to WinExec.

WIN32API-A through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function.  These are not used, but must be present because this CALL requires seven arguments.


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom