1. C開発者ガイド
  2. ODBCでのTimesTenデータベースの使用
  3. TimesTen Scaleoutのクライアント・ルーティングAPI

TimesTen Scaleoutのクライアント・ルーティングAPI

これらの項では、TimesTen Scaleoutのクライアント・ルーティングAPIについて説明します。

クライアント・ルーティングAPIの機能

パフォーマンスを高めるために、TimesTen Scaleoutではクライアント・アプリケーションがハッシュ分散キーのキー値に基づいて要素に接続をルーティングできます。

キー値を指定すると、TimesTen Scaleoutが要素ID (またはレプリカ・セットID)の配列を返します。その値は、データベースによって割り当てられたものです。これにより、指定したキー値に一致する行を格納している要素にクライアント・アプリケーションが接続できるため、行を格納している要素とアプリケーションに接続された要素との間で不要な通信を回避できます。

ノート:

この機能は汎用ドライバ・マネージャではサポートされていませんが、TimesTenドライバ・マネージャではサポートされています。

グリッド・マップとグリッド分散の作成

次の各項では、クライアント・ルーティング用のグリッド・マップとグリッド分散の作成方法について説明します。

グリッド・マップ用とグリッド分散用の関数

クライアント・ルーティング用のグリッド・マップおよびグリッド分散に使用できる関数を示します。

TimesTen Scaleoutでは、timesten.hファイルに、グリッド・マップ用およびグリッド分散用の2つの新しいオブジェクトが含まれています。

  • TTGRIDMAP: グリッド・マップは、グリッドのトポロジをマップする参照表です。グリッド・マップを作成するには、有効なODBC接続を指定したttGridMapCreate関数をコールします。この関数は、TTGRIDMAPオブジェクトへのハンドルを返します。

    グリッド・マップを解放するには、ttGridMapFree関数を使用します。

    ノート:

    • TTGRIDMAPオブジェクトは、HDBC接続に強く関連付けられていません。一方のオブジェクトを解放しても、他方のオブジェクトは解放されません。

    • グリッド・マップは、多くのグリッド分散およびアプリケーション・スレッド間で共有できます。各データベースのアプリケーション・プロセスごとにグリッド・マップが1つのみ必要です。

  • TTGRIDDIST: グリッド分散は、1つ以上の表の分散キー列を表す、順序付きの型と値のセットです。複数の列で構成される分散キーの場合、型と値の順序は表の分散キー列のものと同じである必要があります。

    グリッド分散を作成するには、表の分散キー列のCデータ型、SQLデータ型、長さ、スケールおよび精度を指定してttGridDistCreate関数をコールします。この関数は、TTGRIDDISTオブジェクトへのハンドルを返します。表2-3を参照してください。

    グリッド分散を解放するには、ttGridDistFree関数を使用します。

    ノート:

    • TTGRIDDISTオブジェクトは、特定の表に関連付けられていません。分散キー列に同じ型および値を使用する表に対して、同じTTGRIDDISTオブジェクトを使用できます。

    • グリッド分散はスレッド間で共有できません。ただし、同じグリッド・マップを使用して異なるスレッドに複数のグリッド分散を作成できます。

    表2-3 ttGridDistCreateの引数

    引数 型 説明

    hdbc

    SQLHDBC

    接続ハンドル

    map

    TTGRIDMAP

    グリッド・マップ・ハンドル

    cTypes[]

    SQLSMALLINT

    分散キー列と同じ順序で並んだCバインド・タイプの配列

    sqlTypes[]

    SQLSMALLINT

    分散キー列と同じ順序で並んだSQLバインド・タイプの配列

    precisions[]

    SQLULEN

    分散キー列と同じ順序で並んだ精度値の配列

    scales[]

    SQLSMALLINT

    分散キー列と同じ順序で並んだスケール値の配列

    maxSizes[]

    SQLLEN

    分散キー列と同じ順序で並んだ最大列サイズ値の配列

    nCols

    SQLUSMALLINT

    分散キーの列数

    *dist

    TTGRIDDIST

    グリッド分散ハンドル(OUT)

    ノート:

    ttGridDistCreateのパラメータは、後続のSQLBindParameter ODBCコールで使用されるパラメータと似ています。

