LaunchExecutableEx

int LaunchExecutableEx (char filename[], int windowState, int *handle);

Purpose

Performs the same operation as LaunchExecutable with the following extended features:

  • Under Windows, you can specify how the Windows application displays.
  • LaunchExecutableEx returns a handle to the executable that can show whether the executable is still running and that you can use to terminate the executable.
Note   If you want to wait for the program to exit, use the systemsystem function in the ANSI C Library.

When you launch several processes with LaunchExecutableEx but do not call RetireExecutableHandle on them, you might reach the limit for the maximum number of processes the system imposes. This happens even if the processes terminate; the program does not recognize that the processes have terminated until you call RetireExecutableHandle.

Parameters

Input
Name Type Description
filename char [] Pathname of executable file to run.

If the program is not in one of the directories specified in the PATH environment variable, you must specify the full path. The path can include arguments to pass to the program.

If the program is a .pif, .bat, or .com file, you must include the extension in the pathname. For example, under Windows, the following function call launches the Edit program with the file file.dat:

LaunchExecutableEx ("edit.com c:\\file.dat");
windowState int Specifies how to show a Windows program.

(Linux) This parameter is ignored.

The following table shows valid values for windowState.

Value Application window behavior
LE_HIDE Hidden
LE_SHOWNORMAL Shown normally and activated
LE_SHOWMINIMIZED Displayed as an icon and activated
LE_SHOWMAXIMIZED Displayed as a maximized window and activated
LE_SHOWNA Shown normally but not activated
LE_SHOWMINNOACTIVE Shown as an icon but not activated
Output
Name Type Description
handle int Handle that represents the executable launched.

You can pass the handle to ExecutableHasTerminated and TerminateExecutable.

When you no longer need the handle, call RetireExecutableHandle.

If you do not want to obtain a handle, you can pass NULL.

Return Value

Name Type Description
result int Result of the operation.

Error codes vary, depending on whether you have a Windows or Linux application.

Windows Error Codes
Code Description
0 Command was successfully started.
-1 System was out of memory, executable file was corrupt, or relocations were invalid.
-2 A DLL required by the executable cannot be found.
-3 File was not found.
-4 Path was not found.
-6 Attempt was made to dynamically link to a task, or there was a sharing or network-protection error.
-7 Library required separate data segments for each task.
-9 There was insufficient memory to start the application.
-11 Windows version was incorrect.
-12 Executable file was invalid. Either it was not a Windows application or there was an error in the .exe image.
-13 The directory name is invalid.
-14 Application was designed for MS-DOS 4.0.
-15 Type of executable file was unknown.
-16 You made an attempt to load a real-mode application developed for an earlier version of Windows.
-17 You made an attempt to load a second instance of an executable file that contains multiple data segments that were not marked read only.
-19 The operating system returned an unknown error code.
-20 Attempt was made to load a compressed executable file. You must decompress the file before you can load it.
-21 DLL file was invalid. One of the DLLs required to run this application was corrupt.
-22 Application requires Windows 32-bit extensions.
-216 The bitness of the application is incompatible with this operating system.
Linux Error Codes
0 Command successfully started.
-1 Launching the executable would exceed the operating system limit on the total number of processes under execution or the total number of processes per user.
-2 Insufficient swap space for the new process.
-3 vfork failed for unknown reason.
-4 Search permission is denied for a directory listed in the path prefix of the new process image file, the new process image file denies execution permission, or the new process image file is not a regular file.
-5 The length of the pathname of filename or an element of the environment variable PATH prefixed to a filename exceeds PATH_MAX, or a pathname component is longer than NAME_MAX while _POSIX_NO_TRUNC is in effect for that file. Refer to the man page for pathconf(2V).
-6 One or more components of the pathname of the new process image file do not exist.
-7 A component of the path prefix of the new process image file is not a directory.
-8 Number of bytes that the new process-image-argument list and the environment list use is greater than ARG_MAX bytes. Refer to the man page for sysconf(2V).
-9 New process image file has the appropriate access permission but is not in the proper format.

Additional Information

Library: Utility Library

Include file: utility.h

LabWindows/CVI compatibility: LabWindows/CVI 3.0 and later

Examples

Refer to the following examples that use the LaunchExecutableEx function:

  • udp\DNSResolver.cws

    Open example
  • utility\launchexe.cws

    Open example

WAS THIS ARTICLE HELPFUL?

Not Helpful