A Rexx interface to the gDBM library

Version 1.0

28 April 2006

1. Introduction
2. Overview
3. Functions: GDBMOPEN; GDBMCLOSE; GDBMSETOPT; GDBMEXISTS; GDBMGETKEY; GDBMFETCH; GDBMINSERT; GDBMREPLACE; GDBMDELETE; GDBMSYNC; GDBMREORGANIZE; GDBMSTRERROR; GDBMLOADFUNCS; GDBMDROPFUNCS
4. Errors
5. Using Rexx/GDBM
6. History of Rexx/GDBM

1. Introduction

This document describes the interface to the gDBM package. gDBM is a general purpose package that allows access and manipulation of simple key/value database files. These are basically hash-organized files that also allow every key to be visited (not in any collated order) under control of your Rexx program. Rexx/GDBM is actually built on top of libgdbm but for the purposes of this document it will be refered to simply as gDBM.

2. Overview

Rexx/GDBM consists of Rexx external functions that allow a Rexx program to access any gdbm file. Records may be inserted, replaced, deleted, all records may be traversed, and the file may be reorganized.
See Using Rexx/GDBM for more details.

The Rexx/GDBM external functions are:

GDBMOPEN - initialize the gDBM interface -- for reading/writing/creation.
GDBMCLOSE - cleanup the gDBM interface
GDBMSETOPT - which may be changed during a given access.
GDBMEXISTS - determine if a given key exists.
GDBMGETKEY - read first or next key.
GDBMFETCH - access a given key and its associated data.
GDBMINSERT - insert a new key and record into the database.
GDBMREPLACE - replace the data portion of a given record.
GDBMDELETE - remove a key and its associated data from the database.
GDBMSYNC - remove a key and its associated data from the database.

GDBMLOADFUNCS - load all Rexx/GDBM external functions
GDBMDROPFUNCS - unload all Rexx/GDBM external functions

3. Functions

This section provides the full syntax and usage of each function that comprises Rexx/GDBM.

GDBMOPEN( handle-variable-name, database-path, blocksize, read_write, mode )

Initializes the gDBM interface. The value stored by a successful invocation in the variable named as the first argument of this function is used in all succeeding functions to re-establish this particular access; i.e., the first argument is a quoted string denoting the symbol name of the handle variable.

Arguments:

handle-variable-name

quoted-string variable name

database path

the file name of the database to be opened

blocksize

size of single transfer to/from disk (ignored if not new file)

read_write

Access Type	"READER"	"WRITER"	"WRCREAT"	"NEWDB"
Function	read-only	read and write	create if non-existent	always create
Access Type		"UL_WRITER"	"UL_WRCREAT"	"UL_NEWDB"
No Lock		unlocked	unlocked	unlocked

mode

octal chmod-style permissions (ignored if not new file)

Returns:

success:: zero
failure:: non-zero

GDBMSETOPT( handle, option,option value[,more option values,...] )

This function is called to define the few access parameters which may be altered after GdbmOpen has occurred successfully. Booleans may be given as 'yes'/'no' '1'/'0' 'true'/'false'. 'CACHESIZE' may only be applied once, prior to the first data access.

Arguments:

handle

The value returned from GDBMOPEN.

option

This is the string identifying the option to set.

Option	"CACHESIZE"	"SYNCMODE"	"CENTFREE"	"COALESCEBLKS"
Function	integer: number of cache buckets	boolean: write synchronously	boolean: centralize free pool	boolean: coalesce freed blocks

option value

The value of the option to set.

Returns:

success:: blank
failure:: blank; On failure GDBMERROR.INTCODE is set to a non-zero value. If this value is 1 (one) then GDBMERROR.GDBMCODE is also set to a non-zero value.

GDBMCLOSE( handle )

Terminate current access to the database file.

Arguments:

handle: The value returned from GDBMOPEN.

Returns:

success:: blank
failure:: blank; On failure GDBMERROR.INTCODE is set to a non-zero value. If this value is 1 (one) then GDBMERROR.GDBMCODE is also set to a non-zero value.

GDBMSYNC( handle )

Flush modified data to disk.

Arguments:

handle: The value returned from GDBMOPEN.

Returns:

success:: blank
failure:: blank

GDBMREORGANIZE( handle )

Reorganize the database file on disk.

Arguments:

handle: The value returned from GDBMOPEN.

Returns:

success:: 0
failure:: non-zero

GDBMSTRERROR( )

Return error description string. Probably not thread-safe.

Arguments:

none

Returns:

success:: String describing last error seen by gdbm

GDBMEXISTS(handle, key)

Determine if a key exists in the database, without transferring data.

Arguments:

handle: The value returned from GDBMOPEN.
key: The key value to test.

Returns:

success:: 1
failure:: 0; Failure includes the non-existence of the requested key. GDBMERROR.INTCODE is set to a non-zero value if some other error condition is raised. If GDBMERROR.INTCODE is 1 (one) then GDBMERROR.GDBMCODE is also set to a non-zero value.

GDBMDELETE(handle, key)

Remove a key and its associated data.

Arguments:

handle: The value returned from GDBMOPEN.
key: The key value of the record to be deleted.

Returns:

success:: 0
failure:: Non Zero; Failure includes the non-existence of the requested key. GDBMERROR.INTCODE is set to a non-zero value if some other error condition is raised. If GDBMERROR.INTCODE is 1 (one) then GDBMERROR.GDBMCODE is also set to a non-zero value.

GDBMINSERT( handle, key, data )