グリッド・マップとグリッド分散の作成方法

次の例では、グリッド・マップとグリッド分散の作成方法を示します。

  1. TTGRIDMAPおよびTTGRIDDISTオブジェクトを作成します。
  2. ttGridMapCreate関数をコールし、既存のODBC接続を使用してグリッド・マップを作成します。
  3. ttGridDistCreate関数をコールして、2つの列で構成される分散キーに基づいてグリッド分散を作成します。
  4. グリッド分散とグリッド・マップをそれぞれttGridDistFree関数およびttGridMapFree関数で解放します。
TTGRIDMAP map;
TTGRIDDIST dist;

ttGridMapCreate(hdbc, &map);

SQLSMALLINT cTypes[] = { SQL_C_LONG, SQL_C_CHAR };
SQLSMALLINT sqlTypes[] = { SQL_INTEGER, SQL_CHAR };
SQLLEN maxSizes[] = { 4, 20 };

ttGridDistCreate(hdbc, map, cTypes, sqlTypes, NULL, NULL, maxSizes, 2, &dist);

...

ttGridDistFree(hdbc, dist);
ttGridMapFree(hdbc, map);

分散キーの値

クライアント・ルーティング用のグリッド分散キー値を設定する方法について説明します。

分散キー値用の関数

クライアント・ルーティングのグリッド分散キー値を設定するには、ttGridDistValueSet関数を使用します。

グリッド・マップとグリッド分散を定義したら、それらを割り当てる要素を決定するためにキー値を設定します。ttGridDistValueSet関数をコールして、分散キーの列のいずれかにキー値を設定します。複数の列で構成される分散キーの場合、分散キーの列ごとにこの関数を1回コールします。表2-4に、ttGridDistValueSet関数の引数の概要を示します。

表2-4 ttGridDistValueSetの引数

引数 型 説明

hdbc

SQLHDBC

接続ハンドル

dist

TTGRIDDIST

グリッド分散ハンドル

position

SQLSMALLINT

分散キー内の列の位置

value

SQLPOINTER

キー値ポインタ

valueLen

SQLLEN

キー値の長さ

分散キー値の設定

この例では、まずttGridDistClear関数をコールして、分散キー列に対して事前に定義されているキー値をクリアします。次に、分散キーの列ごとにttGridDistValueSet関数をコールし、各列のキー値を設定します。 

ttGridDistClear(hdbc, dist);

ttGridDistValueSet(hdbc, dist, 1, empId, sizeof(empId));
ttGridDistValueSet(hdbc, dist, 2, "SALES", SQL_NTS);

一連のキー値に与えられた要素位置の取得

分散キー値を設定したので、この項では、要素IDまたはレプリカ・セットIDでキー値の位置を要求できるということを示します。

内容は次のとおりです。

要素ID用の関数

ttGridDistElementGet関数をコールして、指定されたキー値の位置を表す対応する要素IDを取得します。この関数は、要素IDの配列を返します。アプリケーションは、戻り配列を割り当てます。配列の長さは、グリッドのK-safetyの値に基づいています。

たとえば、K-safetyが2に設定されているグリッドでは、配列に少なくとも2つの要素が必要です。表2-5に、ttGridDistElementGet関数の引数の概要を示します。

表2-5 ttGridDistElementGetの引数

引数 型 説明

hdbc

SQLHDBC

接続ハンドル

dist

TTGRIDDIST

グリッド分散ハンドル

elemIds[]

SQLSMALLINT

キー値が割り当てられる要素IDの配列(IN/OUT)

elemIdSize

SQLSMALLINT

K-safetyの値

要素IDの取得

この例では、要素IDの取得方法、および要素IDを接続文字列に関連付ける方法を示します。

