Version
1.61
April 11, 2005
Contents
Getting Started 1
Installation. 1
Support..... 1
License..... 1
Change History...... 1
Conversion From 1.0... 3
Registry
Overview 5
Predefined Keys......... 5
The Application Areas........ 5
Why Use the Registry.... 6
Limitations. 6
Usage..... 8
Using the Templates. 8
Multi-DLL Applications 8
Hand-Coded Projects.... 8
INI File
Replacement Functions................. 10
RFL_PutReg (store or delete a value
in an application area of the Registry).. 11
RFL_GetReg (retrieve a value from
an application area of the Registry).. 11
Key
Functions................. 13
OpenKey (open a Registry key for
use).... 13
CreateKey (create a Registry key)............... 14
CloseKey (close a Registry key)............... 15
DeleteKey (delete a Registry key)............... 15
FlushKey (flush a Registry key to
disk).... 16
Value
Functions................. 17
GetValue (read a value from the
Registry).. 17
PutValue (write a value to the
Registry).. 18
DeleteValue (delete a value from
the Registry... 19
Enumeration
Functions................. 20
EnumReg (get contents of key)........ 21
EnumKey (read subkeys by position) 22
EnumValue (read values by position) 23
Import. 24
ImportRegFile (import a RegEdit
export file) 24
Error
Reporting................. 25
RegErrorCode (return internal error
code) 25
RegError (return internal error
message) 25
RegAPIErrorCode (return error code
from API call)............... 25
Error Codes 26
1. Run “RFL161.EXE”
2. The destination folder is initialized to C:\Clarion6.
3. The User’s Guide comes in Word 6.0 and HTML formats. Select the desired format or you can select both.
4. Upon completion start Clarion. Select “Template Registry” from the Setup menu. Two templates are provided to support the ABC template chain (REGFLABC.TPL) and the “Classic” template (REGFL.TPL). Register either or both.
Support is by e-mail and on an “as available basis” only. The newsgroups are not monitored on a regular basis. Visit my web site for the latest FAQ and releases.
jeffnjones@hvc.rr.com
home.hvc.rr.com/jeffnjones
If you are doing extensive registry work, you will need a good registry reference.
The “author” (Jeffrey Jones) grants the user a license to use the Registry Function Library (“RegFunc”). The “author” reserves all rights to “RegFunc”. Specific terms and conditions are detailed below.
“RegFunc” is distributed as “Freeware” on a “as is” basis. The user of “RegFunc” assumes all responsibility in its use.
“RegFunc” can be used in producing software using SoftVelocity’s Clarion 5, Clarion 5.5 and Clarion 6 products. It cannot be used to produce software that is described as a Windows Registry product. In other words, “RegFunc” cannot be used to produce a competitive product.
The install executable (RFL161.EXE) can be freely distributed. Any partial distribution is not allowed except as compiled source distributed in executable form as a non-competing product. “RegFunc” cannot be sold. Indirect fees are allowed. Examples being compilation shareware disks and download web sites.
1. Fixed template error "variable %ExpLineNumber is not defined" when using the legacy template with Clarion 6.1.
Clarion 6 fixes.
1. Renamed GetReg to RFL_GetReg and PutReg to RFL_PutReg due to clash with new C6 functions
2. Equates for Registry Data Types OMITted if Clarion 6.0
3. ImportRegFile was not working for Binary values with continuation characters
1. (Legacy) Fix “Link Error: xxxxxx is unresolved for export” message that occurs when making a DLL where RegFunc that is external declared in another DLL.
1. When using EnumReg and EnumKey on NT/2000, the key name was not returned when the value for the key was not set.
1. Removed use of Windows.Inc file which is not part of Clarion 5.0.
2. Manual has been reorganized to group procedures by their purpose.
3. The explanations for the programkey and scope parameters for GetReg were corrected.
1. EnumReg fills a QUEUE with the name, type, and content of all subkeys and values for a target key.
2. EnumValue returns the name, type, and content of a value in a key by position.
3. EnumKey returns the name and content of a subkey in a key by position.
1. All usage of 16-bit Windows API calls have been removed and replaced with the 32-bit call.
1. The ABC (regflabc.tpl) template would get an error when it was attempting to write entries to the APP’s export file.
1. Remnants from importing the previous value would sometimes be appended to the current value being imported.
1. Use of LIBs has been eliminated. Source code is now provided and compiled with your APP.
2. Same install can be used for all versions of Clarion4 and Clarion5. CW2 is not supported.
1. New check box to specify that the Registry Functions are externally defined in a DLL or LIB. This allows the Registry Functions to be defined in a DLL of a multi-DLL project or to encapsulate the functions with some of your own for the purpose of creating reusable libraries.
1. Default parameter in GETREG was not working. Default value was never returned for missing registry values and keys.
2. GETREG now returns an LONG or STRING depending on the data type of the value in the Registry. For BINARY and STRING values a string is returned. For DWORD values a LONG is returned.
3. When returning a STRING, the value is no longer padded with blanks out to 255 chars.
4. Can now be used to read values from "HKEY_USERS\.Default\Software" by using REG:UserDefault for the scope parameter.
1. Providing an empty value parameter no longer deletes the entry. The entry's value is set to an empty string. This change makes PutReg conform to the documentation, which states that the parameter must be omitted to cause a deletion to occur.
2. Registry BINARY and DWORD data types can now be written to the Registry by using a new optional parameter to specify the data type. If not specified, it defaults to REG:String unless the value contains an ASCII 0 which will cause it to default to REG:Binary.
3. PutReg can now be used to save values to "HKEY_USERS\.Default\Software" by using REG:UserDefault for the scope parameter.
1. DWORD and BINARY data types are now supported.
2. RegEdit Export uses the backslash to indicate a special character follows. It is now processed correctly.
1. A new registry data type equate, REG:DWORD, has be added to RegFunc.Equ . It has the same value as REG:Long. It was added for those programmers who find it easier to remember the name of the corresponding Registry data type.
It may be necessary to change some of your code when converting from version 1.0. Every effort is made to the need for the developer to convert any code but in certain cases that is not possible. Below are the areas you may need to address when upgrading from 1.0.
Using PutReg to delete a value by providing an empty string for the value parameter, no longer works. Change your code to call PutReg with an omitted value parameter.
Strings with backslash characters have to be doubled-up to
import correctly. For example:
C:\\MyApp\\Bin
The best way to ensure compatibility is to import your .REG files using version 1.0 and then export then back out using RegEdit.
The Windows Registry is a system database used for storing and retrieving configuration data. It is organized in as a hierarchical tree of keys similar to folders (directories) on a disk. A key can contain any number of named values containing data. The key itself can also have a value. Security and a wide assortment of data types are supported.
Subkeys are keys within other keys. They can be accessed directly by passing a string specifying all the keys separated by a backslash (\). It must not start or end with a backslash.
key\subkey1\subkey2\...\subkeyn
The program regedit.exe (part of Windows) can be used to browse the registry and verify that your code is working correctly.
The following keys are predefined by Windows:
|
HKEY_CLASSES_ROOT |
Registered document types (classes) and OLE applications and controls. Subkey of HKEY_LOCAL_MACHINE |
|
HKEY_CURRENT_USER |
Preferences and configuration data for the current user. Subkey of HKEY_USERS |
|
HKEY_LOCAL_MACHINE |
Configuration data affecting the entire PC |
|
HKEY_USERS |
Default preferences and configuration data for users |
|
HKEY_PERFORMANCE_DATA |
NT Only. PC Performance Data |
|
HKEY_CURRENT_CONFIG |
A subkey of HKEY_LOCAL_MACHINE containing the configuration used to start the PC. |
|
HKEY_DYN_DATA |
Win 95/98 only. PC Performance Data |
Equates have been defined for these keys in “REGFUNC.EQU”
There are 3 areas where the developer needs to be concerned about when using the Registry to save application information. They are:
HKEY_LOCAL_MACHINE\Software
HKEY_CURRENT_USER\Software
HKEY_USERS\.Default\Software
The application should create a key hierarchy in each of the above keys to contain the applications information. The standard method for doing so is to create keys for your company name, product name and version. For example:
HKEY_LOCAL_MACHINE\Software\MyCompany\MyApp\1.0
HKEY_CURRENT_USER\Software\MyCompany\MyApp\1.0
HKEY_USERS\.Default\Software\MyCompany\MyApp\1.0
Entries in under HKEY_LOCAL_MACHINE are for all users. They are available regardless of who is logged on to the PC. Use this key when saving application specific information that is the same for all users.
Entries in under HKEY_CURRENT_USER pertain to the current user only. Windows maintains a separate copy of this key for each user of the PC. When the user logs on, their information is becomes visible under this key. Use this key to save user specific information such as window locations, window sizes, list column widths and other user preference settings.
Entries under HKEY_USERS\.Default contains the default information for new users. When a new user logs on, Windows initializes that user's key with the information here. Have your application look for the existence of its key under HKEY_USERS\.DEFAULT, if it does not exist then it should create it at that time. If default user settings are definable within your application, this is the key that should be maintained.
What does the Registry give you that INI files do not?
Although user settings can be saved in an INI file, extra work must be done to save the information for each user of the PC. This is easy using the Registry.
The HKEY_CURRENT_USER key is where information for the current user is saved. When a different user logs on, this key will contain the information for that user. This means that the programmer does not need to manage different areas.
Having your application define the DSN it needs to access a SQL database eliminates the need of having to do it manually. The user may not do it right and that means a support call to you.
DSNs are maintained in the application areas (discussed in previous section). User DSNs are defined under the HKEY_CURRENT_USER key while system DSNs are defined under HKEY_LOCAL_MACHINE. There are two keys you need to be concerned about. They are:
Software\OBDC\ODBC.INI
Software\OBDC\ODBC.INI\ODBC Data Sources
"Software\OBDC\ODBC.INI\ODBC Data Sources" key contains a list of the DSNs defined. The actual DSN definition is contained in a key you create under "Software\OBDC\ODBC.INI". See your SQL database documentation to find out what values need to be defined. Also you can create the desired DSN using the ODBC manager and then use REGEDIT to see the values that were created.
File types are defined under the HKEY_CLASSES_ROOT key. The process is complicated and requires the use of the program UUIDGEN.EXE to create a class identifier for your application. It is available in Visual C++ or by downloading the Platform SDK from the Microsoft MSDN web site.
· No support for16-bit, only 32-bit API calls are made. Make sure your project is set to 32 bit.
· Registry security is not supported. Keys with security defined may not be accessible.
· Only the REG_DWORD (REG:Long), REG_BINARY (REG:Binary), and REG_SZ (REG:String) data types are supported.
· Registry files are not supported.
· Connecting to a network registry is not supported.
Two templates are provided, one for the Clarion legacy template chain and the other for the ABC templates. Use the following steps to add Registry Function Library in an application:
1. Click on the “Global” button and then the “Extension” button.
2. Click “Insert” on the Extension Window.
3. Click on the “RegFuncABC” template ("RegFunc" for classic templates) in the “Select Extension” window and then click “Select”.
4. If you compiled the Registry Function Library into a DLL or LIB and you want to call the functions from your app, check “Defined externally in a DLL or LIB”.
In a multi-DLL application, it makes sense to have a single DLL to contain the Registry Function Library and have the other DLLs call it. Primarily, this saves space and allows you to encapsulate other related functions for reuse in other applications.
In the DLL that will contain the Registry Function Library, select the RegFuncABC template (RegFunc for classic template chain) for use as discussed above. Ensure that “Externally defined in DLL or LIB” is not checked in the template window. The template will take care of “exporting” the functions for use by other apps.
In all other apps (EXE or DLL) that will use the functions, select the RegFunc or RegFuncABC template. Ensure that “Externally defined in DLL or LIB” is checked in the template window. As with any multi-DLL application, the DLL module must be added to the app or the project. It is not necessary to prototype the functions, this is done by the template.
Use the following steps to add Registry Function Library to a hand-coded project:
1. Open your Project file (*.PRJ).
2. Add “RegFunc.clw” to the “External source files” folder.
3. If you will be using the “ImportRegFile” function then add the ASCII file driver to the project in the “Database driver libraries” folder.
4.
Add the following to your program file before the MAP
statement if the functions are not defined externally in a DLL.
rfl_dll_mode equate(0)
5.
In the MAP of your main source file add:
module('RegFunc')
include(‘RegFunc.Inc’)
end
6.
Add the following include in your global declarations section:
include('RegFunc.Equ')
7. If you are making a DLL then you will need to add the functions you want externally available to your export file (.EXP).
The RFL_PutReg and GetReg functions are designed to replace GETINI and PUTINI with a minimum of changes to the parameters. In most cases, the file parameter of PUTINI and GETINI can successfully be used as the programkey parameter in GetReg and RFL_PutReg. The only exception is when the designation for parent directory (2 periods) or current directory (1 period) is used. For example: “.\MyINI.INI”. A period is not allowed to be the first character of the name of a key name.
These functions also provide the simplest method for accessing data in the registry by providing a single function for reading and saving registry data. Access, though, is restricted to the “application areas” of the registry. See Registry Overview for information about “application areas” of the registry. It is not necessary to use any of the Key Functions to create or open keys when using these functions.
RFL_PutReg([section] ,entry [,value] [,programkey] [,scope] [,datatype])
Store or delete a value in of the application areas of the registry:.
HKEY_LOCAL_MACHINE\Software
HKEY_CURRENT_USER\Software
HKEY_USERS\.Default\Software
|
section |
A subkey under the key specified by programkey. Can be omitted. |
|
entry |
The name of the value to store |
|
value |
A string constant or variable containing the value to store. The length can be up to 255 characters. If omitted, the value name specified by entry is deleted. |
|
programkey |
The subkey to contain all of the values for the program. This is usually in the form “CompanyName\Program\Version”. If omitted, the key “Clarion Programs” is used. |
|
scope |
A LONG constant that specifies that the entry is for all users (REG:System), the current user (REG:User), or the default for new users (REG:DefaultUser). If omitted, REG:System is used. These 3 settings correspond to the registry application areas described above. |
|
datatype |
The registry data type to use for entry. Specify REG:Long (or REG:DWord), REG:String, or REG:Binary. REG:Key is not valid. If omitted then REG:String is used unless the value contains an ASCII 0 in which case REG:Binary is used. |
RFL_PutReg is meant to mimic PUTINI with a few exceptions as noted in the section “Replacing PUTINI and GETINI”.
Omitting value will cause the value named by entry to be deleted. To store an empty string (null), value should be set to ''.
! Store Path for Image Files
! In HKEY_LOCAL_MACHINE\Software\MyCompany\MyProgram\1.0\Paths
RFL_PutReg('Paths','Images','.\Images','MyCompany\MyProgram\1.0')
! Store Width of Billing Window for current user
! In HKEY_CURRENT_USER\Software\MyCompany\MyProduct\1.0\BillingWindow
RFL_PutReg('BillingWindow','Width',BillingWindow{PROP:Width}, |
'MyCompany\MyProgram\1.0',REG:User,REG:DWORD)
! A "Lazy" Example
! Store Width of Billing Window for last user
! In HKEY_LOCAL_MACHINE\Software\Clarion Programs
RFL_PutReg(,'BillingWindowWidth', BillingWindow{PROP:Width})
RFL_GetReg([section] ,entry [,default] [,programkey] [,scope])
Retrieve a value from either of the application areas of the registry:
HKEY_LOCAL_MACHINE\Software
HKEY_CURRENT_USER\Software
HKEY_USERS\.Default\Software
|
section |
A subkey under the key specified by programkey. Can be omitted. |
|
entry |
The name of the value to retrieve |
|
default |
The value to retur |