Registry Value attributes
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.
Attributes
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. |
| Data |
Enter the data for the registry value. You may use symbolic references in the data; they will be resolved when the registry value is installed. The data format must be as listed in Registry value types after any symbolic references are resolved. Note: If you specify Increment value for the Install action, then the contents of this field are only used if there is no pre-existing data present for the registry value on the target system. If you specify Decrement value for the Install action, then the contents of the Data field are ignored altogether. |
| Type | Select the desired registry value data type from the drop-down list. See Registry value types 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 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 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 below 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. |
| Keep during updates |
Check this box to keep the registry 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 registry value will remain on the target system. This option is useful if the registry value contains data that must be retained during upgrades of the product, but should be removed during full product uninstallations. |
Installation actions
The installer can create, modify, or remove registry values during product installation.
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 | InstallMate |
|---|---|
|
Do not install |
The registry value is not installed. If it is already present on the target system, its value is left unchanged. |
| 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. |
| 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. Note: If the new value already appears in the registry 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 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. Note: If the new value already appears in the registry 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 registry value is installed and the existing value, if any, is replaced by the new value. |
| 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. |
| 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. |
| Increment value |
If the registry value exists on the target system and its data can be parsed as an unsigned 32-bit integer, then the unsigned integer value is incremented and the incremented value is written back. If the registry value does not exist, cannot be parsed as an unsigned integer, or evaluates to 0 (zero), then the starting value is set to the contents of the Data field parsed as an unsigned integer, or to 0 (zero) if the Data field is empty or does not evaluate to an unsigned integer, and then incremented and written back as before. |
| Decrement value | If the registry value exists on the target system and its data can be parsed as an unsigned 32-bit integer, then the unsigned integer value is decremented and the decremented value is written back if it is > 0. If the registry value does not exist, cannot be parsed as an unsigned integer, or the resulting decremented value would be <= 0, then the registry value is deleted. |
Removal actions
The installer can modify, remove, or retain registry values during product removal.
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 | InstallMate |
|---|---|
| Do not remove | The registry value is left as-is. |
| 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. |
| 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. |
| Increment value |
If the registry value exists on the target system and its data can be parsed as an unsigned 32-bit integer, then the unsigned integer value is incremented and the incremented value is written back. If the registry value does not exist, cannot be parsed as an unsigned integer, or evaluates to 0 (zero), then the starting value is set to the contents of the Data field parsed as an unsigned integer, or to 0 (zero) if the Data field is empty or does not evaluate to an unsigned integer, and then incremented and written back as before. |
| Decrement value | If the registry value exists on the target system and its data can be parsed as an unsigned 32-bit integer, then the unsigned integer value is decremented and the decremented value is written back if it is > 0. If the registry value does not exist, cannot be parsed as an unsigned integer, or the resulting decremented value would be <= 0, then the registry value is deleted. |
Registry value types
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. |
| REG_DWORD_BIG_ENDIAN | DWORD value with byte order swapped. | As REG_DWORD. InstallMate 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. |