bbslib::db_i

作者: 遊手好閒的石頭成 <shirock@mail.educities.edu.tw>
日期: 2001年6月28日

Header files

#include <bbslib/db_i.h>

也可以直接引入 <bbslib.h> ， bbslib.h 會將引入所有 bbslib 的 header files 。

Struct

• DBT

typedef struct {
	void* data;
	size_t size;
} DBT;

Functions

• dbi_open
• dbi_close
• dbi_get
• dbi_exists
• dbi_put
• dbi_delete
• dbi_firstkey
• dbi_nextkey
• dbi_firstdata
• dbi_nextdata
• dbi_get2
• dbi_sync
• dbi_dbtfree
• dbi_dbtnfree
• dbi_errno
• dbi_strerror

dbi_open()/dbi_close()

DBF dbi_open(char*name, int type, int mode, const void*reverse);

void dbi_close(DBF dbf);

name - 資料庫檔名。
type - DBI_READER or DBI_WRITER
若資料庫不存在，且為 writer 時，則會建立之。 可以再加上 DBI_BTREE 指定資料庫的儲存型態，但是只在 底層資料庫管理函數有支援時，才有作用。
mode - 資料庫建立時的檔案讀寫權限，同 open() 的意義，一般用 0644
reverse - 保留給未來使用
RC: success(db handler), fault(NULL)
See also: dbopen(3), gdbm(3)

dbi_get()

DBT dbi_get(DBF dbf, const DBT* key);

取得的 data 內容，其記憶體空間由函數主動配置，當 不在使用時，需呼叫 dbi_dbtfree() 或 dbi_dbtnfree() 將其釋放。
ps. 這其實跟底層資料庫函數的實作方式有關，如果底層 資料庫函數是 db 的話，則 dbi_dbtfree() 只是個空函數， 什麼也不做，因為 data 的空間，是由 db 自行維護的。
RC: DBT, if the key doesn't exist the DBT.data will be NULL.

dbi_exists()

int dbi_exists(DBF dbf, const DBT* key);

RC: exists(1, YEA), not exists(0, NA)

dbi_put()

int dbi_put(DBF dbf, DBT* key, const DBT* data, int flags);

flags - DBI_INSERT or DBI_REPLACE
DBI_INSERT 只加入新資料，若 key 已存在，則不儲存並回傳 DBI_EXISTED。
DBI_REPLACE 當 key 不存在時，加入新資料，否則替代原有內容。
RC: success(0), fault(-1), the key exists(1, DBI_EXISTED)

dbi_delete()

int dbi_delete(DBF dbf, const DBT* key);

RC: success(0), fault(-1)

dbi_firstkey()/dbi_nextkey()

DBT dbi_firstkey(DBF dbf);

DBT dbi_nextkey(DBF dbf, DBT* prevkey);

回傳內容與 dbi_get() 一樣；當不使用時，也需呼叫 dbi_dbtfree() 釋放。
注意， dbi_nextkey() 不會主動釋放 prevkey 的空間。

dbi_firstdata()/dbi_nextdata()

int dbi_firstdata(DBF dbf, DBT* key, DBT* data);

int dbi_nextdata(DBF dbf, DBT* key, DBT* data);

取得的內容會存在 key 及 data 中，當不使用時，需呼叫 dbi_dbtfree() or dbi_dbtnfree() 釋放。
注意， dbi_nextdata() 的參數 key 必須傳入前一個 key 的內容， 而後其將下一個 key 的內容存入傳回。 但 dbi_nextdata() 不會 主動釋放 key 及 data 原先(即前一個資料)內容所用的空間。
RC: success(0), fault(-1), if key not found(1, DBI_NOTFOUND)

dbi_get2()

DBT dbi_get2(DBF dbf, DBT* key, int flags);

新的記錄鍵值會被存入 key 中，函數的傳回值是記錄的資料內容。 DBI_FIRST - 第一筆記錄。
DBI_NEXT - 下一筆記錄，參數 key 須為前一筆記錄的鍵值；函數會將 新的記錄鍵值存入。
DBI_CURSOR - 傳回與 key 相符的記錄。若資料庫型態為 BTREE 時，則 會傳回大於或等於要求鍵值之最小鍵值記錄 - 最接近值。
RC: DBT, if the key doesn't exist the DBT.data will be NULL.

dbi_sync()

void dbi_sync(DBF dbf);

dbi_dbtfree()/dbi_dbtnfree()

void dbi_dbtfree(dbt);

void dbi_dbtnfree(int n, ...);

釋放 DBT 所佔用的記憶體空間。

dbi_errno/dbi_strerror()

int dbi_errno;

char*dbi_strerror(int dbi_errno);

The TIP Project

Short URL: http://fbtip.tsx.org/
Group: http://groups.yahoo.com/list/firebird-tip
Mailing list: firebird-tip@yahoogroups.com