Registry Mnemonics

From CometWiki

Latest revision as of 19:19, 8 November 2011

Using the Windows Registry in your IB Programs

Introduction:

The Registry Mnemonics allow you to create and manage Windows registry settings for your IB application. Entries may be made under either HKEY_CURRENT_USER\Software or HKEY_LOCAL_MACHINE\Software.

Syntax:

Print (RegCreateKey = Type$, BaseKey$, SubKey$, 0) Creates a new registry entry.

Print (RegDeleteKey = Type$, BaseKey$, SubKey$) Deletes a registry entry and all of its name/value pairs.

Print (RegSetValue = Type$, BaseKey$, Name$, Value$, Type) Assigns the specified Name/Value pair of a given type.

Print (RegGetValue = Type$, BaseKey$, Name$) Returns the the Type and Value of the specified Name/Value pair.

Print (RegDeleteValue = Type$, BaseKey$, Name$) Deletes the specified Name/Value pair.

Discussion:

For all functions: Type$ = "USER" or "SYSTEM" where "USER" translates as HKCU\Software; "SYSTEM" translates as HKLM\Software. BaseKey$ = an EXISTING registry key which may contain "\" for subkeys, For example: "MyCompanyName\MyAppName". After each PRINT an INPUT must be done to determine the success of failure of the call. The string returned will be either "+OK" or "-ERR" followed by more information.

Example: Here's an example of how to store a Comet directory name choice for a particular user:

Length 254 & Local RegKey$
Length 30 & Local User$
Length 3 & Local UserDir$
SET STARTUPBASEKEY$ = "MyCompanyName\MyAppName\Settings"
SET USERDIR$ = "UserDir"

Note that each key level of the entry must be created individually, thus it requires 4 PRINTS to create the final key HKCU\Software\MyCompanyName\MyAppName\Settings\Username:

print (RegCreateKey="USER","","MyCompanyName",0)
input Result$
print (RegCreateKey="USER","MyCompanyName","MyAppName",0)
input Result$
print (RegCreateKey="USER","MyCompanyName\MyAppName","Settings",0)
input Result$
print (RegCreateKey="USER",STARTUPBASEKEY$,User$,0)
input Result$

Here's how to test the result of the call:

if strip(Result$) ne "+OK" GoTo RegError

(NOTE: The fourth parameter to the (RegCreateKey=) is RFU. For now it must always be 0).

Here's the code to set the value of the User's directory choice:

RegKey$ = STARTUPBASEKEY$ + "\" + User$
print (RegSetValue = "USER", RegKey$, USERDIR$,UserDir$,1)
input Result$

The fourth parameter to (RegSetValue=) specifies the type of data being stored: 0: DWORD 1: string (this is used in the above example)

Here's the code to retrieve the setting:

RegKey$ = STARTUPBASEKEY$ + "\" + User$
print (RegGetValue = "USER", RegKey$, USERDIR$)
input Result$

(RegGetValue) returns some additional information along with "+OK" which identifies the data type of the value. "+OK 1:" indicates a string. If instead of 1 it was 0 this indicates a DWORD.

if sub(Result$,1,6) = "+OK 1:" GoTo RegSettingOK

Here's how to delete just the entry that stores the directory choice for the user:

RegKey$ = STARTUPBASEKEY$ + "\" + User$
print (RegDeleteValue = "USER", RegKey$, USERDIR$)
input Result$

Here's how to delete the user's entry and all of its associated name/value pairs:

print (RegDeleteKey = "USER", STARTUPBASEKEY$ ,User$)
input Result$

The Registry Mnemonics were introduced in Comet16/32 2011.