コンビニエンス C++API

コンビニエンスAPIはベーシック C++APIをboostライブラリとテンプレートでラップし、安全で覚えやすく少ないコードでパフォーマンスを落とさずに操作できるように設計されたAPIです。特に理由がなければ、このコンビニエンス C++APIを使用することをお奨めします。

コンビニエンスAPIは標準APIを元に trdboostapi.h のヘッダーファイルのみで提供されます。

詳細

メモリー管理

サーバーアプリケーションではメモリーリークが発生すると深刻な問題になることがあります。コンビニエンスAPIではdatabaseオブジェクトとtableオブジェクトはboost::shared_ptrでラップした database_ptrとtable_ptrを使用します。
shared_ptrは循環参照すると破棄されない問題がありますが、API内での循環参照はありません。

例外対応

コンビニエンスAPIでは例外エラーが発生すると例外をスローします。開始と終了が対である必要があるオペレーション (transaction snapshot bulkInsert)は、自動オプジェクトを使用して例外によって関数を抜ける際に自動で終了オペレーションが呼ばれるようにします。
例外処理の実際はサンプルコードを参照してください。

データベースオブジェクトの作成と破棄

データベースオブジェクトの作成は以下のように行います。

　
        database_ptr db = createDatabaseObject();
　       

dbオブジェクトが破棄はdatabase_ptrの参照カウントによって自動で行われます。

データベースのオープンとクローズ

データベースのオープンは、 openDatabase() 関数に connectParamsオブジェクトを作成してそれを渡します。

　
        connectParams prams(_T("tdap"), _T("localhost"), _T("test"), _T("test"));
        prams.setMode(TD_OPEN_EXCLUSIVE);
        openDatabase(db, prams);
　       

クローズはdatabase_ptrによって、dbオブジェクトが破棄される際に自動で行われます。

テーブルのオープンとクローズ

テーブルのオープンは、 openTable() 関数に database_ptrオブジェクトとテーブル名を渡します。

　
        table_ptr tb = openTable(db, _T("user"));
　       

クローズはtable_ptrによって、tbオブジェクトが破棄される際に自動で行われます。

インデックスを使ったカーソルの移動

カーソルの移動は、 readIndex_v() 関数に table_ptrと移動の種類、キー番号、キー値を渡します。
成功すると indexIteratorが返ります。
indexIteratorは ++()を使って次のレコードへ順次移動できます。降順に移動したい場合は readIndexRv_v() 関数を使用して indexRvIteratorを取得します。
キー値は、オーバーロードによって８個まで可変で指定できます。キー値の型は table::setFV()関数でオーバーロードされた bool, short, int, __int64, float, double, const TCHAR*型が使用できます。
移動後は indexIteratorの状態が indexIterator::eos でないか確認します。indexIterator::eosはレコードの最後に達したか、一致するレコードがなかったことを示します。

　
        static char const keynum_group = 1;
        indexIterator it = readIndex_v(tb, eSeekGreaterOrEqual, keynum_group, 1);
        while (it != indexIterator::eos)
        {
                //some
                ++it;
        }
　       

サーバーフィルターを使った複数レコードの取得

サーバーフィルターを使用すると、一回の通信で複数のレコードを取得できるため、通信回数の削減によってパフォーマンスを向上できます。複数のレコードにアクセスする場合はなるべくフィルターを使用して取得します。
最初に readIndex_v()関数を使ったカーソルを確立するところは前記「インデックスを使ったカーソルの移動」と同じです。このあと、 getFindIterator()関数にindexIteratorとフィルター文字列を渡して findIteratorを取得します。
findIteratorは ++()を使って次のレコードへ順次移動できます。降順に移動したい場合は indexRvIteratorを渡してfindRvIteratorを取得します。移動後は findIteratorの状態が findIterator::eos でないか確認します。findIterator::eosはレコードの最後に達したことを示します。

　
        static char const keynum_group = 1;
        indexIterator it = readIndex_v(tb, eSeekGreaterOrEqual, keynum_group, 3);   
        findIterator itsf = getFindIterator(it, _T("group = 3"));
        while (itsf != findIterator::eos)
        {
                //some
                ++itsf;
                
        }
　

クライアントフィルターを使ったレコードの除外

サーバーフィルターを有効に使うには、テーブルがフルスキャンされないようにインデックスフィールドを条件に含めるなどして一定の範囲を取得するようにします。その際に不要なレコードを除外可能であればサーバーフィルターに指定しますが、条件によっては指定できない場合もあります。このような場合は一旦クライアントに取得した上でクライアント側でフィルタリングします。
フィルタリングはユーザー作成の関数または関数オブジェクトにて行います。関数でのフィルタリングはどんな条件でのフィルタリングできるようになります。
手順は、最初「サーバーフィルターを使った複数レコードの取得」と同様です。その後、filterdFindIteratorのコンストラクタにfindIterator渡して構築します。 filterdFindIteratorは ++()を使って次のレコードへ順次移動できます。移動後は filterdFindIteratorの状態が filterdFindIterator::eos でないか確認します。filterdFindIterator::eosはレコードの最後に達したことを示します。
filterdイテレータはFindIteratorだけでなく、indexIterator他からも作成できます。

　       
static const short fd_name = 1;
static char const keynum_group = 1;
int isGroup3(const fields& fds)
{    
        return  (_tcsstr(fds[fd_name].c_str(), "suzuki")!=NULL)? filter_validate_value  
                : filter_validate_block;
}
void filterdRead()
{
        
        indexIterator it = readIndex_v(tb, eSeekGreaterOrEqual, keynum_group, 3);   
        findIterator itsf = getFindIterator(it, _T("group = 3"); 
        filterdIndexIterator itcf(itsf, isGroup3);    
        while (itcf != filterdIndexIterator::eos)
        {
                //some
                ++itcf;
        }
}
　

その他のオペレーション

その他 insertRecord() updateRecord() deleteRecord()などのオペレーションはサンプルコードのコンビニエンスAPIを使ったサンプルや、namespace bzs::db::protocol::tdap::client コンビニエンスC++APIグループのリファレンスを参考にしてください。