The Reginald REXX interpreter allows a script to create/delete/read/write/query registry keys and values.

A registry key is like a directory. A registry value is like a file in which you store some data. A value is therefore created inside of a key. For the rest of this tutorial, 'directory' will be substituted for 'key', and 'file' will be substituted for 'value'.

By default, Reginald will create/delete directories only under the "Current User" directory of the registry. One nice thing about this registry directory is that, each user who logs onto the system with his own profile, has his own "Current User" directory that is automatically set upon log-on. So, when you create/delete/read/write/query registry directories and files, they are per-user settings. For example, if you create a registry directory named 'My Key' and a registry file named 'My Value' inside of it, and store the data 'This is some data' in that file, this will appear in the 'Current User' directory of only whomever was logged in on the system. If another person logs in, there will be no such directory and file in his 'Current User' directory. So your script can store personalized data for each person who uses the system, and have that data automatically accessible when the person logs in. You don't have to do any extra work to implement personalized 'user profiles'.

You create/delete/read/write/query registry directories and files using an extension to Reginald's VALUE() built-in function.

To access the registry, you pass WIN32 for the third (environment) arg to VALUE().


Create a directory in the registry

To create a directory, you must pass a directory name as the first (name) arg to VALUE(). The directory name must end with a \ character. You must omit the second (new_value) arg. For example, here we create a directory named My Directory:

error = VALUE("My Directory\", , "WIN32")
If all goes well, VALUE() will return an empty string. Otherwise, it will raise a SYNTAX error with error number 40.37.

Note: If the directory already exists, then this is not an error. VALUE() will return an empty string without disturbing the contents of the directory, nor raising SYNTAX.

You can even create a directory inside of another directory. But that other directory must exist first, or SYNTAX is raised. You also must specify the full path to the new directory. For example, here we create a sub-directory named My Sub-Directory inside of an existing directory named My Directory:

error = VALUE("My Directory\My Sub-Directory\", , "WIN32")

Create/Write a file in the registry

You create a registry file, and write some data to it, with a single call to VALUE(). For the first arg, you pass the name of the file to create. This name must include the full path (ie, directories). It must not end with a \ character. For the second arg, you pass the data that you wish to write. If all goes well, VALUE() will return the previous contents of that file. Otherwise, VALUE() will raise a SYNTAX condition with error 80.5.

For example, here we create a file named My File inside of the existing directory My Directory\My Sub-Directory, and write the data This is some data. to it:

previous = VALUE("My Directory\My Sub-Directory\My File", "This is some data.", "WIN32")
Note: If the file previously existed, its old contents are overwritten.


Read a file in the registry

If you wish to read the contents of some registry file, then you specify the name of that file as the first arg. This name must include the full path (ie, directories). It must not end with a \ character. You should omit the second arg in order not to change the contents of the file. If all goes well, VALUE() will return the contents of that file. But if the file doesn't exist, then VALUE() simply returns an empty string. (So, if it's important to distinguish between a file that doesn't exist versus a file whose contents is an empty string, then first query if the file exists).

For example, here we read the contents of a registry file named My File inside of the directory My Directory\My Sub-Directory:

data = VALUE("My Directory\My Sub-Directory\My File", , "WIN32")
As another example, here we query and print the value of Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Personal:
SAY VALUE("Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Personal", , "WIN32")
The above would normally print "C:\MY DOCUMENTS", which is where you would typically save your data files that should reside on disk.

Note: To obtain the location of special directories such as where the current user stores documents, where his desktop is located, etc, you should instead use Reginald's SEARCHPATH() built-in.


Query if a file exists

To query if a registry file exists, you specify the name of the directories (containing the file) as the first arg. This name must include the full path (ie, directories). and end with a \ character. For the second arg, you pass only the name of the file without its directories. If the file exists, a 1 is returned, otherwise an empty string is returned.

For example, here we query if a registry file named My File exists inside of the directory My Directory\My Sub-Directory:

IF VALUE("My Directory\My Sub-Directory\", "My File", "WIN32") == 1
   THEN SAY "It exists."

Delete a file in the registry

To delete a file, you must specify an empty string for the first arg. For the second arg, you pass the name of that file. This name must include the full path (ie, directories). It must not end with a \ character.

For example, here we delete the registry file named My File inside of the directory My Directory\My Sub-Directory:

VALUE("", "My Directory\My Sub-Directory\My File", "WIN32")
Note: It is not an error to delete a file that doesn't exist.


Delete a directory in the registry

To delete a directory, you must specify an empty string for the first arg. For the second arg, you pass the name of the directory. This name must include the full path (ie, directories). It must end with a \ character.

For example, here we delete the registry directory named My Sub-Directory inside of the directory My Directory:

VALUE("", "My Directory\My Sub-Directory\", "WIN32")
Note: It is not an error to delete a directory that doesn't exist.


Other registry areas

By default, Reginald creates/reads/writes/queries directories and files under the "Current User" area of the registry. But if desired, you can also create/read/write/query directories and files in other special areas of the registry. For example, the "Local Machine" area of the registry contains directories/files that pertain to the computer system itself (ie, to all users of that computer). There are 7 areas of the registry which you can access (although not all versions of Windows have all 7 areas). They are as follows:

HKEY_CLASSES_ROOT Holds information about file associations and shell extensions.
HKEY_CURRENT_USER Holds information about the currently logged in user. This is the area that VALUE() uses by default when accessing the registry.
HKEY_LOCAL_MACHINE Holds information about the computer's hardware/drivers.
HKEY_USERS Holds information applicable to all users (ie, default setup).
HKEY_PERFORMANCE_DATA
HKEY_CURRENT_CONFIG
HKEY_DYN_DATA

If you wish to access one of these other areas, you need to specify it as the first directory. For example, here we read the contents of a file named .txt in the directory Software\Microsoft\Windows\CurrentVersion\Extensions in the HKEY_LOCAL_MACHINE area of the registry.

SAY VALUE("HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Extensions\.txt", , "WIN32")