Addressing Registry Keys with $setting

Retrieve, add, or change registry keys on Windows platforms.

Retrieve settings:

ReturnedValue = $setting(Registry, RetrieveProfile,"REGKEYS | REGVALUES | REGDATA")

vRegKeys = $setting ("", "HKEY_CURRENT_USER\Software\Uniface\Uniface 9\*", "REGKEYS")
vRegValues = $setting ("", "HKEY_CURRENT_USER\Software\Uniface\Uniface 9\State\MyApp\P" "")

Add or change a setting:

$setting(Registry, Key\SubKey,"REGDATA")=Value

$setting ("", "abcd", "REGDATA") = "Hello"

Parameters

Parameters
Parameter Data Type Description
Registry String
  • Empty string ("")—default source, which is the Registry of the current machine
  • //MachineName—Registry of remote machine
RetrieveProfile String Profile to retrieve the desired section or setting, as defined by Topic (REGKEYS, REGVALUES, or REGDATA). To retrieve multiple sections or settings, you can use the GOLD * and GOLD ? characters. The profile must match the Topic.
Key String Registry key; equivalent to an initialization file section.
Subkey String Registry subkey; equivalent to an initialization setting.
REGDATA String Get or set the registry value. Wildcards are not allowed.
REGVALUES String Get a list of registry values under the specified key. Wildcards are allowed for Setting (in this case, the value) but not for Section (the key).

Each returned item in the list has the form Value=Type). For example, ""=REG_SZ;A=REG_DWORD

REGKEYS String Get a list of subkeys under the specified key. Wildcards can be used for Subkey (in this case, the subkey) but not for Key (the key).

Addressing Registry Keys

On Windows, although the .ini file is usually used for initialization settings, when a Uniface application closes, its state is stored under the key HKEY_CURRENT_USER\Software\Uniface\Uniface Version\State\Application key in the Windows Registry.

Caution: Making changes to the Registry can significantly affect your computer, so use due care when using $setting and deletesetting. Uniface cannot be held responsible for changes you make to your Registry

To address the Registry of the current machine, specify Source as an empty string ("").

If you want to address an alternate registry (for example, for a 32-bit uniface installation running on a 64-bit machine), you can explicitly specify Source as "32" or "64":

$setting("32", "HKEY_LOCAL_MACHINE\SOFTWARE\Setting_32", ....
$setting("64", "HKEY_LOCAL_MACHINE\SOFTWARE\Setting_64", ....

On 32-bit platforms "" is equivalent to "32" and on 64-bit platforms "" is equivalent to "64".

To address the Registry of a remote machine, specify Source as the machine's network name, preceded by two slashes; for example, "\\apollo". (The Remote Registry Service must be running on the remote machine, and accessing the registry of that machine must be allowed by that machine for the current user).

The value of the Setting parameter depends on the Topic.

Registry keys can be fully specified, including the HKEY_ part. If not fully-specified, the key will be relative to HKEY_CURRENT_USER\Software\Uniface\Uniface 9.

Note: When addressing registry keys, you can only use a backslash (\) as a path separator, not a forward slash (/).

The value of the Setting parameter depends on the Topic. When addressing Setting values (using the topic keywords REGVALUES or REGDATA), it is possible to include square brackets in the specification. For example, the following statements are equivalent:

$setting("", "HKEY_LOCAL_MACHINE\SOFTWARE\keyName","REGDATA") = "abc"
$setting("", "[HKEY_LOCAL_MACHINE\SOFTWARE]keyName", "REGDATA") = "abc" 

However, using REGKEYS will cause the error -1118.

Setting Values

To set a registry value set Topic as REGDATA. For example, to modify or add the data value of the registry value "abcd" under the registry key "HKEY_CURRENT_USER\Software\Uniface\" :

$setting ("", "abcd", "REGDATA") = "Hello"
vRegData = $setting("", "HKEY_CURRENT_USER\Software\Uniface\Uniface 10\abcd", "REGDATA")
;vRegData="Hello"

When setting a registry value:

  • If you assign the value of a field, the data type of the field determines the type of the registry value: Numeric becomes REG_DWORD, String becomes REG_SZ, and Raw becomes REG_BINARY.
  • If you assign to a registry value named "", you are assigning to the default value, represented by"(Default)" .
  • If the registry value does not exist, it is added under the registry key; the default type of the new registry value is REG_SZ.
  • If the registry value exists, it is changed; the type remains unchanged.

Retrieving Values

When retrieving a specific value, if the value does not exist, an empty string is returned and $procerrror is -1118. If the value does exist, it is returned as a string and $procerror is 0, even if the setting exists but is empty.

When retrieving a list of values, the returned list is in the form Value1=DataType1;Value2=DataType2. For example:

"windowsize=REG_SZ·;windowpos=REG_SZ"

For example:

  • Retrieve a list of subkeys under a registry key. For example:
    vRegKeys = $setting ("", "HKEY_CURRENT_USER\Software\Uniface\Uniface 10\*", "REGKEYS")
    ;Result: vRegKeys = "History·;PRT_NETWORK·;PRT_NETWORK PRINTER·;State"
  • Retrieve a list of registry values under a registry key. For example:
    vRegValues = $setting ("", "HKEY_CURRENT_USER\Software\Uniface\Uniface 10\State\MyApp\P*", "REGVALUES")
    ;Result: vRegValues = "panelsize=REG_SZ·;panelpos=REG_SZ·;panel=REG_SZ·;panelmin=REG_SZ"
  • Retrieve the contents of a specific registry value. For example:
    vRegData = $setting ("", "[HKEY_CURRENT_USER\Software\Uniface\Uniface 10\State\MyApp]panel", "REGDATA")
    ;Result: vRegData = "on"

Specifying Sections and Settings

Section may be required or optional, depending on the Topic:

  • Required for REGVALUES and REGDATA.
  • Omitted for REGKEYS

If Setting is empty, an error is returned if Topic is REGVALUES or REGDATA.

Specifying Setting returns an error if Topic is REGKEYS.

Adding or Changing a Setting

You can add or modify a setting only if Topic is REGDATA. If the setting does not exist, it is added to the end of the section. If the setting already exists, the value is changed.

To set the value, put the $setting function on the left side of an assignment.

Registry Settings

Return the registry value"(Default)" under the registry key HKEY_CURRENT_USER\Software\Uniface.

vRegValue = $setting ("", "[HKEY_CURRENT_USER\Software\Uniface]", "REGDATA")

Set the value of the registry value "abcd" under the registry key HKEY_CURRENT_USER\Software\Uniface to 15 (type is REG_DWORD).

variables
   numeric vNum
endvariables

vNum = 15
$setting ("", "HKEY_CURRENT_USER/Software/Uniface/abcd", "REGDATA") = vNum 

Return a list of all the subkeys under HKEY_CURRENT_USER\Software\Uniface:

VSettings = $setting ("", "HKEY_CURRENT_USER\Software\Uniface\*", "REGKEYS")