INI Value
An INI Value object represents a value in a Windows .ini file for installation or removal. You can add or remove entire values, or you can append or prepend partial values. INI values are identified by their name, their file section, and the actual file in which they appear, for example, the file <WindowsFolder>\MySettings.ini might contain the following:
[Section name] Value name=Value
Installation or removal of an INI value is controlled by its component. If the component is installed, the INI value's Install action is executed (which may actually remove the value); if the component is removed, the Remove action is executed. If an INI value is not linked to a component, its Install action is executed during installation of your product, and its Remove action when the product is removed.
Attributes
The following attributes and options are available.
| Attribute | Description |
|---|---|
| Name | Enter the name of the INI value. This name may not start or end with spaces or tabs, and may not contain the '=' character. You may use symbolic references in the name; they will be resolved when the INI value is installed. Note: You can use the special name * (a single asterisk) to make the installer remove the entire INI file section that you specify in the Section field. In order to do so, you must either leave the Value field empty or specify Remove completely for either Install action or Remove action, or both. If you use this feature and the enclosing section is removed, then the entire INI file will also be removed if it is now empty. |
| Value | Enter the value for the INI value. You may use symbolic references in the value; they will be resolved when the INI value is installed. Note: You can use the special value ~ (a single tilde) to make the installer create an empty value. |
| Section | Enter the name of the section in the INI file. You may use symbolic references in the name; they will be resolved when the INI value is installed. |
| INI file | Enter the path to the INI file. For compatibility with Windows Installer, this path must have the format <folder_alias>\file_name. |
| Alias | Enter the alias for the INI value. This alias must be unique in the project. (InstallMate does not currently use the alias, but this may change in future releases.) |
| Install action | Select the desired installation action from the drop-down list. The installation action is executed when the INI value's component is installed. If the INI value is not linked to a component, the action is executed when the product as a whole is installed. See Installation actions below for the full list of actions. |
| Remove action | Select the desired removal action from the drop-down list. The removal action is executed when the INI value's component is removed. If the INI value is not linked to a component, the action is executed when the product as a whole is removed. See Removal actions below for the full list of actions. |
| Keep during updates | Check this box to keep the INI value during updates, i.e., when the uninstaller is run in upgrade mode (TsuUpgrade is nonzero). If this box is checked, the Remove action is ignored during upgrades (only) and the INI value will remain on the target system. This option is useful if the INI value contains data that must be retained during upgrades of the product, but should be removed during full product uninstallations. |
| Separator | Enter the separator character that is used for Append or Prepend installation actions. The default character is a semicolon ';', which is commonly used to separate paths in a path list, but you may choose any character that your application requires. If you leave this field blank, the new value is added to the existing value without separator. |
Installation actions
The installer can create, modify, or remove the INI value during product installation.
Note: As a side effect, removal of a value may lead to removal of its section and file if the section or file are empty after the value is removed.
| Install action | InstallMate |
|---|---|
Do not install |
The INI value is not installed. If it is already present on the target system, its value is left unchanged. |
| Install if not present | The INI value is only installed if it does not already exist. If it is already present on the target system, its value is left unchanged. |
| Install if present | The INI value is only installed if it already exists. In that case, the existing value is replaced by the new value. |
| Prepend to existing value | The INI value is installed. If it already exists, the new value is prepended to the existing value and the optional separator is inserted between the newly added portion and the existing value. If the value did not exist, it is created and set to the new value. The separator is not used in that case. Note: If the new value already appears in the INI value, it is not added again. This is done to prevent duplicates of folders paths etc. in values that contain lists of values. |
| Append to existing value | The INI value is installed. If it already exists, the new value is appended to the existing value and the optional separator is inserted between the the existing value and the newly added portion. If the value did not exist, it is created and set to the new value. The separator is not used in that case. Note: If the new value already appears in the INI value, it is not added again. This is done to prevent duplicates of folders paths etc. in values that contain lists of values. |
| Overwrite existing value | The INI value is installed and the existing value, if any, is replaced by the new value. |
| Remove partial value | If the INI value exists, the portion specified by its new value is removed from the existing value along with the optional separator character. If the resulting value is empty, the INI value is removed altogether. |
| Remove if matched | If the INI value exists, it is removed if, and only if, its existing value matches the specified value. |
| Remove completely | If the INI value exists, it is removed in its entirety. |
Removal actions
The installer can modify, remove, or retain the INI value during product removal.
Note: As a side effect, removal of a value may lead to removal of its section and file if the section or file are empty after the value is removed.
| Remove action | InstallMate |
|---|---|
| Do not remove | The INI value is left as-is. |
| Remove partial value | If the INI value exists, the portion specified by its new value is removed from the existing value along with the optional separator character. If the resulting value is empty, the INI value is removed altogether. |
| Remove if matched | If the INI value exists it is removed if, and only if, its existing value matches the specified value. |
| Remove completely | If the INI value exists, it is removed in its entirety. |
| Restore original | The INI value is restored to the value it had before the first installation action. If that value was empty or did not exist at that time, the INI value is removed in its entirety. |