The registry is a database where Windows and applications store various settings and other data of small size. Macros also can store their settings there.
int rset(data [name] [key] [hive] [options|datatype]) int rget(variable [name] [key] [hive] [default] [datatype])
data - data to be stored in the registry. Can be variable or other expression.
variable - variable that receives data stored in the registry.
name - registry value name. String. Default: variable name (should be in simplest form - without .'()[] ). If data is not variable, name is required. Use "" for "(Default)".
key - registry key. String. Must not begin with "HKEY_CURRENT_USER\" or similar. Default (or ""): "Software\GinDi\QM2\User". If begins with \, it is interpreted as subkey of default key. Also can be an open key handle (QM 2.3.0).
hive - one of HKEY_... constants. Integer. Default (or 0): HKEY_CURRENT_USER.
default - default value to be used if the value does not exist in the registry. Default: "" for strings, 0 for numeric variables. Cannot be used with user-defined types.
options - one of the following values. Default: 0.
| -1 | delete value. data is not used and can be 0 or "". |
| -2 | delete subkey. data is not used and can be 0 or "". name must be subkey name (without path). key must be parent key. |
| -3 | delete subkey, but only if it does not contain subkeys. |
| -4 (QM 2.2.0) | delete subkey, but only if it is empty (does not contain subkeys and values). |
datatype - registry data type. Can be used only with strings. Default: REG_SZ. Can be one of REG_... constants that are defined in WinConstants function.
rset writes data to the registry. If the specified key does not exist, creates it.
rget reads data from the registry and stores it into the variable.
Each of these functions returns a nonzero value on success. For strings, it is string length+1. For data of other type, it is registry data length. If fails (e.g., key or value does not exist, access denied, etc), returns 0. You can get error description using str.dllerror (QM 2.2.0).
Warning: You should not use rset if you are not sure that this will not damage something. You can safely use rget. It is quite safe to use rset if key is omitted, "", or begins with \, because then you deal only with the key dedicated for QM macros.
Hive HKEY_CURRENT_USER (default) is used for current user's settings. Other hives are used for settings common to all users.
For security reasons, rset usually cannot write to common hives (hives other than HKEY_CURRENT_USER) on non-administrator user accounts. On Windows Vista, it fails to write to these hives even on the administrator account if QM is running not as administrator.
Registry data format:
| expression/variable type | registry data format |
| str, lpstr | REG_SZ or datatype |
| int, byte, word | REG_DWORD |
| other | REG_BINARY |
QM 2.3.0. If variable is a str variable, and datatype is REG_SZ or 0 or omitted, rget succeeds even if data type in registry is not of REG_SZ type. REG_EXPAND_SZ strings are automatically expanded. REG_MULTI_SZ strings are correctly retrieved too. REG_DWORD and REG_QWORD values are converted to string. Data of other nonstring types is copied to the str variable unmodified. In older QM versions, rget would fail if registry data type is not a string type. String types are REG_SZ, REG_MULTI_SZ and REG_EXPAND_SZ.
If variable is a str variable, and datatype other than 0 or REG_SZ is specified, rget fails if data type of the value in the registry is other. With variables of other types, data type in the registry must mach too.
Variables of composite types except str cannot be used. These are ARRAY, BSTR, VARIANT, interface pointer, and structures containing these types or str. With rget, pointers and lpstr also cannot be used. Structures containing str can be used if you convert them from/to string. See str.getstruct/str.setstruct.
retrieves value "Logon User Name" from HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer str s if(rget(s "Logon User Name" "Software\Microsoft\Windows\CurrentVersion\Explorer")) out s else out "the value or the key does not exist" retrieves the default value from HKEY_CLASSES_ROOT\mp3file\shell\play\command str s if(rget(s "" "mp3file\shell\play\command" HKEY_CLASSES_ROOT)) out s sets value "test" in HKEY_CURRENT_USER\software\gindi\qm2\user\MyFunctionSettings str s="data" rset s "test" "\MyFunctionSettings" retrieves value "test" from HKEY_CURRENT_USER\software\gindi\qm2\user\MyFunctionSettings str s rget s "test" "\MyFunctionSettings" out s sets value "test" in HKEY_CURRENT_USER\software\gindi\qm2\user int test = 100 rset test retrieves value "test" from HKEY_CURRENT_USER\software\gindi\qm2\user int test2 rget test2 "test" out test2 deletes value "test" in HKEY_CURRENT_USER\software\gindi\qm2\user\MyFunctionSettings rset "" "test" "\MyFunctionSettings" 0 -1 deletes key "MyFunctionSettings" in HKEY_CURRENT_USER\software\gindi\qm2\user rset "" "MyFunctionSettings" "" 0 -2
Ini files can be used to store settings. However it is not recommended because is too limited. No Unicode, not all characters allowed, no hierarchy, etc. To store small-size settings, instead use the registry. For bigger-size settings and other data, or if you want to share it, you can use XML or CSV.
int rset(data [name] [section] [inifile] [options]) int rget(variable [name] [section] [inifile] [default])
data - data to be stored in the ini file. Can be variable or other expression.
variable - variable that receives data stored in the ini file.
name - ini value name (also called key). Everything other is the same as with the registry.
section - ini section name. In ini files section names are in [ ]. Default: "QM".
inifile - ini file. Default: "$my qm$\User.ini.
default - default value to be used if the value does not exist. Everything other is the same as with the registry.
options - one of the following values. Default: 0.
| -1 | delete value. data is not used and can be "". |
| -2 | delete section. data and name are not used and can be "". |
If 4-th argument of rset/rget is string, is used a .ini file instead of the registry.
rset writes data to the ini file. If the file or section does not exist, creates.
rget reads data from the ini file and stores it into the variable.
Each of these functions returns 1 on success, 0 on failure. If rset failed, you can get error description using str.dllerror.
Write to ini file: rset "data" "a" "section" "$desktop$\test.ini"