この例では、ttGridDistElementGet関数をコールすることで、現在のキー値(ttGridDistValueSet関数によって設定)に関連付けられた要素IDの配列を取得します。 

SQLSMALLINT elementIds[2];

ttGridDistElementGet(hdbc, dist, elementIds, 2);

ノート:

elementIds配列の長さは、グリッドのK-safetyの値以上である必要があります。

使用可能なキー値セットの位置により、アプリケーションは要素IDを使用して、要素のいずれかへの接続を選択し、文を作成し、値をバインドして、その文を実行できます。

ノート:

接続試行はフェイルオーバー・イベントの対象になることがあり、そのためにアプリケーションが目的の要素に接続できない可能性があります。

次の例では、要素IDを接続文字列に関連付ける際に役立つ問合せを示します。この例では、SYS.V$DISTRIBUTION_CURRENTシステム・ビューを問い合せることで、データベースの要素ごとに接続文字列をアセンブルします。接続文字列にはTTC_REDIRECT=0属性が含まれていて、指定した要素またはそのレプリカへの接続が保証されます。すべてのレプリカへの接続が失敗すると、接続エラーが返されます。 

select 'TTC_REDIRECT=0;
TTC_SERVER='||hostexternaladdress||'/'||serverport,mappedelementid
 from SYS.V$DISTRIBUTION_CURRENT;
< TTC_REDIRECT=0;TTC_SERVER=ext-host3.example.com/6625, 1 >
< TTC_REDIRECT=0;TTC_SERVER=ext-host4.example.com/6625, 2 >
< TTC_REDIRECT=0;TTC_SERVER=ext-host5.example.com/6625, 3 >
< TTC_REDIRECT=0;TTC_SERVER=ext-host6.example.com/6625, 4 >
< TTC_REDIRECT=0;TTC_SERVER=ext-host7.example.com/6625, 5 >
< TTC_REDIRECT=0;TTC_SERVER=ext-host8.example.com/6625, 6 >
6 rows found.

レプリカ・セットID用の関数

ttGridDistReplicaGet関数をコールして、指定されたキー値の位置を表す対応するレプリカ・セットIDを取得します。

表2-6に、ttGridDistReplicaGet関数の引数の概要を示します。

表2-6 ttGridDistReplicaGetの引数

引数 型 説明

hdbc

SQLHDBC

接続ハンドル

dist

TTGRIDDIST

グリッド分散ハンドル

*replicaSetId

SQLSMALLINT

キー値が割り当てられるレプリカ・セットID (OUT)

レプリカ・セットIDの取得

この例では、ttGridDistReplicaGet関数をコールすることで、現在のキー値(ttGridDistValueSet関数によって設定)に関連付けられたレプリカ・セットIDを取得します。 

SQLSMALLINT replicaSetId;

ttGridDistReplicaGet(hdbc, dist, replicaSetId);

SYS.V$DISTRIBUTION_CURRENTシステム・ビューでレプリカ・セットIDを使用して、そのレプリカ・セット内の要素の通信パラメータを参照できます。

クライアント・ルーティングAPIとその関数の使用例

この部分的な例では、クライアントルーティングAPIが示されており、そのほとんどのオブジェクトと関数が使用されています。

#include <timesten.h>

...

TTGRIDMAP map;
TTGRIDDIST dist;

/* Create a grid map using any existing connection. */
ttGridMapCreate(hdbc, &map);

/* The distribution key has two columns: one with TT_INTEGER as data type and
 * one with CHAR(20), in that order. Precision and scale are not necessary. */
SQLSMALLINT cTypes[] = { SQL_C_LONG, SQL_C_CHAR };
SQLSMALLINT sqlTypes[] = { SQL_INTEGER, SQL_CHAR };
SQLLEN maxSizes[] = { 4, 20 };

/* Create grid distribution from the grip map and the specified distribution
 * key column paremeters. */
ttGridDistCreate(hdbc, map, cTypes, sqlTypes, NULL, NULL, maxSizes, 2, &dist);

