1. 打開Duplicate keys的功能。在ham_create_ex or ham_env_create_db中將flags參數(shù)設(shè)置為HAM_ENABLE_DUPLICATES。
ham_create_ex(db, "test.db", HAM_ENABLE_DUPLICATES, 0664, 0)
2. 插入重復(fù)數(shù)據(jù)。在調(diào)用ham_insert or ham_cursor_insert時(shí)將flags參數(shù)設(shè)置為HAM_DUPLICATE。通過ham_cursor_insert可以改變插入數(shù)據(jù)的順序，如HAM_DUPLICATE_INSERT_BEFORE, HAM_DUPLICATE_INSERT_AFTER, HAM_DUPLICATE_INSERT_FIRST or HAM_DUPLICATE_INSERT_LAST，ham_insert的缺省行為是HAM_DUPLICATE_INSERT_LAST。
3. 遍歷重復(fù)keys。ham_find(總是返回重復(fù)key的第一條記錄)，然后再通過ham_cursor_move函數(shù)進(jìn)行duplicate keys的遍歷，HAM_SKIP_DUPLICATES標(biāo)志將跳過后面的重復(fù)鍵，HAM_ONLY_DUPLICATES標(biāo)志將只是遍歷重復(fù)鍵。
4. 替換重復(fù)keys，ham_cursor_overwrite或者ham_insert函數(shù)的flags參數(shù)設(shè)置為HAM_OVERWRITE。
5. 獲取重復(fù)鍵的數(shù)量，ham_cursor_get_duplicate_count，對(duì)于非重復(fù)鍵，該函數(shù)返回1，否則返回重復(fù)鍵的記錄數(shù)。
6. 刪除重復(fù)鍵，ham_erase將刪除該重復(fù)鍵的所有記錄，ham_cursor_erase只是刪除當(dāng)前cursor指向的記錄。
7. 給重復(fù)鍵排序，在創(chuàng)建數(shù)據(jù)庫的時(shí)候同時(shí)指定這兩個(gè)flags，HAM_SORT_DUPLICATES | HAM_ENABLE_DUPLICATES。
同時(shí)安裝一下回調(diào)函數(shù)
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);
以下函數(shù)為回調(diào)函數(shù)安裝函數(shù)。
ham_status_t ham_set_duplicate_compare_func(ham_db_t *db, ham_duplicate_compare_func_t foo);
事物：
1. 同一數(shù)據(jù)庫在同一時(shí)刻只能存在同一個(gè)事物，包括隱性事物也不能和顯示事物同時(shí)存在，以下函數(shù)為隱性事物ham_insert, ham_find, ham_erase, ham_cursor_create和ham_env_erase_db。
2. 在ENV或者DB中打開事物功能，在創(chuàng)建環(huán)境或者數(shù)據(jù)庫的時(shí)候?qū)?span lang="EN-US">flag參數(shù)設(shè)置為HAM_ENABLE_TRANSACTIONS。如下：
ham_env_create_ex(env, "test.db", HAM_ENABLE_TRANSACTIONS, 0644, 0)
3. 開始一個(gè)新事物：ham_status_t ham_txn_begin(ham_txn_t **txn, ham_db_t *db, ham_u32_t flags)
4. 應(yīng)用事物：以下四個(gè)函數(shù)可以和事物一起使用。
* ham_insert
* ham_erase
* ham_find
* ham_cursor_create
注意：ham_cursor_create函數(shù)創(chuàng)建的游標(biāo)將和attached的事物共享相同的生命周期，因此在commit或者abort事物之前，必須先close游標(biāo)。
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)
數(shù)據(jù)操作和游標(biāo)
1. 設(shè)置自定義比較函數(shù)。
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，插入數(shù)據(jù)。 當(dāng)flags參數(shù)設(shè)置為HAM_DUPLICATE時(shí)，如果該key已經(jīng)存在，則插入重復(fù)鍵。flags為HAM_OVERWRITE時(shí)，如果該key已經(jīng)存在則覆蓋它。flags如果沒有被指定，當(dāng)key重復(fù)時(shí)，insert操作將報(bào)錯(cuò)。注意，insert之前需要將key和value這兩個(gè)結(jié)構(gòu)體先初始化為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，查找數(shù)據(jù)。基于指定的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的內(nèi)存空間是由hamsterdb內(nèi)部分配，因此只要在調(diào)用任何hamsterdb的任何函數(shù)，該數(shù)據(jù)可能會(huì)被覆蓋，如果打算自行分配內(nèi)存，如下:
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) {
// ...
}
這里內(nèi)存分配是否可以容納所有record數(shù)據(jù)，需要自行判斷。
4. hamsterdb可以讀取和替換已存在record的partial data。
5. hamsterdb針對(duì)ham_find or ham_cursor_find兩個(gè)函數(shù)都提供了近似查找的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. 游標(biāo)操作相關(guān)的函數(shù)：
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關(guān)閉：
1) ham_status_t ham_close(ham_db_t *db, ham_u32_t flags); 該函數(shù)只是關(guān)閉數(shù)據(jù)庫，可以重新打開。
2) ham_status_t ham_delete(ham_db_t *db); 該函數(shù)將刪除ham_new創(chuàng)建的數(shù)據(jù)庫句柄，以防止內(nèi)存泄露。