4glWorks reference: Associative arrays

4glworks offers a homegrown implementation of associative arrays built over memory located byte variables. Hashes have no limit in the number of entries and are self reorganizing. Hash entries can be hashes themselves, and thus it is possible to implement tree structures. K_entrysize and K_defsize (see the declarations below) are currently set to 32K.
The functions below that return values return nulls in case of erroneous arguments. All set status in case of errors.

hst_add

file chstc.c
declaration
function hst_add(ht, n, d, e, t)
    define ht	byte,			#byte containing the hash
	   n	integer,		#the destination node
	   d	char(K_defsize),	#the entry description
	   e	char(K_entrysize),	#the entry contents
	   t	integer			#the storage type
returns nothing
purpose Adds or updates an entry to an associative array.
example none
notes Of the input parameters n and t need some explanation: the first is the node the entry needs to be added to. This should be 0 to signify the root node, or an address returned by hst_addnode. The second is the type the entry should be stored as (the entry value passed as e will be converted accordingly). Possible types are defined in sqltypes.h. Entries are stored as strings should the type be invalid.

hst_addnode

file chstc.c
declaration
function hst_addnode(ht, n, d, b)
    define ht	byte,			#byte containing the hash
	   n	integer,		#the destination node
	   d	char(K_defsize)		#the node description
	   b	integer			#the initial number of buckets
returns nothing
purpose Creates a hash node
example none
notes see hst_add

hst_delete

file chstc.c
declaration
function hst_delete(ht, n, d)
    define ht	byte,			#byte containing the hash
	   n	int, 			#the destination node
	   d	char(K_defsize)		#the entry description
returns nothing
purpose Deletes an entry from an associative array.
example none
notes none

hst_dispose

file chstc.c
declaration
function hst_dispose(ht)
    define ht	byte
returns nothing
purpose Frees a hash variable
example none
notes It appears that 4gl keeps track of the blobs it locates, so while it is entirely possible to free hashes the 4gl way, this is cumbersome and error prone. Use hst_dispose instead.

hst_fetch

file chstc.c
declaration
function hst_fetch(ht, l)
    define ht	byte,			#byte containig the hash
	   l	integer			#leaf address of the hash entry
returns d, char(K_entrysize), value associated with entry l
purpose Retrieves the value associated with an entry of an associative array by entry leaf address (as opposed to a node/description pair)
example none
notes
  • The leaf address l can be obtained via hst_get or hst_walknode
  • In actual fact, hst_fetch return value could be of any type. It is safer to use a character destination variable if the type of the return value of hst_fetch is not readily available

hst_get

file chstc.c
declaration
function hst_get(ht, n, d)
    define ht	byte,			#byte containing the hash
	   n	integer,		#the destination node
	   d	char(K_defsize)		#the entry description
returns l, integer, leaf address of entry e
e, char(K_entrysize), value associated with entry d
purpose Retrieves the value associated with an entry of an associative array.
example none
notes In actual fact, hst_get return value could be of any type. It is safer to use a character destination variable if the type of the return value of hst_get is not readily available

hst_locate

file chstc.c
declaration
function hst_locate(ht, hs)
    define ht	byte,			#byte containing the hash
	   hs	smallint		#initial no of buckets for the root node
returns nothing
purpose Initializes an associative array.
example none
notes
  • hs is the initial number of buckets
  • The associative array can only be disposed of using hst_dispose

hst_update

file chstc.c
declaration
function hst_update(ht, l, e, t)
    define ht	byte,				#byte containing the hash
	   l	integer,			#the entry leaf address
	   e	char(K_entrysize),		#the entry contents 
	   t	type				#the storage type
returns nothing
purpose Updates an entry to an associative array.
example none
notes see hst_add and hst_get

hst_walknode

file chstc.c
declaration
function hst_walknode(ht, n, l)
    define ht	byte,				#byte containing the hash
	   n	integer,			#node to be scanned
	   l	integer				#the entry leaf address
returns l, integer, leaf address of the next entry e
d, char(K_defsize), definition string of the entry
e, char(K_entrysize), value associated with the entry
purpose Updates an entry to an associative array.
example none
notes
  • during the first invocation, the input parameter l needs to be null. For all other invocations, l needs to be set to the value returned by the previous invocation via the output parameter l
  • In actual fact, e could be of any type. It is safer to use a character destination variable if the type of e is not readily available
  • In the current implementation, the behaviour of hst_walknode may affected by invocations to hst_get, hst_add, hst_delete, hst_addnode


Please address questions or comments to marco greco
(last updated Sun, 23 March 2003 21:14:52 GMT)