About
Overview
Philosophy
Features
News
Download
Help Us!

Docs
Overview
Designers
Developers
Functions
Accessors
Database
CGIs
Applications
Roadmap
Architecture

Community
Powered By

• except for the binary data type, all key/value pairs are stored as strings. so even though you may think that you are storing numbers sometimes, you are actually storing string representations of numbers. say it out loud: "everything is a string".
• the *set*() functions store copies - silently over-writing old values if they exist.
• the *get*() functions return empty strings (not NULL pointers) if a value is not found at key. this means that you never need to check for NULL pointers before further using values returned.
• the *get*() functions return pointers to malloc()d data. never directly free() these values, as that would cause corruption of the in-memory storage.
• unless otherwise specified, all functions are re-entrant.

The following is a description of the various methods by which the programmer may move calculated (and other) values in and out of the in-memory storage.

String object accessors

Used to access and manipulate objects which have been stored according to the string convention.

• htdb_setint
• htdb_getint
• htdb_setval
• htdb_setvarg
• htdb_getval
• htdb_setbin
• htdb_getbin
• htdb_checkval
• htdb_size
• htdb_getnum
• htdb_defined
• htdb_equal

Used to access and manipulate objects which have been stored according to the array convention.

• htdb_setarrayval
• htdb_getarrayval
• htdb_setarrayint
• htdb_getarrayint

Used to access and manipulate objects which have been stored according to the pointer convention.

• htdb_getptrval
• htdb_getptrint
• htdb_setptrval
• htdb_setptrint

Used to access and manipulate objects which have been stored according to the HTDB object convention.

• htdb_getobjval
• htdb_getobjint
• htdb_setobjvarg
• htdb_setobjval
• htdb_setobjint

These lower-level functions are used internally by the String, Array, Pointer and HTDB objects and may be useful by the programmer directly.

• htdb_getarrayname
• htdb_getobjdyname
• htdb_getobjname
• htdb_getptrdyname

In the string convention, object keys (names) are of the form:

key

int htdb_setint(char *key, int val)
	used to store an integer value in the object named key. returns the value stored. note that the internal storage primative for HTDB objects is actually strings, so what is stored here is a strings representation of an integer, not an interger value.
I	input  printf("%d\n", htdb_setint("tmpval", "4")); output  4
II	input  printf("setting 'tmpval' to '3'\n");   htdb_setint("tmpval", 3);   printf("equal to 1? ");   if (htdb_getint("tmpval") == 1)    printf("FALSE\n");   printf("equal to 3? ");   if (htdb_getint("tmpval") == 3)    printf("TRUE\n"); output  setting 'tmpval' to '3'   equal to 1? FALSE   equal to 3? TRUE

int htdb_getint(char *key)
	used to retrieve an integer value in the object named key. returns the value stored, or zero.
I	input  htdb_setint("tmpval", "4");  printf("%d\n", htdb_getint("tmpval")); output  4
II	input  printf("%d\n", htdb_getint("aValuesWhichDoesNotExist")); output  0

char * htdb_setval(char *key, char *val)
	used to store a copy of a string in the object named key. returns the value stored.
I	input  printf("%s\n", htdb_setval("tmpval", "hello world")); output  hello world
II	input  htdb_setval("tmpval", "hello world"); output   notes result is simply shoved into in-memory storage

char * htdb_setvarg(char *key, char *fmt, ...)
	a variable-argument version of htdb_setval.
I	input  printf("%s\n", htdb_setvarg("tmpval", "the answer is %d, dude", 3)); output  the answer is 3, dude

char * htdb_getval(char *key)
	used to retrieve a string stored in the object named key. returns the value stored, or an empty string. htdb_getval() is probably the most-used function of the CGI programmer.
I	input  htdb_setval("tmpval", "hello world");  printf("%s\n", htdb_getval("tmpval")); output  hello world
II	input  printf("%s\n", htdb_getval("anObjectWhichDoesNotExist")); output

void * htdb_setbin(char *key, void *val, off_t size)
	shoves binary into storage at key. returns a pointer to the stored value. the data is not copied - it is stored as-is. being a void * type, it is the programmer's responsibility to deal with the "real" type of the data stored.

