Run DLL action
The Run DLL action calls an entry point in your extension DLL. The entry point must be defined as per the fTixCustomFunc prototype. You can define more than one entry point in your DLL and then call them through different Run DLL actions. You can also call the same entry point multiple times through different Run DLL actions, with the same or different arguments.
The entry point receives a pointer to the Setup runtime engine interface that you can use to communicate with the Setup process, plus an array of zero or more arguments. These arguments are similar to the traditional main arguments in C and C++ programs: they consist of 0-terminated strings that are parsed from the action's attributes (see Arguments, below).
The function must return ERROR_SUCCESS (0, zero) if successful, or a nonzero error code if a failure occurred. Typically, you would return a Win32-style error code if the function encounters a problem. The LastExitCode variable is set to the function's return value; nonzero values may cause the parent action sequence or the entire installation to be aborted (this is subject to the global Error handling options on the Installer options project page).
Note: Using this function requires that you include an extension DLL on the Installer options project page.
Exit codes
The installer stores the DLL function's return value in the LastExitCode variable; you can use this variable in the conditions of subsequent actions. The exit code is one of the following:
- If an error occurs before the function is called, LastExitCode is set to the (nonzero) Windows error code.
- Else the return value of the function itself is stored.
Note: LastExitCode is overwritten by the next action that runs an external program (including Run Script, Run DLL, Run Program, and Uninstall Product).
Attributes
The following attributes and options are available.
| Attribute | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Action name | Enter the name of the action. This name is only used in InstallMate and is not visible to the user. | ||||||||
| Display text | Enter the localizable description of the action. This description is displayed in progress messages in the installer while the action is executing. | ||||||||
| Localized | Check this box to localize the Display text field and use different descriptions for different languages. | ||||||||
| Function name | Enter the name of the DLL entry point that must be called. You should enter the name as it appears in your source code (for example, MyCustomFunc as shown above); the installer will add the required name decorations before it tries to locate the entry point in the extension DLL. | ||||||||
| Arguments | Enter the arguments for the program. Be sure to enclose any arguments that contain (or might expand to contain) spaces in quotes, for example "argument with spaces" or "<INSTALLDIR>". The installer will expand any symbolic references and break the argument string into separate arguments before calling the DLL function, similar to the way Windows parses command line arguments before calling the main entry point in a traditional C or C++ program. |
||||||||
| Do not log arguments | Check this box to prevent the Arguments from being logged in the installer's log file; clear it to write the arguments to the log file when the action is executed. This option is mainly useful if the Arguments field contains sensitive information such as an embedded password. | ||||||||
| Execute | Select the action's execution mode from the drop-down list. The following choices are available:
|
||||||||
| Prompt | Check this box and enter the localizable prompt text to have InstallMate prompt the user before the action is run; clear it to run the action without prompting. If you use this option, then the prompt is displayed in a dialog box with (localized versions of) Yes and No buttons. The action is executed if the user clicks Yes and skipped if No is clicked. You should phrase your prompt accordingly. |
||||||||
| Localized | Check this box to localize the Prompt field and use different prompts for different languages. | ||||||||
| CPU | Select the Windows architectures on which the action must be executed. This CPU selection acts as an additional condition for the action. | ||||||||
| Condition | Enter the conditional expression that determines if the action will be executed, or leave empty for unconditional execution. | ||||||||
| Disabled | Check this box to disable the action. A disabled action is not included in the installer and not checked during the build. You can use this option to remove actions temporarily from your installer without permanently deleting them. Disabled actions are shown with a grayed-out icon. |