Windows Installer requires that all registry values are linked to components;
Tarma ExpertInstall will issue a BLD:E0072
diagnostic message if this is not the case.| Reference information | |
|---|---|
| Project page | Registry Keys and Values |
| Related topics | Working with attribute panes |
A Registry Value object represents a registry value for installation or removal. You can add or remove entire values, or you can append or prepend partial values.
Installation or removal of a registry value is controlled by its component. If the component is installed, the registry value's Install action is executed (which may actually remove the value); if the component is removed, the Remove action is executed. If a registry 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.
Windows Installer requires that all registry values are linked to components;
Tarma ExpertInstall will issue a BLD:E0072
diagnostic message if this is not the case.
The installer can create, modify, or remove registry values during product installation. The effect of the actions differs somewhat between Tarma Installer and Windows Installer, because Windows Installer does not support the full complement of installation actions.
Note: As a side effect, removal of a value may lead to removal of its parent key if the key is empty after the value is removed. This in turn may lead to removal of the grandparent key, etc.
| Install action | Tarma Installer | Windows Installer |
|---|---|---|
|
Do not install |
The registry value is not installed. If it is already present on the target system, its value is left unchanged. | Same |
| Install if not present | The registry value is only installed if it does not already exist. If it is already present on the target system, its value is left unchanged. | Not supported. Behaves as Overwrite existing value. |
| Install if present | The registry 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 registry 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 variable did not exist, it is created and set to the new value. The separator is not used in that case. Prepend to existing value works for REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ, and REG_BINARY data. |
Same, except that only REG_MULTI_SZ data can be appended or prepended. |
| Append to existing value |
The registry 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 variable did not exist, it is created and set to the new value. The separator is not used in that case. Append to existing value works for REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ, and REG_BINARY data. |
|
| Overwrite existing value | The registry value is installed and the existing value, if any, is replaced by the new value. | Same |
| Remove partial value | If the registry 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 registry value is removed altogether. | Not supported. Behaves as Remove completely. |
| Remove if matched | If the registry value exists, it is removed if, and only if, its existing value matches the new value. | |
| Remove completely | If the registry value exists, it is removed in its entirety. | Same |
The installer can modify, remove, or retain registry values during product removal. The effect of the actions differs somewhat between Tarma Installer and Windows Installer, because Windows Installer does not support the full complement of removal actions.
Note: As a side effect, removal of a value may lead to removal of its parent key if the key is empty after the value is removed. This in turn may lead to removal of the grandparent key, etc.
| Remove action | Tarma Installer | Windows Installer |
|---|---|---|
| Do not remove | The registry value is left as-is. | Not supported; all installed registry values are automatically removed. |
| Remove partial value | If the registry 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 registry value is removed altogether. |
All removal actions depend on the installation action. If the installation action specified Prepend or Append, the partial value is removed; else the entire value is removed. If the resulting value is empty, it is removed altogether. |
| Remove if matched | If the registry value exists it is removed if, and only if, its existing value matches the new value. | |
| Remove completely | If the registry value exists, it is removed in its entirety. | |
| Restore original | The registry 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 registry value is removed in its entirety. | Not supported. Behaves as the other removal actions. |
The following registry value data types are available (note that not all types are supported for installation and removal):
| Type | Description | Data format |
|---|---|---|
| REG_NONE | Not a valid format; is treated as REG_BINARY. | As REG_BINARY. |
| REG_SZ | Null-terminated text string. | Any text string. |
| REG_EXPAND_SZ | Null-terminated text string with embedded %name references that are resolved as environment variables when the value is retrieved from the registry. | Any text string with embedded %name references. |
| REG_BINARY | Generic binary data. | Binary data formatted as pairs of hexadecimal digits. |
| REG_DWORD | DWORD value (32-bit unsigned integer). | Decimal integer value, or a hexadecimal value if prefixed with 0x (Tarma Installer only). |
| REG_DWORD_BIG_ENDIAN | DWORD value with byte order swapped. |
As REG_DWORD. Tarma Installer will automatically swap the bytes when installing this type.
|
| REG_LINK | (reserved; do not use) | (reserved) |
| REG_MULTI_SZ | Series of null-terminated text strings. | Any series of text strings. Each substring must be on a separate line. |
| REG_RESOURCE_LIST | (reserved; do not use) | (reserved) |
| REG_FULL_RESOURCE_DESCRIPTION | (reserved; do not use) | (reserved) |
| REG_RESOURCE_REQUIREMENTS | (reserved; do not use) | (reserved) |
| REG_QWORD | QWORD value (64-bit unsigned integer). |
Decimal integer value, or a hexadecimal value if prefixed with 0x (Tarma Installer only).
|
This pane contains the following attributes and options.
| Attribute | Description |
|---|---|
| Name | Enter the name of the registry value. You may use symbolic references in the name; they will be resolved when the registry value is installed. |
| Alias | Enter the alias for the registry key. This alias must be unique in the project; it is used as a key in the Windows Installer database. (Tarma Installer does not currently use the alias, but this may change in future releases.) |
| Data |
Enter the value for the registry value. You may use symbolic references in the value; they will be resolved when the registry value is installed. The data format must be as listed in Registry value types (above) after any symbolic references are resolved. |
| Type | Select the desired registry value data type from the drop-down list. See Registry value types above for a list of data types and the corresponding format in the Data field. |
| Install action | Select the desired installation action from the drop-down list. The installation action is executed when the registry value's component is installed. If the registry value is not linked to a component, the action is executed when the product as a whole is installed. See Installation actions above 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 registry value's component is removed. If the registry value is not linked to a component, the action is executed when the product as a whole is removed. See Removal actions above for the full list of actions. |
| 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.
|