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. 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_drop

file chstc.c
declaration 
function hst_drop(ht, e)
    define ht	byte,
	   e	char(K_entrysize)
returns nothing
purpose Deletes an entry from an associative array.
example none
notes none

hst_enter

file chstc.c
declaration 
function hst_enter(ht, e, d)
    define ht	byte,
	   e	char(K_entrysize),
	   d	char(K_defsize)
returns nothing
purpose Adds or updates an entry to an associative array.
example none
notes none

hst_enterdate

file chstc.c
declaration 
function hst_enterdate(ht, e, d)
    define ht	byte,
	   e	char(K_entrysize),
	   d	date
returns nothing
purpose Adds or updates an entry to an associative array.
example none
notes none

hst_enterdecimal

file chstc.c
declaration 
function hst_enterdecimal(ht, e, d)
    define ht	byte,
	   e	char(K_entrysize),
	   d	decimal
returns nothing
purpose Adds or updates an entry to an associative array.
example none
notes none

hst_enterdtime

file chstc.c
declaration 
function hst_enterdtime(ht, e, d)
    define ht	byte,
	   e	char(K_entrysize),
	   d	datetime
returns nothing
purpose Adds or updates an entry to an associative array.
example none
notes none

hst_enterfloat

file chstc.c
declaration 
function hst_enterfloat(ht, e, d)
    define ht	byte,
	   e	char(K_entrysize),
	   d	float
returns nothing
purpose Adds or updates an entry to an associative array.
example none
notes none

hst_enterint

file chstc.c
declaration 
function hst_enterint(ht, e, d)
    define ht	byte,
	   e	char(K_entrysize),
	   d	integer
returns nothing
purpose Adds or updates an entry to an associative array.
example none
notes none

hst_enterinv

file chstc.c
declaration 
function hst_enterinv(ht, e, d)
    define ht	byte,
	   e	char(K_entrysize),
	   d	interval
returns nothing
purpose Adds or updates an entry to an associative array.
example none
notes none

hst_free

file chstc.c
declaration 
function hst_free(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_free instead.

hst_member

file chstc.c
declaration 
function hst_member(ht, e)
    define ht	byte,
	   e	char(K_entrysize)
returns m, boolean
purpose Tests whether an entry is member of an associative array.
example none
notes none

hst_retrieve

file chstc.c
declaration 
function hst_retrieve(ht, e)
    define ht	byte,
	   e	char(K_entrysize)
returns d, char(K_entrysize), value associated with entry e
purpose Retrieves the value associated with an entry of an associative array.
example none
notes in actual fact, hst_retrieve 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_retrieve is not readily available

hst_scan

file chstc.c
declaration 
function hst_scan(ht, idx)
    define ht	byte,
	   idx	integer
returns e, char(K_entrysize), next entry
d, char(K_entrysize), entry value
idx, integer, routine state.
purpose Scans an associative array.
example none
notes
  • The initial value of idx should be NULL
  • Successive calls should be passed the value returned by the previous call
  • The end of the array being reached is flagged by e and d both being NULL

hst_start

file chstc.c
declaration 
function hst_start(ht, hs)
    define ht	byte,
	   hs	smallint
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 asc_free