Setup Method

The Setup method sets up the StringHashTable with the number of buckets specified in the size parameter.

Though the default hashing and comparison algorithms are usually suffient, they can be used to provide hashing and comparison algorithms which are more complex or more appropriate for the actual keys entered into the hash table.

The 3GL procedures referred to by the comparekeyfunction and hashkeyfunction parameters must exist in the application and must be defined as Language "C", returntype "integer".

The 3GL implementation of the comparekeyfunction requires two 4-byte integer (long) parameters (the key to compare with and the key in the hash table) and should return 0 (zero) if the keys match or a non-zero value otherwise.

The 3GL implementation of the hashkeyfunction requires two 4-byte integer parameters (the key to be hashed and the size of the hashtable) and should return the (4-byte integer) hash value for the key.

integer = StringHashTable.Setup([size = integer]
          [, uniquekey = integer]
          [, autoresizethreshold = integer]
          [, objectclass = Class[, allowsubclassobjects = integer]]
          [, comparekeyfunction = varchar]
          [, hashkeyfunction = varchar]
          [, ignorecase = integer])

Specifies the number of buckets for the hash table. If size is not specified, a default of 89 is used. The specified size must be greater than 2. A prime number should be used; if size is not a prime number it automatically will be adjusted to the next prime number.

Designates that there is not already an entry with the specified key in the hash table. The uniquekey information will be used during later InsertObject method invocations.

Note: Using this option will add some overhead when inserting objects.

Specifies a positive integer that represents the size threshold as a percentage at which the hash table will automatically be resized. The new size will be 2*size+1. A value of 0 (zero) indicates that the hash table should not be resized automatically.

A recommended value is 75, that is, the hash table will be increased when the number of objects entered exceeds 75% of the size of the hash table.

You can use this parameter to get a better distribution of key values within increasing hash tables, which should lead to better performance for InsertObject and Find methods.

Note: The resizing will add some performance and memory overhead.

Specifies the class of objects that are allowed to be entered into the hash table. If this attribute is NULL, then objects of all classes are allowed. Objects of subclasses of the specified class are also allowed if allowsubclassobjects is TRUE.

Using this option will add some overhead when inserting objects.

Specifies whether subclasses of the object class specified in objectclass may be entered into the hash table. Valid values are TRUE or FALSE.

Specifies the names of 3GL procedures that will perform the comparison of keys for the StringHashTable

Specifies the names of 3GL procedures that will perform the hashing of keys for the StringHashTable

Specifies that case should be ignored when comparing keys. This information will be used during later method invocations having a key parameter.

This method returns ER_OK on success, ER_FAIL if an error occurred. Descriptions of system constant values and their numeric equivalents are listed in Error Codes (see Error Codes).