GUI ScreenIO for Windows

 ScreenIO.com


WinExec

This API lets you launch an executable from your application.

Application notes

WinExec normally launches programs asynchronously; that is, control returns immediately to your application without waiting for the launched program to finish.

We optionally also a synchronous option, which will freeze your GUI ScreenIO application till the launched program exits.

If your application needs to wait until the launched application has terminated, you normally must figure some way to determine that; such as creating a file with completion information that your application can examine.  If you select the -WAIT option (see WINEXEC-CMDSHOW below), GUI ScreenIO will not return to your application until the invoked application exits, at which time it will return the return-code of that application.  GUI ScreenIO can not update its screen during this time, and will remain unresponsive.  You may wish to cause your application to Minimize during this interval if the invoked task takes more than a few seconds.

Windows searches for the executable in this sequence:

  1. The directory from which the application loaded
  2. The current directory
  3. The Windows system directory
  4. The Windows directory
  5. The directories in the PATH environment variable

Its important t point out here that WinExec expects to launch a WINDOWS task.  If you can type your intended command into the dialog box that appears when you click Start / Run, and have it work, then it will work in your application using this API.

However, if the task you expect to run is a DOS command, you will have to launch a command.com or cmd.exe shell with the DOS command as an argument.

Example:

You want to delete a file from the hard drive.  You might expect to code "DEL C:\filename.ext" in the WINEXEC-COMMAND-LINE.  But this would fail because DEL is not a windows command.  (It won't work in Start/Run).

The proper way do to this is to pass this command to a command shell as follows:

     STRING "COMMAND.COM /C DEL C:\filename.ext"  DELIMITED SIZE INTO WINEXEC-COMMAND-LINE.

The /C argument in the above example tells command com to exit after running this single command.

Note that command.com exists in all versions of windows, but it is not the default command processor for Windows 2000 or Windows XP, and its behavior differs somewhat from release to release.   You may also invoke cmd.exe instead of command.com if the platform is Windows 2000 or Windows XP, but this will fail on Win9x platforms. See GetVersionEx to determine platform.

Client/Server issues

If running in client/server mode, this API will run the program on client. 

To run the program on the server:

     SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE

Files available to copy to your system:

Usage

     COPY WIN32API.
     COPY WINEXEC.


     
* ------------------------: Call the API.
*
     SET API-WINEXEC TO TRUE.

     CALL 'GSWINAPI' USING WIN32API-PARMS
                           WINEXEC-COMMAND-LINE
                           WINEXEC-CMDSHOW
                           WIN32API-C
                           WIN32API-D
                           WIN32API-E
                           WIN32API-F.

Parameters specific to this function

WINEXEC-COMMAND-LINE

Filespec of the .EXE file to launch; up to 1024 bytes.

WINEXEC-CMDSHOW

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

     SET SW-SHOWNORMAL TO TRUE.

Flag Description
SW-SHOWNORMAL Launch and display the new application.
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.

SW-SHOWMINIMIZED Launches the application and displays it as a minimized window.
SW-SHOWMAXIMIZED Launches the application and displays it as a maximized window.
SW-SHOWNOACTIVATE Same as SHOWNORMAL except the window is not activated.
SW-SHOWMINNOACTIVE This value is similar to SHOWMINIMIZED,except the window is not activated.
SW-.....-WAIT For each of the above values in this table, the -WAIT option will cause GUI ScreenIO to wait till the invoked task exits before returning to your program.

  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.

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