A.3.5.3 Executing an External Program

The GUI INF script language provides two commands that enable you to execute another program from an INF script. From a shell or install section, you can use the RunProgram and StartDetachedProcess commands to start another program, and you can use the WaitOnEvent and SignalEvent commands to synchronize execution between the INF script and a program started by StartDetachedProcess.

RunProgram Command

The RunProgram command executes the specified program and stores the program’s exit code under the ExitCode variable. To the INF script, it appears that the program is executed synchronously, because execution of the INF script waits for the program to terminate. Internally, however, the Setup program executes the program asynchronously and then uses a loop to wait for the program’s termination while yielding periodically to handle messages. This enables the Setup program to be responsive to user interactions during the wait. The syntax of this command is:

RunProgram ExitCode DiskName Reserved ProgramPath [Args]*

ExitCode

Receives the exit code of the process, if the process is successfully started. Otherwise, receives the string, “ERROR”.

DiskName

String to prompt the user to insert a disk. This string is used only if ProgramPath indicates that the specified file is on a floppy disk (for example, a:\mysetup.exe) and the file is not found on the disk that is present.

Reserved

Ignored; should be ““.

Args

Zero or more argument strings.

For example:

RunProgram ExitCode "Setup Disk #1"  "" a:\setupprg.exe
 

StartDetachedProcess Command

The StartDetachedProcess command executes the specified program asynchronously, using the CreateProcess function of the Win32 API (with the DETACHED_PROCESS flag). Execution of the INF script continues without waiting for the process to terminate. The syntax of the command is:

StartDetachedProcess ExitCode DiskName Reserved ProgramPath [Args]*

ExitCode

Receives the exit code of the process, if the process is successfully started. Otherwise, receives the string “ERROR”.

DiskName

String to prompt the user to insert a disk. This string is used only if ProgramPath indicates that the specified file is on a floppy disk (for example, a:\mysetup.exe) and the file is not found on the disk that is present.

Reserved

Ignored; should be ““.

ProgramPath

A full or partial path specifying the file to be executed.

Args

Zero or more argument strings.

For example:

StartDetachedProcess Success "Setup Disk #1" "" a:\setupprg.exe
 

WaitOnEvent Command

The WaitOnEvent command opens a handle to the specified event object. It then waits for either the object’s state to be signaled or the timeout interval to elapse. This command blocks the execution of the INF script, but, internally, the Setup program uses a loop to wait for the event to be signaled while yielding periodically to handle messages. This enables the Setup program to be responsive to user interactions during the wait.

This command is useful in coordinating execution of the INF script with an external program started by the StartDetachedProcess command. If the first character of the EventName string is an asterisk (*), a variation of the WaitOnEvent operation is performed. In this case, the detached process can signal either the named event or an event named \\SETUP_FAILED. It signals the EventName event to indicate success, and signals the \\SETUP_FAILED event to indicate that the process failed and an error popup has already been presented to the user.

Note that the Setup program does not create the EventName event if it does not exist. This means that you must allow time for the detached process to create the event. The syntax of the command is:

WaitOnEvent Result EventName Timeout

Result

Receives one of the following strings:

“EventSet” - The EventName event was signaled.

“EventNotFound” - No event object exists with the specified name.

“EventTimeout” - The timeout interval elapsed before the event was signaled.

“EventFailed” - The \\SETUP_FAILED event was signaled.

EventName

Specifies the name of the event object to wait on. If the first character of the string is ‘*’, the name consists of the characters following the ‘*’.

Timeout

Specifies the timeout interval in milliseconds. If zero is specified, the wait is indefinite.

SignalEvent Command

The SignalEvent command opens a handle to the specified event object, and sets its state to signaled. The Setup program does not create the EventName event if it does not exist. The syntax of the command is:

SignalEvent Result EventName

Result

Receives one of the following strings:

“EventSignaled” - The event’s state was set to signaled.

“EventNotSet” - The event’s state could not be set to signaled.

“EventNotFound” - No event object exists with the specified name.

EventName

Specifies the name of the event object to be signaled.