Transactd Developer's Guide

Documents

Supported languages

Currently, languages which can be used with application development are followings:

(Planning with Java, Python, etc.)

Multi thread support

The clients for all languages support multi-thread per database.

The database and associated objects such as tables can be used safely in a thread. In other words, to use objects safely, create database object on each thread. At this time, pass the option that creating dedicated TCP connection, to connect method.

It can be used safely from Apache 2 workerMPM or ISAPI extension on IIS.

Ruby client

We provide Ruby Gem for Ruby 1.9 / 2.0.

Introduction

To install the client for Ruby, please refer to Transactd Install Guide for Ruby.

Specifications and Limitations

Ruby client is a wrapper of the C++ API, and is the same as the C++ API, with the following exceptions:

Differences between Ruby client and C++ API (2015/06/09)
General
  • Class names are capitalized (ex: database->Database)
  • Constant names are capitalized (ex: ft_integer->Ft_integer)
  • Namespaces does not nest. Transactd is the only namespace.
    (ex: bzs::db::protocol::tdap::client::database->Transactd::Database)
End processing
  • Memory release process is done by GC of Ruby. You do not need to release memory explicitly. database::release and nstable::release does not exist.
  • The connection will be closed when memory is released, but we recommend to describe the closing process explicitly. Use Database.close and 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
Character set
  • Limited to Multibyte, Unicode can not be used even on Windows. (Use tdclcpp_*m*.dll)
  • Use UTF-8 for encoding of the source code file.
  • For available character set, please refer to character set section of SDK documents.
Changes in Methods
  • Change keydef::segments[] to Keydef.segment method.
  • Change tabledef::fieldDefs[] to Tabledef.fieldDef method.
  • Change tabledef::keyDefs[] to Tabledef.keyDef method.
  • Change btrVersions::versions[] to BtrVersions::version method.
  • Change signatures of BtrTimeStamp::toString, btrdtoa, btrttoa, btrstoa 
    nowdate = Transactd::getNowDate()
# A char* argument is removed. Return Strings.
nowdate_str  = Transactd::btrdtoa(nowdate, true)
  • Add set_value_by_object method to Record class. It set field values from object to record.
  • Add fetchMode property to Recordset class and Table class. See Expanded row fetching on PHP and Ruby for details.
  • Add getRecord method to Recordset class. It returns Record object regardless of the value of fetchMode.
  • Add getRow to Table class. It is alias of fields method.
  • Add CRUD operation methods table::save_by_object, table::update_by_object, table::insert_by_object, table::read_by_object and table::delete_by_object to Table class. They receive object as a parameter and seek record with primary key value.
  • Add seek_key_value(keyValues) method to Table class. It move to a record with key value. It is implemented in extension and behaves like following code: 
    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
  • Add aliases for methods and properties according to the following rules:
    • Add snake_case format aliases for camelCase format names.
    • Add is_XXX? format aliases for methods which has is_XXX format name and boolean return value.
    • Add XXX= format aliases for methods which has set_XXX format name, one parameter, and void return value.
Unsupported Features
  • onCopyData and onDeleteRecord callback functions are currently not supported.
  • table::insertBookmarks is currently not supported.
  • fielddefs::addAllFields is currently not supported.
  • fielddefs::append is currently not supported.
  • fielddefs::addSelectedFields is currently not supported.
  • fielddefs::addAliasName is currently not supported.
  • fielddef::blobLenBytes is currently not supported.
  • fielddef::varLenBytes is currently not supported.
  • nstable::stats is currently not supported.
  • table::optionalData is currently not supported.
  • table::setOptionalData is currently not supported.
  • database::optionalData is currently not supported.
  • database::setOptionalData is currently not supported.
  • connection::record::status is currently not supported.
  • tdap::getFilterLogicTypeCode is currently not supported.

COM client

COM is only available on Windows.

Introduction

If you install Transactd clients using the Windows Installer, COM client is also installed and is registered in the registry. For instructions on how to install, please refer to Transactd Install Guide.

Specifications and Limitations

COM client is a wrapper of the C++ API, and is the same as the C++ API, with the following exceptions:

