execute

Summary

Launches a file inside the install archive.

Method of

Install object

Syntax

int execute (
   String xpiSourcePath [, Boolean blocking]);

int execute (
   String xpiSourcePath,
   String args [, Boolean blocking]);

Parameters

The execute method has the following parameters:

xpiSourcePath

The pathname of the file to extract and execute. (Note that this path points into the XPI itself.)

args

A parameter string that is passed to the executable. (Ignored on Mac OS). See note below.

blocking

A boolean value that specifies whether the installation should wait for the execution of the file to finish before it resumes. Default is false. See note below. The blocking parameter is not available as part of this method in versions of Netscape before 6.1/Mozilla 0.9.3.

Returns

An integer error code. For a list of possible values, see Return Codes.

Description

The execute method extracts the named file from the XPI file to a temporary file name.

Your code must call the performInstall method to actually execute the file. You can use this method to launch an InstallShield installer or any install executable file stored in a XPI file.

Executing Installed Files

Note: If the file you wish to execute is one you are installing (as opposed to an installer executable that you plan to delete once it runs), then use the execute method on the File object instead. File.execute() executes an installed file (such as a browser) after it has been installed, and is typically placed at the end of an install script and outside of the main install block.

The Install object's execute method, on the other hand, deletes the executable from its temporary location once it has finished. The optional blocking argument, when set to true, specifies that the installation should wait for this executable to finish before processing the next queued install command. If you do not set this flag and launch an executable that is not a part of the installation, you will raise an error when you restart the browser.

Passing Arguments to the Executable

The args parameter, when present, passes a string to the executable as command-line parameters. The following line, for example, passes the "-c" command-line parameter to the executable:

err = file.execute(myfile, "-c", true);

When you want to pass more than one parameter to the executable itself, however, you must format the args string in a particular way so that the parameters can be broken up and passed separately as required. In general, you should use single quotes for the args string and double quotes to delimit the command-line arguments within args. The following parsing rules apply:

• Double quotes are treated as quotes; single quotes are ignored by the executable but legal in the execute() method.
• The outer quotes that frame the args string itself are stripped off when the string is passed to the executable.
• Quotes that are escaped, or "backslashed," are passed through the executable intact. All other backslashed cases are ignored.

This means that in order to pass three command-line arguments (-c, -d, and -s) to the executable, you should format the args string as follows:

err = file.execute(myfile, '"-c""-d""-s"', true);
//Technically, given the rules above, you could also pass the same
//arguments with the following line, but the result is much less
//readable:
err = file.execute(myfile, "\"-c\"\"-d\"\"-s\"", true);

Also see the note about binaries on the Macintosh platform in addFile.