Insert the given key and data into the database.

Arguments:

handle: The value returned from GDBMOPEN.
key: The key value to associate with the data.
data: The data to store with the given key.

Returns:

success:: 0
failure:: non-zero; Failure includes the existence of the given key. GDBMERROR.INTCODE is set to a non-zero value if some other error condition is raised. If GDBMERROR.INTCODE is 1 (one) then GDBMERROR.GDBMCODE is also set to a non-zero value.

GDBMREPLACE( handle, key, data )

Replace the data associated with the given key.

Arguments:

handle: The value returned from GDBMOPEN.
key: The key value to associate with the data.
data: The data to store with the given key.

Returns:

success:: 0
failure:: non-zero; Failure includes the non-existence of the given key. GDBMERROR.INTCODE is set to a non-zero value if some other error condition is raised. If GDBMERROR.INTCODE is 1 (one) then GDBMERROR.GDBMCODE is also set to a non-zero value.

GDBMGETKEY( handle, key-variable-name )

Retrieve the first or next key in a traversal of keys.

Arguments:

handle: The value returned from GDBMOPEN.
key-variable-name: The name of the variable to receive the first or next key.; If this variable is null or empty, the first key will be returned.; otherwise the next key (physical hash sequence) will be returned.

Returns:

success:: 0
failure:: non-zero; GDBMERROR.INTCODE is set to a non-zero value if some other error condition is raised. If GDBMERROR.INTCODE is 1 (one) then GDBMERROR.GDBMCODE is also set to a non-zero value.

GDBMFETCH( handle, key, data-variable-name )

Retrieve the data associated with the given key.

Arguments:

handle: The value returned from GDBMOPEN.
key: The key value of the data to be fetched.
data-variable-name: The quoted string name of the variable to receive the data..

Returns:

success:: 0
failure:: non-zero; Failure includes the non-existence of the given key. GDBMERROR.INTCODE is set to a non-zero value if some other error condition is raised. If GDBMERROR.INTCODE is 1 (one) then GDBMERROR.GDBMCODE is also set to a non-zero value.

GDBMLOADFUNCS()

This function is used to load all the Rexx/GDBM external functions. This function is called after the function has been loaded with the Rexx builtin function rxfuncadd().

Although this function is useful only for dynamic library implementations of Rexx/GDBM, it can be called by the executable version of Rexx/GDBM. In this case it does nothing.

Arguments:

none

Returns:

success:: zero
failure:: non-zero

GDBMDROPFUNCS()

This function is used to terminate Rexx/GDBM and free up all resources that have been used.

It should be called at the end of every Rexx/GDBM program. In particular, this function should be called after a syntax error has been caught with SIGNAL ON SYNTAX.

Arguments:

none

Returns:

success:: zero
failure:: non-zero

4. Errors

The success or failure of each function call is determined by the Rexx compound variable; GDBMERROR.INTCODE. If the function call succeeds, this will be set to zero. If the function call fails, this will be set to a non-zero value. If the value set is 1 (one), a gDBM error occured, and GDBMERROR.GDBMCODE is set to the appropriate error code. Associated with both error code variables, is an equivalent textual error message. These are GDBMERROR.INTERRM and GDBMERROR.GDBMERRM respectively.
The stem name set for the error variables is GDBMERROR. (including trailing period).

Internal Errors:

    1  - Invalid gDBM Handle
    2  - Invalid Boolean
    3  - Invalid Number
    4  - Invalid Option
    5  - gDBM error from setopt
    6  - Invalid read_write option
    7  - Invalid filemode octal string
    8  - Open error from gDBM
    9  - Null key presented to GdbmFetch
   10  - Null data presented to GdbmInsert/GdbmReplace

5. Using Rexx/GDBM

A typical Rexx/GDBM program will either create, modify, or retrieve a gDBM database.

Call RXFuncAdd 'GDBMLoadFuncs','rexxgdbm','GDBMLoadFuncs'
Call GDBMLoadFuncs
ret = GdbmOpen( 'dbf', "/tmp/test.new.gdb", 4096, 'NEWDB', '644' )
If ret=0 then
   Do
      newkey_data = "new record stuff"
      ret = GdbmInsert( dbf, "newkey", newkey_data )
      If gdbmerror.intcode \= 0 Then Call Abort 'Error inserting record "newkey"'
      If GdbmExists( dbf, "newkey" ) then do
         ret = GdbmFetch( dbf, "newkey", 'outdata' )
	 If gdbmerror.intcode \= 0 then Call Abort 'Error retrieving "newkey" data'
         end 
      Call GdbmClose dbf
   End
Call GDBMDropFuncs
Return 0
Abort:
Parse Arg msg
Say msg
If gdbmerror.intcode = 1 Then Say 'Internal error:' gdbmerror.intcode gdbmerror.interrm
Else Say 'GDBM error:' gdbmerror.gdbmcode gdbmerror.gdbmerrm
Call GdbmClose dbf
Exit 1

Examples
Several example programs are provided with all Rexx/GDBM distributions.

History of Rexx/GDBM

This section provides details of changes and additions made to the Rexx/GDBM interface as it evolves.

Version 1.0: 28 Apr 2006

Initial release for Unix platforms.

Last updated 28 April 2006

A Rexx interface to the gDBM library

Table of Contents

1. Introduction

2. Overview

3. Functions

4. Errors

5. Using Rexx/GDBM

History of Rexx/GDBM

Version 1.0: 28 Apr 2006