/* Execution loop. */
while ( ... ) 
{
      SQLSMALLINT elementIds[2];

      /* Clear the existing key values from the distribution map */
      ttGridDistClear(hdbc, dist);

      /* Set the key values for the grid distribution. */
      ttGridDistValueSet(hdbc, dist, 1, key1, sizeof(key1));
      ttGridDistValueSet(hdbc, dist, 2, key2, SQL_NTS);

      /* Get the corresponding element IDs for current key values*/
      ttGridDistElementGet(hdbc, dist, elementIds, 2);

      /* The application uses the element IDs to select a connection to 
       * one of the elements, prepare a statement, bind values, and execute 
       * the statement. */
      ...
}

/* Free the grid distribuion and map. */
ttGridDistFree(hdbc, dist);
ttGridMapFree(hdbc, map);

サポートされているデータ型

TTGRIDDISTオブジェクトは、ODBCで使用可能なCデータ型およびSQLデータ型を使用して作成されます。

表2-7に、サポートされているCデータ型およびSQLデータ型をその対応するデータベースSQLデータ型とともに示します。

表2-7 サポートされているデータ型のリスト

Cデータ型 ODBC SQLデータ型 データベースSQLデータ型

SQL_C_TINYINT

SQL_TINYINT

TT_TINYINT

SQL_C_SMALLINT

SQL_SMALLINT

TT_SMALLINT

SQL_C_LONG

SQL_INTEGER

TT_INTEGER

SQL_C_BIGINT

SQL_BIGINT

TT_BIGINT

SQL_C_CHAR

SQL_CHAR

CHAR

SQL_C_CHAR

SQL_VARCHAR

VARCHAR、VARCHAR2

SQL_C_WCHAR

SQL_WCHAR

NCHAR

SQL_C_WCHAR

SQL_WVARCHAR

NVARCHAR

SQL_C_SQLT_NUM

SQL_DOUBLE

NUMBER

SQL_C_SQLT_NUM

SQL_DECIMAL

NUMBER(p,s)

SQL_C_SQLT_VNU

SQL_DOUBLE

NUMBER

SQL_C_SQLT_VNU

SQL_DECIMAL

NUMBER(p,s)

TTGRIDDISTオブジェクトでは、符号付きと符号なしのすべてのデータ型バリアントがサポートされています。たとえば、SQL_C_SLONGとSQL_C_ULONGの両方がサポートされています。

ttGridDistValueSet関数のvalueLenパラメータにSQL_NULL_DATAを指定して、NULL値を設定できます。NULL値は、常に同じレプリカ・セットまたは要素IDにマップされます。

制限事項

クライアント・ルーティングにはいくつか制限事項があります。

  • 暗黙的な接続または文の管理はありません。

  • 日付、時間またはタイムスタンプのデータ型はサポートされていません。

  • 明示的な型変換はサポートされていません。アプリケーションでは、キー値を正規のバイト形式で指定する必要があります。

  • 文字セット変換はサポートされていません。接続文字セットは無視されます。

  • グリッドのトポロジを変更するには、アプリケーションがグリッド・マップを解放して再作成する必要があります。

障害モード

クライアント・ルーティングAPIによって返される可能性があるエラーはいくつかあります。

  • 表の分散キー列を説明するデータ型および値が正しくありません。この場合、APIは要素IDの配列を計算しますが、目的のキー値の実際の位置に対応していない可能性があります。

  • 型コードを認識できません。認識されない型コードでttGridDistCreate関数をコールすると、エラーが返されます。

  • グリッド分散に十分な値が設定されていません。ttGridDistValueSet関数を使用して分散キーに十分な値を指定しない場合、ttGridDistElementGet関数またはttGridDistReplicaGet関数はエラーを返します。

  • 要素ID配列のサイズが無効です。K-safetyの値のサイズ以上の配列を指定しない場合、ttGridDistElementGet関数はエラーを返します。