Registry Value
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
The following attributes and options are available.
| Attribute | Description |
|---|---|
| Value 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. Tip 1: To install the unnamed default registry value for the parent key, leave the Name field empty. If you leave the Name field empty, InstallMate will display it as (Default) in the list view just like Registry Editor does, but will use an empty name during installation. Do not attempt to create your own (Default) registry value by entering (Default) in the Name field; this will install a named registry value that may look the same in Registry Editor, but is a completely different value than the unnamed value displayed as (Default). Tip 2: If Value name ends with %# or %? and you have set Install action: Install if not present, the installer will replace the %# or %? portion by a 1-based numerical suffix to ensure that the value name is unique within the parent key:
|
| Value alias | Enter the alias for the registry key. This alias must be unique in the project. |
| 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. |
| 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. |
| Localized | Check this box to localize the Data field and use different data for different languages. |
| 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. |
| 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. |
| 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 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. Tip: In conjunction with value names that end in %# or %? (see the description of Value name, above), this install action will cause the installer to generate a unique registry value name that is not currently present in the parent key. |
| 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. |