Differences between COM interface and C++ API (2015/06/09)
General
  • Class names are capitalized (ex: database->Database)
  • Method names are capitalized (ex: openTable->OpenTable)
  • Namespaces does not nest. transactd is the only namespace.
    (ex: bzs::db::protocol::tdap::client::database->transactd::Database)
Constant (enum)
  • If you use a scripting language, define it in the script.
  • If the IDE can use the type library, it is accessible in eXxx namespace. (ex: eStatus.STATUS_SUCCESS)
End processing
  • Memory release process is done by COM. You do not need to release memory explicitly. database::release and nstable::release does not exist.
  • The connection will be closed when memory is released, but we recommend to describe the closing process explicitly. Use Database.Close and 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
Character set

Limited to Unicode, multi-byte can not be used. (Use tdclcpp_*****_**u_*_*.dll)
Changes in Methods
  • To create Database object, like: 
    var db = new ActiveXObject('transactd.Database');
  • Change keydef::segments[] to Keydef.Segments method
  • Change tabledef::fieldDefs[] to Tabledef.FieldDef method
  • Change tabledef::keyDefs[] to Tabledef.KeyDef method.
  • Change btrVersions class to TdVersion class.
  • To create QueryBase object, like: 
    var query = new ActiveXObject('transactd.query');
  • Change QueryBase::addLogic to QueryBase::Where, QueryBase::And, QueryBase::Or. example: 
    query.Where("id", ">=", 1).And("id", "<", 3).Or("name", "=", "akio");
  • Change QueryBase::addField to QueryBase::Select. 11 arguments can be specified. If need more arguments, call Select again. example: 
    query.Select("id", "name", "email");
  • Change QueryBase::addSeekKeyValue to QueryBase::AddInValue.
  • Add QueryBase::In. 11 arguments can be specified. If need more arguments, call In again. example: 
    query.In(1, 2, 10, 23, 30, 40, 55);
  • canRecoverNetError is not supported. It can be replaced with following code: 
    function CanRecoverNetError(var code)
{
    return (code >= ERROR_TD_CONNECTION_FAILURE) &&
        (code < ERROR_TD_RECONNECTED) &&
        (code != ERROR_TD_NET_TOO_BIGDATA);
}
Unsupported Features
  • table::insertBookmarks is currently not supported.
  • Date and time classes and functions which is defined in btrDate.h and myDateTime.h are currently not supported.
  • fielddefs::addAllFileds is currently not supported.
  • fielddefs::append is currently not supported.
  • fielddefs::addSelectedFields is currently not supported.
  • fielddefs::addAliasName is currently not supported.
  • fielddef::blobLenBytes is currently not supported.
  • fielddef::varLenBytes is currently not supported.
  • recordset::appendField(fielddef) is currently not supported.

PHP client

We provide extension for PHP 5.x.

Introduction

To install the client for PHP, please refer to Transactd Install Guide for PHP.

Specifications and Limitations

PHP client is a wrapper of the C++ API, and is the same as the C++ API, with the following exceptions:

Differences between PHP client and C++ API (2015/06/09)
General
  • Classes are not qualified with namespaces.
    (ex: bzs::db::protocol::tdap::client::database->database)
  • Constants and functions that are not members of any classes are placed in transactd class.
    (ex: bzs::db::protocol::tdap::btrttoa->transactd::btrttoa)
  • Function to return to copy the result in the buffer, the parameter is not required. Because the buffer is provided automatically.At the same time, the parameter is also not required to indicate the length of the buffer.
    （ex：const _TCHAR* nstable::getDirURI(const _TCHAR *uri, const _TCHAR* retbuf) → $s = nstable::getDirURI($uri) ）
End processing
  • Memory release process is done by GC of PHP. You do not need to release memory explicitly. database::release and nstable::release does not exist.
  • The connection will be closed when memory is released, but we recommend to describe the closing process explicitly. Use database.close and 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
Character set
  • Limited to Multibyte, Unicode can not be used even on Windows.
  • Use UTF-8 for multibyte strings.
    mb_internal_encoding('UTF-8');
  • For available character set, please refer to character set section of SDK documents.