void * htdb_getbin(char *key)
	used to retrieve binary data stored at key. being a void * type, it is the programmer's responsibility to deal with the "real" type of the data stored.

int htdb_checkval(char *key)
	used to determine whether an object exists (has size). returns the size, or zero if the object does not exist. effectively, this is a strlen() on a looked-up value. naturally only works on strings. to determine the size of binary stored data, use htdb_size().

int htdb_size(char *key)
	returns the number of bytes in an object. returns zero if the object does not exist. uses an internal structure value to determine object size, so can be used to determine number of bytes in binary data.
I	input  htdb_setval("tmpval", "hello world");  printf("%d\n", htdb_size("tmpval")); output  11
II	input  htdb_setval("tmpval", "3.14");  printf("%d\n", htdb_size("tmpval")); output  4
III	input  printf("%d\n", htdb_size("anObjectWhichDoesNotExist")); output  0
IV	input  htdb_setint("tmpval", "666");  printf("%d\n", htdb_size("tmpval")); output  3 notes note that even though the stored value was an integer, it was actually stored as a string, so the size of the object is the number of bytes used to hold the value.

int htdb_getnum(char *key)
	synonym for htdb_getint()

char * htdb_defined(char *key)
	synonym for htdb_getval(()

int htdb_equal(char *key, char *value)
	used to determine whether the looked-up value of key is equal to value. is case insensitive in the comparison. returns 0 if either the key or the value is empty or if they are not equal, else returns 1. this function is simply shorthand for (strcasecmp(htdb_getval(key), value) == 0) this function is most often used to determine the correct "state" to be in when programming CGIs.
I	input  htdb_setval("tmpval", "hello");  if (htdb_equal("tmpval", "world"))   printf("WORLD");  else if (htdb_equal("tmpval", "hello"))   printf("HELLO"); output  HELLO
II	input  if (htdb_equal("cgi->request_method", "GET"))   printf("access method was GET");  else if (htdb_equal("cgi->request_method", "POST"))   printf("access method was POST");  else   printf("access method was UNKNOWN"); output   notes the behavior of this code snippet will depend upon the context in which the web page was called.

In the array convention, object keys (names) are of the form:

key[index]

char * htdb_setarrayval(char *key, int index, char *fmt, ...)
	stores the variable-arguments format string value into the object named key[index]. returns a pointer to the stored string.

char * htdb_getarrayval(char *key, int index)
	fetches the string stored at the object named key[index], or an empty string if no such object exists.

int htdb_setarrayint(char *key, int index, int value)
	stores the string representation of an integer, value, at the object named key[index]. returns the stored string evaluated as an integer.

int htdb_getarrayint(char *key, int index)
	fetches the integer stored at the object named key[index], or 0 if no such object exists.

In the pointer convention, object keys (names) are of the form:

key->field

char * htdb_getptrval(char *key, char *field)
	fetches the string at the object named key->field, or an empty string if no such object exists.

int htdb_getptrint(char *key, char *field)
	fetches the integer at the object named key->field, or 0 if no such object exists.

char * htdb_setptrval(char *key, char *field, char *value)
	stores a copy of the string value at the object named key->field. returns a pointer to the stored string.

int htdb_setptrint(char *key, char *field, int value)
	stores the string representation of an integer, value, at the object named key->field. returns the stored string evaluated as an integer.

In the HTDB object convention, object keys (names) are of the form:

key[index]->field

char * htdb_getobjval(char *key, int index, char *field)
	fetches the string at the object named key[index]->field, or an empty string if no such object exists.

int htdb_getobjint(char *key, int index, char *field)
	fetches the integer at the object named key[index]->field, or 0 if no such object exists.

char * htdb_setobjvarg(char *key, int index, char *field, char *fmt, ...)
	stores the variable-arguments format string value into the object named key[index]->field. returns a pointer to the stored string.

char * htdb_setobjval(char *key, int index, char *field, char *value)
	stores value into the object named key[index]->field. returns a pointer to the stored string.

int htdb_setobjint(char *key, int index, char *field, int value)
	stores the string representaion of the integer value into the object named key[index]->field. returns an integer of the value stored.

The general purpose of the functions in this section is to derive object names in a standard format. There are versions which return static memory, and re-entrant versions which return dynamic memory.