Transactd 開発者ガイド

サポートする言語

現在、Transactd クライアントを用いたアプリケーション開発を行える言語は、以下の通りです。

(Java、Pythonなどを順次対応予定)

マルチスレッドサポート

すべての言語のクライアントにおいて、接続データベース単位でのマルチスレッドをサポートしています。

あるデータベースとそれに付随するテーブルなどのオブジェクトグループは、1つのスレッドからは安全に操作できます。 言い換えると、スレッドごとに専用のデータベースオブジェクトを利用すれば安全に操作できます。 その際、個々のデータベースオブジェクトのconnectメソッドオプションで専用のTCPコネクションを張るように指示してください。

Apache 2のworkerMPMやIISのISAPIエクステンションからも安全に実行することができます。

Ruby クライアント

Ruby 1.9系 および Ruby 2.0系 用のRubyGemを用意しています。

仕様と制限

RubyのクライアントはC++のAPIをラップした形になっており、以下の点を除いてC++のAPIと同じです。

C++ APIに対するRubyクライアントの相違点(2015/06/09)
全般
  • クラス名の先頭は大文字(例:databaseDatabase
  • 定数の先頭は大文字(例:ft_integerFt_integer
  • ネストした名前空間はなく、すべてがTransactd名前空間に置かれる
    (例:bzs::db::protocol::tdap::client::databaseTransactd::Database
終了処理
  • メモリの解放はRubyのGCによって行われるため、明示的なメモリ解放処理は不要。 database::releaseおよびnstable::releaseは存在しない。
  • メモリ解放時にコネクションの切断も行われるが、明示的に切断処理を記述することを推奨する。 Database.closeおよびTable.closeを使用する。
    db.open(uri, 0, Transactd::TD_OPEN_NORMAL, '', '') # open database
    tb = db.openTable('user', Transactd::TD_OPEN_NORMAL, true)  # open table
    # ... some operations ...
    tb.close() # close table
    db.close() # close database
    
文字コード
  • Windows上であってもマルチバイトに限定され、Unicodeは使用できない。 (tdclcpp_*m*.dllを使用する)
  • ソースコードファイルのエンコーディングにはUTF-8を使用する。
  • 使用可能な文字コードはSDKドキュメントの文字コードの項目を参照。
整数
  • データベースに格納されたUNSIGNED BIGINT型の値について、63bitまでの整数はTable::getFV64Field::i64メソッドで取得できます。それ以上の値は、バイト列を符号付64bitの値とみなした数値が取得されます。
  • Table::getFVstrField::strメソッドを使用すると、10進数の文字列表現として取得できます。
メソッドの
変更
  • keydef::segments[]へのアクセスをKeydef::segmentメソッドに変更。
  • tabledef::fieldDefs[]へのアクセスをTabledef::fieldDefメソッドに変更。
  • tabledef::keyDefs[]へのアクセスをTabledef::keyDefメソッドに変更。
  • btrVersions::versions[]へのアクセスをBtrVersions::versionメソッドに変更。
  • BtrTimeStamp::toString, btrdtoa, btrttoa, btrstoaのシグネチャを変更。
    nowdate = Transactd::getNowDate()
    # 引数の char* が削除され、文字列を返す。
    nowdate_str  = Transactd::btrdtoa(nowdate, true)
  • Recordクラスにオブジェクトからフィールドの値をセットするset_value_by_objectを追加。
  • RecordsetクラスとTableクラスにfetchModeを追加。詳細は PHPとRubyにおける行取得の追加機能を参照。
  • RecordsetクラスにgetRecordを追加。getRecordfetchModeの値に関わらず recordオブジェクトを返します。
  • TableクラスにgetRowを追加。getRowfieldsメソッドのエイリアスです。
  • Tableクラスに、オブジェクトをパラメータにとりプライマリキーでCRUDを行うオペレーション table::save_by_objecttable::update_by_object table::insert_by_objecttable::read_by_objecttable::delete_by_objectを追加。
  • Tableクラスに、キーの値でレコードを移動するseek_key_value(keyValues)メソッドを追加。このメソッドは以下の内容をエクステンション内で処理します。
    def seek_key_value(keyValues)
      tb.clearBuffer
      i = 0
      for value in keyValues
        tb.setFV(keyseg(i), value)
        i += 1
      end
      tb.seek
      return tb.stat
    end
    
  • 各クラスおよびモジュールのメソッド名とプロパティ名について、以下の規則に従った別名を追加しました。
    • camelCase形式の名前にsnake_case形式の別名を追加。
    • is_XXXという名前で、戻り値が真偽値のものにis_XXX?の別名を追加。
    • set_XXXという名前で、引数が1つかつ戻り値がないものにXXX=の別名を追加。
未対応の
機能
  • onCopyData,onDeleteRecordのコールバック関数機能は未対応(今後対応予定)
  • table::insertBookmarksは非対応。
  • fielddefs::addAllFieldsは非対応。
  • fielddefs::appendは非対応。
  • fielddefs::addSelectedFieldsは非対応。
  • fielddefs::addAliasNameは非対応。
  • fielddef::blobLenBytesは非対応。
  • fielddef::varLenBytesは非対応。
  • nstable::statsは非対応。
  • table::optionalDataは非対応。
  • table::setOptionalDataは非対応。
  • database::optionalDataは非対応。
  • database::setOptionalDataは非対応。
  • connection::record::statusは非対応。
  • tdap::getFilterLogicTypeCodeは非対応。

COM クライアント

COMはWindowsでのみ使用可能です。

仕様と制限

ActiveX(COM)はC++のAPIをラップした形になっており、以下の点を除いてC++のAPIと同じです。

C++ APIに対するActiveX(COM)インターフェースの相違点(2015/06/09)
全般
  • クラス名の先頭は大文字(例:databaseDatabase
  • メソッド名の先頭は大文字(例:openTableOpenTable
  • getter関数とsetter関数が対であるメソッドは、メンバー変数のように = で参照と値の設定を行う
    (例:table.setUsePadChar(true);table.UsePadChar = true;
    value = table.usePadChar();value = table.UsePadChar;
  • ネストした名前空間はなく、すべてがtransactd名前空間に置かれる
    (例:bzs::db::protocol::tdap::client::databasetransactd.Database
定数(enum)
  • スクリプト言語で使用する場合は、スクリプト内で定義する。
  • タイプライブラリが使えるIDEでは、eXxx名前空間でアクセス可能。(例:eStatus.STATUS_SUCCESS
終了処理
  • メモリの解放はCOMによって行われるため、明示的なメモリ解放処理は不要。 database::releaseおよびnstable::releaseは存在しない。
  • メモリ解放時にコネクションの切断も行われるが、明示的に切断処理を記述することを推奨する。 Database.CloseおよびTable.Closeを使用する。
    db.Open(uri, TYPE_BDF, OPEN_NORMAL); // open database
    var tb = db.OpenTable('user', TD_OPEN_NORMAL);  // open table
    // ... some operations ...
    tb.Close(); // close table
    db.Close(); // close database
    
文字コード

Unicodeに限定され、マルチバイトは使用できない。(tdclcpp_*****_**u_*_*.dllを使用する)

整数
  • 符号付32bitの範囲に収まる整数はtable::GetFVintfield::Iメソッドで取得できます。
  • その範囲に収まらない整数は、Table::GetFVstrField::Strメソッドを使用すると、10進数の文字列表現として取得できます。
メソッドの
変更
  • Databaseオブジェクト作成方法
    var db = new ActiveXObject('transactd.Database');
  • keydef::segments[]へのアクセスをKeydef.Segmentsメソッドに変更。
  • tabledef::fieldDefs[]へのアクセスをTabledef.FieldDefメソッドに変更。
  • tabledef::keyDefs[]へのアクセスをTabledef.KeyDefメソッドに変更。
  • btrVersionsクラスをTdVersionクラスに変更。
  • QueryBaseオブジェクトの作成方法
    var query = new ActiveXObject('transactd.query');
  • QueryBase::addLogicQueryBase::WhereQueryBase::AndQueryBase::Orに置き換え。コード例:
    query.Where("id", ">=", 1).And("id", "<", 3).Or("name", "=", "akio");
  • QueryBase::addFieldQueryBase::Selectに置き換え。1回で11個まで記述可能。 それ以上の場合は再度Selectを呼ぶことで追加できる。コード例:
    query.Select("id", "name", "email");
  • QueryBase::addSeekKeyValueQueryBase::AddInValueに名前を変更。
  • QueryBase::Inメソッドを追加。1回で11個まで記述可能。 それ以上の場合は再度Inを呼ぶことで追加できる。コード例:
    query.In(1, 2, 10, 23, 30, 40, 55);
  • GroupQuery::AddFunctionメソッドのパラメータが異なる。
    AddFunction(func, targetNames, resultName, recordsetQuery)
    func
    他の言語では関数のオブジェクトを渡すが、以下に挙げる関数の番号を指定する。
    enum eGroupFunc
    {
        fsum = 0,
        fcount = 1,
        favg = 2,
        fmin = 3,
        fmax = 4,
        ffirst = 5,
        flast = 6
    }eGroupFunc;
    
    targetNames
    計算の対象となるフィールドを指定したFieldNamesオブジェクトを指定する。 funcfcountの場合はnullを指定する。
    resultName
    計算結果を受け取る列名を指定する。省略した場合はtargetNamesで指定された最初のフィールドの名前が使用される。
    recordsetQuery
    計算対象のレコードを限定する場合は、RecordsetQueryオブジェクトをセットしwhenで条件を指定する。指定しない場合は省略可。
    戻り値
    GroupQueryオブジェクトのインスタンス。thisを返す。
  • canRecoverNetError関数は非対応。以下のコードで同様な結果を得られます
    function CanRecoverNetError(var code)
    {
        return (code >= ERROR_TD_CONNECTION_FAILURE) &&
            (code < ERROR_TD_RECONNECTED) &&
            (code != ERROR_TD_NET_TOO_BIGDATA);
    }
未対応の
機能
  • table::insertBookmarksは非対応。
  • btrDate.hとmyDateTime.hで定義される日付と時刻を数値で扱うクラス、関数は未対応
  • fielddefs::addAllFiledsは非対応。
  • fielddefs::appendは非対応。
  • fielddefs::addSelectedFieldsは非対応。
  • fielddefs::addAliasNameは非対応。
  • fielddef::blobLenBytesは非対応。
  • fielddef::varLenBytesは非対応。
  • recordset::appendField(fielddef)は非対応。

PHP クライアント

PHP5系 PHP7系用のextensionを用意しています。

仕様と制限

PHPのクライアントはC++のAPIをラップした形になっており、以下の点を除いてC++のAPIと同じです。

C++ APIに対するPHPクライアントの相違点(2015/06/09)
全般
  • クラスは名前空間で修飾されない。
    (例:bzs::db::protocol::tdap::client::databasedatabase
  • クラスのメンバでない定数や関数はtransactdクラスに置かれる。
    (例:bzs::db::protocol::tdap::btrttoatransactd::btrttoa
  • バッファに結果をコピーして返す関数は、自動でバッファが用意されるため、そのパラメータは不要。同時にバッファの 長さを示すパラメータも不要。
    (例:const _TCHAR* nstable::getDirURI(const _TCHAR *uri, const _TCHAR* retbuf) $s = nstable::getDirURI($uri)
終了処理
  • メモリの解放はPHPのGCによって行われるため、明示的なメモリ解放処理は不要。 database::releaseおよびnstable::releaseは存在しない。
  • メモリ解放時にコネクションの切断も行われるが、明示的に切断処理を記述することを推奨する。 database.closeおよびtable.closeを使用する。
    $db->open(uri, 0, transactd::TD_OPEN_NORMAL); // open database
    $tb = $db->openTable("user", transactd::TD_OPEN_NORMAL, true);  // open table
    /* ... some operations ... */
    $tb->close(); // close table
    $db->close(); // close database
    
文字コード
  • Windows上であってもマルチバイトに限定され、Unicodeは使用できない。
  • マルチバイト文字列のエンコーディングにはUTF-8を使用する。
    mb_internal_encoding('UTF-8');
  • 使用可能な文字コードはSDKドキュメントの文字コードの項目を参照。
整数
  • 符号付32bitの範囲に収まる整数はtable::getFVintfield::iメソッドで取得できます。
  • その範囲に収まらない整数は、table::GetFVstrfield::strメソッドを使用すると、10進数の文字列表現として取得できます。
メソッドの
変更
  • keydef::segments[]へのアクセスをkeydef::segmentメソッドに変更。
  • tabledef::fieldDefs[]へのアクセスをtabledef::fieldDefメソッドに変更。
  • tabledef::keyDefs[]へのアクセスをtabledef::keyDefメソッドに変更。
  • btrVersions::versions[]へのアクセスをbtrVersions::versionメソッドに変更。
  • btrTimeStamp::toString, btrdtoa, btrttoa, btrstoaのシグネチャを変更。
    $nowdate = transactd::getNowDate();
    // 引数の char* が削除され、文字列を返す。
    $nowdate_str = transactd::btrdtoa($nowdate, true);
  • fielddefsクラスにArrayAccess, Countable, IteratorAggregate, Generator methodを実装。
  • RecordクラスにArrayAccess, Countable, IteratorAggregate, Generator methodを実装。
  • Recordクラスにオブジェクトからフィールドの値をセットするsetValueByObjectを追加。
  • RecordsetクラスにArrayAccess, Countable, IteratorAggregate, Generator methodを実装。
  • RecordsetクラスとTableクラスにfetchModeを追加。詳細は PHPとRubyにおける行取得の追加機能を参照。
  • RecordsetクラスにgetRecordを追加。getRecordfetchModeの値に関わらず recordオブジェクトを返します。
  • TableクラスにgetRowを追加。getRowfieldsメソッドのエイリアスです。
  • Tableクラスに、オブジェクトをパラメータにとりプライマリキーでCRUDを行うオペレーション table::saveByObjecttable::updateByObject table::insertByObjecttable::readByObjecttable::deleteByObjectを追加。
  • Tableクラスに、キーの値でレコードを移動するseekKeyValue($keyValues)メソッドを追加。このメソッドは以下の内容をエクステンション内で処理します。
    function seekKeyValue($keyValues)
    {
      $tb->clearBuffer();
      $i = 0;
      foreach($keyValues as $value)
        $tb->setFV(keyseg($i++), $value);
      $tb->seek();
      return $tb->stat();
    }
    
未対応の
機能
  • onCopyData,onDeleteRecordのコールバック関数機能は未対応(今後対応予定)
  • table::insertBookmarksは非対応。
  • fielddefs::addAllFiledsは非対応。
  • fielddefs::appendは非対応。
  • fielddefs::addSelectedFieldsは非対応。
  • fielddefs::addAliasNameは非対応。
  • fielddef::blobLenBytesは非対応。
  • fielddef::varLenBytesは非対応。
  • nstable::statsは非対応。
  • table::optionalDataは非対応。
  • table::setOptionalDataは非対応。
  • database::optionalDataは非対応。
  • database::setOptionalDataは非対応。
  • connection::record::statusは非対応。
  • tdap::getFilterLogicTypeCodeは非対応。

PHPとRubyにおける行取得の追加機能

すべてのクライアントにおいて、recordset::recordおよびtable::fieldsメソッドを使用し、recordオブジェクトとして行を取得することができます。

PHPとRubyではさらに、配列・ハッシュ・標準オブジェクト・ユーザークラスの形式で取得可能です。

形式の指定

形式の指定はfetchModeプロパティで行います。

fetchModeの値内容
FETCH_VAL_NUM = 1配列(フィールド番号 => 値)
FETCH_VAL_ASSOC = 2ハッシュ(フィールド名 => 値)
FETCH_VAL_BOTH = 3フィールド番号のキーも含むハッシュ
FETCH_OBJ = 4標準オブジェクト(無名オブジェクト)
FETCH_USR_CLASS = 8ユーザー定義クラス
FETCH_RECORD_INTO = 16Transactdのrecordオブジェクト

配列ではフィールド番号でフィールドの値にアクセスします。ハッシュではフィールド名のキーで値にアクセスします。 オブジェクトとユーザークラスでは、フィールド名と同名のパブリックプロパティで値にアクセスできます。

fetchModeのデフォルトはFETCH_RECORD_INTOです。

PHP 例

$tb->fetchMode = transactd::FETCH_OBJ;
$tb->seekFirst();
$obj = tb->fields(); // <--- 行の取り出し
$id = $obj->id;

Ruby 例

tb.fetchMode = Transactd::FETCH_OBJ
tb.seekFirst()
obj = tb.fields() # <--- 行の取り出し
id = obj.id

ユーザー定義クラスの指定

ユーザー定義クラスの場合は、fetchClassでクラス名(RubyではClassオブジェクトでも可)を、 ctorArgsでコンストラクタへの引数を指定します。 コンストラクタへの引数は不要であれば省略可能です。

PHP 例

$tb->fetchMode = transactd::FETCH_USR_CLASS;
$tb->fetchClass = 'User';
$tb->ctorArgs = $userName;

$tb->seekFirst();
$user = tb->fields(); // <--- 行の取り出し
$id = $user->id;

Ruby 例

tb.fetchMode = Transactd::FETCH_USR_CLASS
tb.fetchClass = User
tb.ctorArgs = userName

tb.seekFirst()
user = tb.fields() # <--- 行の取り出し
id = user.id

recordsetにおける全行取得

recordsetではすべての行を指定したfetchModeで取得し配列にして返す toArrayもしくはto_aを使用できます。

PHP 例

$rs->fetchMode = transactd::FETCH_USR_CLASS;
$rs->fetchClass = 'User';
$rs->ctorArgs = $userName;

$users = $rs->toArray();
$user = $users[0];

Ruby 例

rs.fetchMode = Transactd::FETCH_USR_CLASS
rs.fetchClass = User
rs.ctorArgs = userName

users = rs.to_a()
user = users[0]