1. 打開Duplicate keys的功能。在ham_create_ex or ham_env_create_db中將flags參數設置為HAM_ENABLE_DUPLICATES。
ham_create_ex(db, "test.db", HAM_ENABLE_DUPLICATES, 0664, 0)
2. 插入重復數據。在調用ham_insert or ham_cursor_insert時將flags參數設置為HAM_DUPLICATE。通過ham_cursor_insert可以改變插入數據的順序，如HAM_DUPLICATE_INSERT_BEFORE, HAM_DUPLICATE_INSERT_AFTER, HAM_DUPLICATE_INSERT_FIRST or HAM_DUPLICATE_INSERT_LAST，ham_insert的缺省行為是HAM_DUPLICATE_INSERT_LAST。
3. 遍歷重復keys。ham_find(總是返回重復key的第一條記錄)，然后再通過ham_cursor_move函數進行duplicate keys的遍歷，HAM_SKIP_DUPLICATES標志將跳過后面的重復鍵，HAM_ONLY_DUPLICATES標志將只是遍歷重復鍵。
4. 替換重復keys，ham_cursor_overwrite或者ham_insert函數的flags參數設置為HAM_OVERWRITE。
5. 獲取重復鍵的數量，ham_cursor_get_duplicate_count，對于非重復鍵，該函數返回1，否則返回重復鍵的記錄數。
6. 刪除重復鍵，ham_erase將刪除該重復鍵的所有記錄，ham_cursor_erase只是刪除當前cursor指向的記錄。
7. 給重復鍵排序，在創建數據庫的時候同時指定這兩個flags，HAM_SORT_DUPLICATES | HAM_ENABLE_DUPLICATES。
同時安裝一下回調函數
typedef int HAM_CALLCONV (*ham_duplicate_compare_func_t)(ham_db_t *db,const ham_u8_t *lhs, ham_size_t lhs_length,const ham_u8_t *rhs, ham_size_t rhs_length);
以下函數為回調函數安裝函數。
ham_status_t ham_set_duplicate_compare_func(ham_db_t *db, ham_duplicate_compare_func_t foo);
事物：
1. 同一數據庫在同一時刻只能存在同一個事物，包括隱性事物也不能和顯示事物同時存在，以下函數為隱性事物ham_insert, ham_find, ham_erase, ham_cursor_create和ham_env_erase_db。
2. 在ENV或者DB中打開事物功能，在創建環境或者數據庫的時候將flag參數設置為HAM_ENABLE_TRANSACTIONS。如下：
ham_env_create_ex(env, "test.db", HAM_ENABLE_TRANSACTIONS, 0644, 0)
3. 開始一個新事物：ham_status_t ham_txn_begin(ham_txn_t **txn, ham_db_t *db, ham_u32_t flags)
4. 應用事物：以下四個函數可以和事物一起使用。
* ham_insert
* ham_erase
* ham_find
* ham_cursor_create
注意：ham_cursor_create函數創建的游標將和attached的事物共享相同的生命周期，因此在commit或者abort事物之前，必須先close游標。
5. 提交和放棄
ham_status_t ham_txn_commit(ham_txn_t *txn, ham_u32_t flags)
ham_status_t ham_txn_abort(ham_txn_t *txn, ham_u32_t flags)
數據操作和游標
1. 設置自定義比較函數。
static int my_int_compare(ham_db_t *db, ham_u8_t *lhs, ham_size_t lhs_size, ham_u8_t *rhs, ham_size_t rhs_size) {
int nlhs=*(int *)lhs;
int nrhs=*(int *)rhs;
if (nlhs<nrhs) return -1;
if (nrhs>nlhs) return +1;
return 0;
}
int main(int argc, char **argv)
{
ham_status_t st;
ham_db_t *db;
if ((st=ham_new(&db))!=HAM_SUCCESS) {
printf("ham_new failed: %d (%s)\n", st, ham_strerror(st));
exit(-1);
}
if ((st=ham_set_compare_func(db, my_int_compare))!=HAM_SUCCESS) {
printf("ham_set_compare_func failed: %d (%s)\n", st, ham_strerror(st));
exit(-1);
}
if ((st=ham_create_ex(db, "test.db", 0, 0664))!=HAM_SUCCESS) {
printf("ham_create_ex failed: %d (%s)\n", st, ham_strerror(st));
exit(-1);
}
// ...
}
2. ham_insert，插入數據。 當flags參數設置為HAM_DUPLICATE時，如果該key已經存在，則插入重復鍵。flags為HAM_OVERWRITE時，如果該key已經存在則覆蓋它。flags如果沒有被指定，當key重復時，insert操作將報錯。注意，insert之前需要將key和value這兩個結構體先初始化為0.
void example_of_insert() {
ham_key_t key;
ham_record_t record;
memset(&key, 0, sizeof(key));
memset(&record, 0, sizeof(record));
.
key.data="color";
key.size=strlen(key.data)+1; /* +1 for the terminating zero-byte */
record.data="green";
record.size=strlen(record.data)+1; /* +1 for the terminating zero-byte */
.
if ((st=ham_insert(db, NULL, &key, &record, 0))!=HAM_SUCCESS) {
printf("ham_insert failed: %d (%s)\n", st, ham_strerror(st));
exit(-1);
}
}
3. ham_find，查找數據。基于指定的key查找。
void example_of_find() {
ham_status_t st;
ham_key_t key;
ham_record_t record;
memset(&key, 0, sizeof(key));
memset(&record, 0, sizeof(record));
key.data="color";
key.size=strlen(key.data)+1; /* +1 for the terminating zero-byte */
.
if ((st=ham_find(db, NULL, &key, &record, 0))!=HAM_SUCCESS) {
printf("ham_find failed: %d (%s)\n", st, ham_strerror(st));
exit(-1);
}
}
注意：這里的record.data的內存空間是由hamsterdb內部分配，因此只要在調用任何hamsterdb的任何函數，該數據可能會被覆蓋，如果打算自行分配內存，如下:
memset(&record, 0, sizeof(record));
record.flags=HAM_RECORD_USER_ALLOC;
record.data=malloc(6);
.
if ((st=ham_find(db, NULL, &key, &record, 0))!=HAM_SUCCESS) {
// ...
}
這里內存分配是否可以容納所有record數據，需要自行判斷。
4. hamsterdb可以讀取和替換已存在record的partial data。
5. hamsterdb針對ham_find or ham_cursor_find兩個函數都提供了近似查找的flag，如ham_find(db, NULL, &key, &record, HAM_FIND_NEAR_MATCH)。
* HAM_FIND_EXACT_MATCH: This is the default setting. If exactly this key exists then the record of this key will be returned.
* HAM_FIND_LT_MATCH ‘find’ flag ‘Less Than’: retrieves the last record with a key which is less than the specified key.
* HAM_FIND_GT_MATCH ‘find’ flag ‘Greater Than’: retrieves the first record with a key which is greater than the specified key.
* HAM_FIND_LEQ_MATCH ‘find’ flag ‘Less or EQual’: retrieves the last record with a key which is less or equal than the specified key.
* HAM_FIND_GEQ_MATCH ‘find’ flag ‘Greater or Equal’: retrieves the first record with a key which is greater or equal than the specified key.
* HAM_FIND_NEAR_MATCH ‘find’ flag ‘Any Near Or Equal’: retrieves the record which’ key matches the specified key and when such a key is not available hamsterdb will retrieve either the last record which’ key is less than the specified key or the first record which’ key is larger than the specified key, whichever of these records is located first.
6. 游標操作相關的函數：
1) ham_status_t ham_cursor_create(ham_db_t *db, ham_txn_t *txn, ham_u32_t flags, ham_cursor_t **cursor);
2) ham_status_t ham_cursor_move(ham_cursor_t *cursor, ham_key_t *key, ham_record_t *record, ham_u32_t flags);
3) ham_status_t ham_cursor_insert(ham_cursor_t *cursor, ham_key_t *key, ham_record_t *record, ham_u32_t flags);
4) ham_status_t ham_cursor_find(ham_cursor_t *cursor, ham_key_t *key, ham_u32_t flags);
5) ham_status_t ham_cursor_overwrite(ham_cursor_t *cursor, ham_record_t *record, ham_u32_t flags);
6) ham_status_t ham_cursor_erase(ham_cursor_t *cursor, ham_u32_t flags);
7) ham_status_t ham_cursor_clone(ham_cursor_t *src, ham_cursor_t **dest);
8) ham_status_t ham_cursor_close(ham_cursor_t *cursor);
7. hamsterdb關閉：
1) ham_status_t ham_close(ham_db_t *db, ham_u32_t flags); 該函數只是關閉數據庫，可以重新打開。
2) ham_status_t ham_delete(ham_db_t *db); 該函數將刪除ham_new創建的數據庫句柄，以防止內存泄露。