REGISTRY for Rex 6000 V0.7

This is a package which provides a simple registry (similar to the Microsoft Windows registry) for the Rex.

Programs can store and retrieve text strings, 32-bit values and binary buffers using the registry.

Design

The core function is to maintain a database indexed by key name containing the registered values.

Each record has fields for both DWORD values and variable length data. One or other of these fields are used depending on a TYPE field.

Limitations

Unlike Microsoft's registry, this registry is not actually structured with a containment hierarchy. The keys are just text strings.

There is no user interface to allow editing of the registry. The existing REGmaint program just allows basic database maintenance and REGedit can only handle exporting the whole registry to a memo or importing keys from a memo.

Documentation

The addin programmer has a choice of two forms of the library to use:

Consumers must both include registry.h and link with either registry.lib or registry-so.lib. The libraries should be put in ../../lib/clibs and linked using -lregistry or -lregistry-so.

Writing values into the registry

There are three functions used to write values into the registry:

reg_write_sz

int reg_write_sz(char *keyname, char *value)

char *keyname -- registry key text string

char *value -- value to write (zero terminated text string)

return value -- if less than zero, an error code; if greater than or equal to zero, success

reg_write_dword

int reg_write_dword(char *keyname, unsigned long value)

char *keyname -- registry key text string

unsigned long value -- value to write

return value -- if less than zero, an error code; if greater than or equal to zero, success

Note: if specifying a constant value, it should be a long contant (e.g. "2L").

reg_write_binary

int reg_write_binary(char *keyname, unsigned char *value, unsigned short length)

char *keyname -- registry key text string

unsigned char *value -- pointer to data to write

unsigned short length -- length of data to write

return value -- if less than zero, an error code; if greater than or equal to zero, success

Reading values from the registry

There are three functions used to read values from the registry:

reg_read_sz

int reg_read_sz(char *keyname, char *buffer, unsigned short max_length)

char *keyname -- registry key text string

char *buffer -- pointer to buffer to receive text string

unsigned short max_length -- maximum length of data to retrieve (including zero terminator)

return value -- if less than zero, an error code; if greater than or equal to zero, the length of the string actually copied to the buffer

Note 1: if the buffer is long enough, the full string value will be copied to the buffer, including the zero terminator, and the length of the string (excluding the zero terminator) will be returned.

Note 2: if the buffer is not long enough, max_length-1 bytes will be copied, the last byte will be zeroed and the length actually copied (excluding the zero terminator) will be returned.

Note 3: the expression REG_MAX_VALUE+1 can be used to allocate a buffer guaranteed to be long enough for any string value.

reg_read_dword

int reg_read_dword(char *keyname, unsigned long *p_value)

char *keyname -- registry key text string

unsigned long *p_value -- pointer to long int to receive the value

return value -- if less than zero, an error code; if greater than or equal to zero, success

Note: if an error is returned (in particular, REG_ERR_WRONG_TYPE), the output parameter (pointed to by p_value) may have been modified -- the contents are undefined.

reg_read_binary

int reg_read_binary(char *keyname, char *buffer, unsigned short max_length)

char *keyname -- registry key text string

char *buffer -- pointer to buffer to receive binary data

unsigned short max_length -- maximum length of data to retrieve

return value -- if less than zero, an error code; if greater than or equal to zero, the length of the data actually copied to the buffer

Note 1: if the buffer is long enough, the full binary value will be copied to the buffer and the length of the data will be returned. The contents of the buffer beyond the copied data are undefined.

Note 2: if the buffer is not long enough, max_length bytes will be copied, and the length actually copied will be returned.

Note 3: the constant REG_MAX_VALUE can be used to allocate a buffer guaranteed to be long enough for any binary value.

Deleting keys from the registry

reg_delete

int reg_delete(char *keyname)

char *keyname -- prefix of registry keys to be deleted

return value -- if less than zero, an error code; if greater than or equal to zero, success

Note 1: reg_delete will delete all keys which have the specified prefix.

Note 2: if no keys match the prefix, the error REG_ERR_NOT_FOUND will be returned. The caller may or may not consider this an error.

Creating the database

The routines described above assume the database exists. If you want to make sure the database exists, call reg_database_create(). The return value is either an error code (if less than zero) or success (if greater than or equal to zero).

Note that if the database already exists, this routine will return success and will not modify the database.

Version control

Future versions of this library may change the database format. To check that the database format is consistent with your version of the library, call reg_version_check(). This returns an error code if the database version is inconsistent.

Note: reg_database_create automatically includes this check so you do not need to call reg_version_check if you have called reg_database_create.

Import

It is possible to import registry values from a Memo. The Memo must have the following format (based on the Microsoft .reg format):

Prototype

int reg_import_memo(const char *memo_name)

Parameters

Return value

Notes

Export

Any sub-tree of the registry may be exported to a Memo. The Memo will be in a format compatible with reg_import_memo and Microsoft's .reg files.

Prototype

int reg_export_memo(char *keyname, const char *memo_name)

Parameters

Return value

Notes

Source files

Copyright (C) 2001, 2002 Graham R. Cobb. The package is distributed under the GPL (see the copyright notices and the COPYING file).

REGISTRY For Rex 6000 is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

REGISTRY For Rex 6000 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

When the ZIPfile is expanded, it creates the key library files (and several informational files) in the current directory and creates several source subdirectories.

The package itself:

REGedit

Registry import/export utility.

This utility can be used to import a set of keys and values from a Memo, using the same format as Microsoft's .reg files.

The utility can also export the entire database to a Memo with a fixed name (Registry Export). It cannot export portions of the registry tree nor can it be used to edit the tree.

The utility is linked with the shareable library versions of GRClib, REGISTRY and MemoIO so all these shareable libraries must be loaded.

REGmaint

Registry database maintenance utility. Can be used to create the database, examine the database and delete the database.

REGtest

Sample addin using the registry.

Changes

In V0.7

Add REG_ERR_NO_REGISTRY error if shareable library not loaded. This allows code to try a registry lookup but to react gracefully if the registry library is not loaded.

In V0.6

Link with new FindLib from August 2002 RexDk

In V0.5

Fix unintended dependency on GRCLIB library addin.

In V0.4

Convert to new Rexdk shareable library mechanism.

Add second shareable library.

In V0.3

Add shareable library.

Add import/export.


Return to Graham's Rex page

This page has been accessed Access counter times.

Graham Cobb