Changes in Methods
  • Change keydef::segments[] to keydef.segment method
  • Change tabledef::fieldDefs[] to tabledef.fieldDef method
  • Change tabledef::keyDefs[] to tabledef.keyDef method.
  • Change btrVersions::versions[] to btrVersions::version method.
  • Change signatures of btrTimeStamp::toString, btrdtoa, btrttoa, btrstoa 
    $nowdate = transactd::getNowDate();
// A char* argument is removed. Return Strings.
$nowdate_str = transactd::btrdtoa($nowdate, true);
  • Add ArrayAccess, Countable, IteratorAggregate, Generator method to fielddefs.
  • Add ArrayAccess, Countable, IteratorAggregate, Generator method to Record.
  • Add setValueByObject method to Record class. It set field values from object to record.
  • Add ArrayAccess, Countable, IteratorAggregate, Generator method to Recordset.
  • Add fetchMode property to Recordset class and Table class. See Expanded row fetching on PHP and Ruby for details.
  • Add getRecord method to Recordset class. It returns Record object regardless of the value of fetchMode.
  • Add getRow to Table class. It is alias of fields method.
  • Add CRUD operation methods table::saveByObject, table::updateByObject, table::insertByObject, table::readByObject and table::deleteByObject to Table class. They receive object as a parameter and seek record with primary key value.
  • Add seekKeyValue(keyValues) method to Table class. It move to a record with key value. It is implemented in extension and behaves like following code: 
    function seekKeyValue($keyValues)
{
  $tb->clearBuffer();
  $i = 0;
  foreach($keyValues as $value)
    $tb->setFV(keyseg($i++), $value);
  $tb->seek();
  return $tb->stat();
}
Unsupported Features
  • onCopyData and onDeleteRecord callback functions are currently not supported.
  • table::insertBookmarks is currently not supported.
  • fielddefs::addAllFileds is currently not supported.
  • fielddefs::append is currently not supported.
  • fielddefs::addSelectedFields is currently not supported.
  • fielddefs::addAliasName is currently not supported.
  • fielddef::blobLenBytes is currently not supported.
  • fielddef::varLenBytes is currently not supported.
  • nstable::stats is currently not supported.
  • table::optionalData is currently not supported.
  • table::setOptionalData is currently not supported.
  • database::optionalData is currently not supported.
  • database::setOptionalData is currently not supported.
  • connection::record::status is currently not supported.
  • tdap::getFilterLogicTypeCode is currently not supported.

Expanded row fetching on PHP and Ruby

recordset::record and table::fields method return a row as a record object on all kind of client libraries.

On PHP and Ruby clients, row fetching is extended. You can get a row as an Array, Hash, standard object and user class.

Set format

Use fetchMode property to set format.

value of fetchModeformat
FETCH_VAL_NUM = 1Array (field_number => value)
FETCH_VAL_ASSOC = 2Hash (field_name => value)
FETCH_VAL_BOTH = 3Hash which has field_number as keys
FETCH_OBJ = 4Standard object
FETCH_USR_CLASS = 8User defined class object
FETCH_RECORD_INTO = 16record object of Transactd

Access to value with field number on Array. With field name on Hash. On standard object and user class object, they have public properties which have the name same as field name.

The default value of fetchMode is FETCH_RECORD_INTO.

Example with PHP

$tb->fetchMode = transactd::FETCH_OBJ;
$tb->seekFirst();
$obj = tb->fields(); // <--- row fetching
$id = $obj->id;

Example with Ruby

tb.fetchMode = Transactd::FETCH_OBJ
tb.seekFirst()
obj = tb.fields() # <--- row fetching
id = obj.id

Set user defined class

Set user defined class to fetchClass, and parameters for constructor to ctorArgs. The parameters for constructor are optional.

Example with PHP

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

$tb->seekFirst();
$user = tb->fields(); // <--- row fetching
$id = $user->id;

Example with Ruby

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

tb.seekFirst()
user = tb.fields() # <--- row fetching
id = user.id

Fetchi all records with recordset

Recordset::toArray (or to_a on Ruby) method returns an Array of all rows objects as format which specified with fetchMode.

Example with PHP

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

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

Example with Ruby

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

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