ヘッダーをスキップ
Oracle TimesTen In-Memory Database TTClassesガイド
リリース7.0
E05171-02
  目次へ
目次
索引へ
索引

前へ
前へ
次へ
次へ
 

TTCmd

アプリケーション・プログラムで複数回使用される単一のSQL文をカプセル化します。TTCmdは、ODBC HSTMTハンドルの付加価値C++ラッパーとみなすことができます。

パブリック・メンバー

なし

TTCmdには、次の3種類のパブリック・メソッドがあります。

パブリック・メソッド

メソッド
説明

Prepare

SQL文とTTCmdを関連付けます。

RePrepare

文の再準備を可能にします。

Execute

実行のために準備されたSQL文を起動します。

ExecuteImmediate

事前に準備されていないSQL文を起動します。

FetchNext

応答セットの行を1行ずつフェッチします。行のフェッチに成功した場合は0を、フェッチする行がなくなった場合は1を返します。

Close

アプリケーションでの行のフェッチが終了したら、応答セットを閉じます。

Drop

準備済のSQL文とそれに関連付けられたすべてのリソースを解放します。

setQueryTimeout

問合せのタイムアウト値を設定します。

setMaxRows

SELECT文によって返される行の数に制限を設定します。

getMaxRows

SELECT文によって返される行の数の現在の制限を返します。

getRowCount

最近実行されたSQL操作の影響を受けた行の数を返します。

setParam

準備済のSQL文を実行する前にパラメータの値を設定します。

setParamNull

準備済のSQL文を実行する前にパラメータの値をNULLに設定します。

getParamPrecision

準備済の文に指定されたパラメータの精度を返します。

getParamScale

準備済の文に指定されたパラメータのスケールを返します。

getParamNull

指定されたパラメータをNULLにできるかどうかを示します。

getColumn

特定の列に関連付けられた値を返します。

isColumnNull

指定された列の値がNULLかどうかを示します。

getColumnLength

指定された列の長さを返します。

getColumnNullable

応答セットの現在の行の列値を返して、列値がNULLかどうかを示します。

getNextColumn

応答セットの次の行の列値を返します。

getNextColumnNullable

応答セットの次の行の列値を返して、列値がNULLかどうかを示します。

printColumn

指定された列を出力ストリームに出力します。

TTCmdオブジェクトのプロパティを取得するためのパブリック・メソッド

メソッド
説明

getNParameters

入力パラメータの数を返します。

getNColumns

出力列の数を返します。

getParamType

指定されたパラメータのODBCデータ型を返します。

getColumnName

指定された列の名前を返します。

getColumnType

指定された列のODBCデータ型を返します。

getColumnPrecision

指定された列の精度を返します。

getColumnScale

指定された列のスケールを返します。

バッチ操作のためのパブリック・メソッド

メソッド
説明

PrepareBatch

INSERT、UPDATEおよびDELETE文のバッチ処理を準備します。

BindParameter

PrepareBatchを使用してコンパイルされた文の値の配列をバインドします。

setParamLength

準備済の文を実行する前に、バインドされたいずれかのパラメータ値の長さを設定します。

setParamNull

準備済の文を実行する前に、バインドされたいずれかのパラメータをNULLに設定します。

ExecuteBatch

PrepareBatchによって実行のために準備されたSQL文を起動します。バッチ内の更新された行数を返します。

Prepare

void Prepare (TTConnection*, const char* sqlP, TTStatus&)

このメソッドは、SQL文とTTCmdを関連付けます。次の3つのパラメータをとります。

TTCmdを使用する前に、SQL文(SELECT、INSERT、UPDATEまたはDELETE)を関連付ける必要があります。この関連付けはPrepareメソッドを使用して行われます。Prepareメソッドは、SQL文が効率的に実行されるように、SQL文のコンパイルおよび最適化も行います。Prepareメソッドは文を実行しません。

通常、TimesTenでは、性能の向上のために文はパラメータ化されます。次のようなSQL文を考えてみます。

SELECT col1 FROM table1 WHERE C = 10

SELECT col1 FROM table1 WHERE C = 11

これよりも、パラメータ化された1つの文を準備し、それを複数回実行した方がより効率的です。

SELECT col1 FROM table1 WHERE C = ?

「?」の値は、TTCmd::setParamメソッドを使用して実行時に指定されます。

ODBCを直接使用する場合と違い、列またはパラメータを明示的にSQL文にバインドする必要はありません。TTCmdは、準備する際にすべての必要な列とパラメータを自動的に定義しバインドします。

Prepareは相対的に負荷の高い操作であることに注意してください。アプリケーションによって、(TTConnection::Connectを使用して)TimesTenへの接続が確立される際に、その接続に関連付けられたすべてのTTCmdオブジェクトが準備されます。

例外が有効な場合は、エラーが発生するとTTStatusオブジェクトが返されます。例外が無効な場合は、メソッドから返される際に、発生したエラーに関する情報が、最後のパラメータとしてメソッドに渡されたTTStatus&オブジェクトに格納されます。

RePrepare

void RePrepare (TTConnection *cP, TTStatus & stat)

このメソッドは、文の再準備を可能にします。このメソッドは、準備済の文の文ハンドルが無効の場合にのみ有効です。

Execute

void Execute (TTStatus&)

このメソッドは、実行のために準備されたSQL文を起動します。

必要なパラメータ値がsetParamメソッドによって定義された後、Executeを使用して、Prepareメソッドによって事前に準備済のSQL文を起動します。

SQL文がSELECT文の場合は、このメソッドによって問合せが実行されますが、結果セットから行が返されません。FetchNextメソッドを使用すると、結果セットから一度に1行ずつフェッチされます。該当するすべての行がフェッチされたら、Closeメソッドを使用して結果セットを閉じます。SELECT以外のSQL文の場合は、カーソルがオープンされないため、Closeメソッドをコールする必要はありません。

例外が有効な場合は、エラーが発生するとTTStatusオブジェクトが例外として返されます。例外が無効な場合は、メソッドから返される際に、発生したエラーに関する情報が、最後のパラメータとしてメソッドに渡されたTTStatus&オブジェクトに格納されます。

ExecuteImmediate

int ExecuteImmediate (TTConnection*, const char * sqlP,

                      TTStatus & stat)

このメソッドは、事前に準備されていないSQL文を起動します。

数回だけ実行されるSQL文については、PrepareおよびExecuteのかわりにExecuteImmediateを使用すると便利です。DDL文(CREATE TABLE、DROP TABLEなど)や、使用頻度が低く結果セットを返さないDML文(DELETE FROM table nameなど)にExecuteImmediateを使用します。

ExecuteImmediateは、結果セットを返すSQL文と互換性がありません。また、ExecuteImmediateによって実行された文は、後でgetRowCount(DML操作によって影響を受けた行の数を取得する)を使用して問い合せることができません。このため、ExecuteImmediateは自動的にgetRowCountをコールし、その値がこのメソッドの整数の戻り値となります。

FetchNext

int FetchNext (TTStatus & stat)

Executeメソッドを使用して準備済のSQL SELECT文を実行した後、FetchNextメソッドを使用して、応答セットから一度に1行ずつフェッチします。

応答セットから1行をフェッチした後に、オーバーロードされたバージョンのgetColumnメソッドの1つを使用して、現在の行から値をフェッチします。

応答セットに行がなくなると、FetchNextは1を返します。行が返されると、FetchNextは0を返します。

Executeメソッドを使用してSELECTを実行した後、要求されるすべての行がフェッチされてから、Closeメソッドで応答セットを閉じる必要があります。Closeメソッドをコールした後は、FetchNextメソッドを使用して応答セットからそれ以上の行をフェッチできないことに注意してください。

例外が有効な場合は、エラーが発生するとTTStatusオブジェクトが例外として返されます。例外が無効な場合は、メソッドから返される際に、発生したエラーに関する情報が、最後のパラメータとしてメソッドに渡されたTTStatus&オブジェクトに格納されます。

Close

void Close (TTStatus&)

Executeメソッドを使用してSQL SELECT文を実行すると、応答セットから行をフェッチするために使用できるカーソルがオープンされます。アプリケーションでの行のフェッチが完了したら、Closeメソッドを使用してカーソルをクローズする必要があります。

応答セットのクローズに失敗すると、行のロックが保持される時間が長くなりすぎるため、同時実行性の問題、メモリ・リークおよびその他のエラーが発生する可能性があります。

例外が有効な場合は、エラーが発生するとTTStatusオブジェクトが例外として返されます。例外が無効な場合は、メソッドから返される際に、発生したエラーに関する情報が、最後のパラメータとしてメソッドに渡されたTTStatus&オブジェクトに格納されます。

Drop

void Drop (TTStatus&)

準備済のSQL文を今後使用しない場合は、Dropメソッドをコールして、その文とそれに関連付けられたリソースを解放できます。再度Prepareをコールすると、TTCmdオブジェクトを別の文に再利用できます。

複数のTTCmdオブジェクトを使用して複数のSQL文を実行した方が、より効率的です。特定のSQL文を今後使用しないことが確実な場合にのみ、Dropメソッドを使用してください。

例外が有効な場合は、エラーが発生するとTTStatusオブジェクトが例外として返されます。例外が無効な場合は、メソッドから返される際に、発生したエラーに関する情報が、最後のパラメータとしてメソッドに渡されたTTStatus&オブジェクトに格納されます。

setQueryTimeout

void setQueryTimeout (const int nSecs, TTStatus&)

このメソッドでは、必要に応じて、問合せでタイムアウト値を設定して、アプリケーションによって長時間実行問合せを停止できます。nSecsはタイムアウトの秒数です。

デフォルトの問合せタイムアウト値は存在しないことに注意してください。

setMaxRows

void setMaxRows (const int nRows, TTStatus &stat)

このメソッドは、SELECT文によって返される行数に制限を設定します。結果セットの行数が設定された上限を超える場合、設定された最大行数を超えてフェッチすると、文はSQL_NO_DATA_FOUNDを返します。eof()メソッドがコールされると、TTCmdオブジェクトはTRUEを返します。デフォルトでは、すべての行が返されます。すべての行を返すように制限をリセットするには、nRowsを0に設定してsetMaxRowsをコールします。この制限はSELECT文に対してのみ意味があります。

getMaxRows

int getMaxRows (TTStatus &stat)

このメソッドは、SELECT文によってこのTTCmdコールから返される行数について現在設定されている上限を返します。戻り値0は、すべての行が返されることを示します。

getRowCount

int getRowCount()

このメソッドをExecuteの直後にコールして、直前に実行されたSQL操作の影響を受けた行の数を返すことができます。たとえば、10行を削除するDELETE文が実行された後には、getRowCountは10を返します。

setParam

void setParam (int pno, ...)

この項では、オーバーロードされたすべてのsetParamメソッドについて説明します。

準備済のSQL文を実行する前に、setParamメソッドを使用してパラメータの値を設定します。SQL文は、使用前にPrepareメソッドで準備され、Executeメソッドで実行されます。SQL文にパラメータ・マーカー(リテラル定数が有効である位置で使用される?文字)が含まれている場合、そのSQL文を実行するには、それらのパラメータに値を割り当てる必要があります。文を実行する前に、setParamメソッドを使用して各パラメータの値を定義します。『Oracle TimesTen In-Memory Database SQLリファレンス・ガイド』の動的パラメータに関する説明を参照してください。

setParamに最初に渡される引数は、設定されるパラメータの位置です。SQL文の最初(一番左)のパラメータはパラメータ1です。setParamに2番目に渡される引数はパラメータの値です。オーバーロードされた様々なバージョンのsetParamは、2番目の引数で様々なデータ型を受け入れます。

このバージョンのTTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。準備済のSQLのパラメータごとに、オーバーロードされた適切なバージョンのsetParamをコールする必要があります。誤ったバージョンをコールする(たとえば、整数パラメータをchar*値に設定しようとする)と、プログラム障害が発生するおそれがあります。

setParamに渡された値は、TTCmdオブジェクトによって保守される内部バッファにコピーされます。これらのバッファは静的に割り当てられ、Prepareメソッドによってバインドされます。パラメータ値はsetParamのコール時にsetParamに渡される値であって、後続のExecuteメソッドのコール時の値ではありません。

表3.1に、サポートされるSQLデータ型と、各パラメータ型での使用に適したsetParamのバージョンを示します。表に示されていないSQLデータ型は、このバージョンのTTClassesではサポートされないことに注意してください。

表3.1 サポートされるデータ型に対するTTCmd::setParamのバージョン
データ型
サポートされるsetParamのバージョン
TT_TINYINT
setParam (int, unsigned char)
TT_SMALLINT
setParam (int, SQLSMALLINT)
TT_INTEGER
setParam (int, SQLINTEGER)
TT_BIGINT
setParam (int, SQLBIGINT)
BINARY_FLOAT
setParam (int, float)
BINARY_DOUBLE
setParam (int, double)
NUMBER
TT_DECIMAL
setParam (int, char*)
setParam (int, const char*)
setParam (int, SQLTINYINT)
setParam (int, SQLSMALLINT)
setParam(int, SQLINTEGER)
setParam (int, SQLBIGINT)
注意: 整数型のメソッドは、たとえばNUMBER(8)やNUMBER(8,0)など、スケール・パラメータを0(ゼロ)に設定して宣言された列にのみ適しています。
TT_CHAR
CHAR
TT_VARCHAR
VARCHAR2
setParam (int, char*)
setParam (int, const char*)
TT_NCHAR
NCHAR
NVARCHAR2
setParam (int, SQLWCHAR*, int len)
BINARY
VARBINARY
setParam (int, const void*, int len)
DATE
TT_TIMESTAMP
TIMESTAMP
setParam (int, TIMESTAMP_STRUCT*)
TT_DATE
setParam (int, DATE_STRUCT*)
TT_TIME
setParam (int, TIME_STRUCT*)

setParamNull

void setParamNull (int pno)

このメソッドを使用して、パラメータ番号pnoの値をSQLのNULL値に指定できます。

「setParam」を参照してください。

getParamPrecision

int getParamPrecision(int pno)

このメソッドは、パラメータ番号pnoの精度を返します。

getParamScale

int getParamScale(int pno)

このメソッドは、パラメータ番号pnoのスケールを返します。

getParamNull

bool getParamNull(int pno);

このメソッドは、パラメータ番号pnoをNULLにできるかどうかを示します。

getColumn

void getColumn (int cno, ...)

getColumnおよびgetColumnNullableメソッドを使用して、応答セットの現在の行の列値をフェッチできます。getColumnおよびgetColumnNullableメソッドを使用するには、まずFetchNextメソッドを使用して、SELECT文の応答セットから最初(または次)の行をフェッチする必要があります。SQL文はExecuteメソッドを使用して実行されます。

getColumnメソッドは、特定の列に関連付けられた値を返します。列は序数で参照され、「1」はSELECT文で指定された最初の列を示します。すべての場合において、getColumnメソッドに渡される最初の引数は、値がフェッチされる列の序数です。getColumnメソッドに渡される2番目の引数は、指定された列の値を受け取る変数のポインタです。この引数の型は、返される列の型に依存します。

このバージョンのTTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。準備済のSQLの出力列ごとに、オーバーロードされた適切なバージョンのgetColumnをコールする必要があります。誤ったバージョンをコールする(たとえば、整数の列をchar*値にフェッチしようとする)と、プログラム障害が発生するおそれがあります。

整数型のメソッドには、SQLTINYINT、SQLSMALLINT、SQLINTEGERおよびSQLBIGINTのいずれかの関数が含まれています。これらのメソッドは、たとえばNUMBER(p)やNUMBER(p,0)など、スケール・パラメータが0(ゼロ)に設定された列にのみ適しています。前述の関数の精度範囲を次に示します。

関数
精度範囲
SQLTINYINT
0<=p<=2
SQLSMALLINT
0<=p<=4
SQLINTEGER
0<=p<=9
SQLBIGINT
0<=p<=18

アプリケーションがデータベースから情報を取得するために使用する変数に列内のすべての値が適合するようにするには、表のデータ型NUMBER(p)の列すべてに対してSQLBIGINTを使用します。ここで、0 <= p <= 18です。次に例を示します。

getColumn(int cno, SQLBIGINT*)

表3.2に、サポートされるSQLデータ型と、各パラメータ型での使用に適したgetColumnおよびgetColumnNullableのバージョンを示します。

表3.2 サポートされるデータ型に対するTTCmd::getColumn[Nullable]のバージョン
データ型
サポートされるgetColumnのバージョン
TT_TINYINT
getColumn (int cno, unsigned char*)
getColumnNullable (int cno, SQLTINYINT*)
TT_SMALLINT
getColumn (int cno, SQLSMALLINT*)
getColumnNullable (int cno, SQLSMALLINT*)
TT_INTEGER
getColumn (int cno, SQLINTEGER*)
getColumnNullable (int cno, SQLINTEGER*)
TT_BIGINT
getColumn (int cno, SQLBIGINT*)
getColumnNullable (int cno, SQLBIGINT*)
BINARY_FLOAT
getColumn (int cno, float*)
getColumnNullable (int cno, float*)
BINARY_DOUBLE
getColumn (int cno, double*)
getColumnNullable (int cno, double*)
NUMBER
TT_DECIMAL
getColumn (int cno, char**)
getColumn(int cno, SQLTINYINT*)
getColumn (int cno, SQLSMALLINT*)
getColumn (int cno, SQLINTEGER*)
getColumn (int cno, SQLBIGINT*)
getColumnNullable (int cno, char**)
getColumnNullable (int cno, SQLTINYINT*)
getColumnNullable (int cno, SQLSMALLINT*)
getColumnNullable (int cno, SQLINTEGER*)
getColumnNullable (int cno, SQLBIGINT*)
注意: 整数型のメソッドは、スケール・パラメータを0(ゼロ)に設定して宣言された列にのみ適しています。
TT_CHAR
CHAR
TT_VARCHAR
VARCHAR2
getColumn (int cno, char**)
getColumnNullable (int cno, char**)
TT_NCHAR
NCHAR
TT_NVARCHAR
NVARCHAR2
getColumn (int cno, SQLWCHAR*)
getColumnNullable (int cno, SQLWCHAR*)
BINARY
VARBINARY
void getColumn (int cno, void** binPP, int* lenP)
void getColumnNullable (int cno, void** binPP, int* lenP)
DATE
TT_TIMESTAMP
TIMESTAMP
getColumn (int cno, TIMESTAMP_STRUCT*)
getColumnNullable (int cno, TIMESTAMP_STRUCT*)
TT_DATE
getColumn (int cno, DATE_STRUCT*)
getColumnNullable (int cno, DATE_STRUCT*)
TT_TIME
getColumn (int cno, TIME_STRUCT*)
getColumnNullable (int cno, TIME_STRUCT*)

このリリースのTTClassesライブラリでは、他のSQLデータ型はサポートされません。

isColumnNull

bool isColumnNull (int cno)

このメソッドは、列番号cnoの値がNULLかどうかを決定するもう1つの方法です。

「getColumnNullable」を参照してください。

getColumnLength

int getColumnLength (int cno)

このメソッドは、列番号cnoの長さを返します。通常、VARBINARYまたはNVARCHAR2型の列にアクセスする場合のみ有効です。返される値は、0から列の精度の間の値です。「getColumnPrecision」を参照してください。

getColumnNullable

bool getColumnNullable (int cno, ...)

getColumnNullableメソッドはgetColumnメソッドに類似しています。ただし、getColumnNullableメソッドはgetColumnの動作に加え、列の値がSQLのNULL擬似値であるかどうかも返します。列の値がNULLである場合、2番目のパラメータの値は特徴的な値(-9999など)に設定され、メソッドの戻り値はTRUEとなります。列の値がNULLでない場合、2番目のパラメータが指す変数で列の値が返され、getColumnNullableメソッドはFALSEを返します。

「getColumn」を参照してください。

getNextColumn

void getNextColumn (int iP, ...)

getNextColumnおよびgetNextColumnNullableメソッドを使用して、応答セットの次の行の列値をフェッチできます。getNextColumnおよびgetNextColumnNullableメソッドを使用するには、まずFetchNextメソッドを使用して、SELECT文の応答セットから最初の行をフェッチする必要があります。iPは内部列番号へのポインタを表します。getNextColumnを使用する場合、列は順番にフェッチされます。フェッチする順番は変更できません。

サポートされるSQLデータ型と、各パラメータ・タイプで使用する適切なgetColumnのバージョンについては、表3.2を参照してください。この情報は、getNextColumnに対して使用できます。

getNextColumnNullable

bool getColumnNullable (int iP, ...)

getNextColumnNullableメソッドはgetNextColumnメソッドに類似しています。ただし、getNextColumnNullableメソッドはgetColumnの動作に加え、列の値がSQLのNULL擬似値であるかどうかも返します。列の値がNULLである場合、2番目のパラメータの値は特徴的な値(-9999など)に設定され、メソッドの戻り値はTRUEとなります。列の値がNULLでない場合、2番目のパラメータが指す変数で列の値が返され、getColumnNullableメソッドはFALSEを返します。

iPは内部列番号へのポインタを表します。getNextColumnを使用する場合、列は順番にフェッチされます。フェッチする順番は変更できません。

サポートされるSQLデータ型と、各パラメータ・タイプで使用する適切なgetColumnのバージョンについては、表3.2を参照してください。この情報は、getNextColumnNullableに対して使用できます。

printColumn

void printColumn (int cno, STDOSTREAM & os,

                  const char * nullString) const

このメソッドは、列番号cnoを出力ストリームに出力します。デバッグまたはデモ・プログラム用に使用します。

使用方法

プログラムで複数回実行される各SQL文には、独自のTTCmdオブジェクトが必要です。これらのTTCmdオブジェクトは、プログラムの初期化時にそれぞれ1回準備され、プログラムの実行時にExecuteメソッドで複数回実行されます。

ExecuteImmediateメソッドは、1回だけ実行する必要のあるデータベース操作でのみ使用します。ExecuteImmediateはどのタイプのSELECT文とも互換性がないことに注意してください(かわりに、すべての問合せでPrepareとExecuteを使用する必要があります)。また、ExecuteImmediateは、後で、挿入、更新または削除された行数を調べるために、getRowcountによって問い合されるINSERT/UPDATE/DELETE文とも互換性がありません。これらの制限は、一部の状況(表の作成または削除など)を除き、ExecuteImmediateの使用を避けるために課されています。

準備済のTTCmdオブジェクトのプロパティを取得するためのメソッド

準備済のTTCmdオブジェクトの、バインドされた入力パラメータおよび出力列のプロパティについて問い合せる場合に有効なメソッドがいくつかあります。通常、これらのメソッドでは、文が事前に準備されている場合にのみ、有効な結果が得られます。

getNParameters

int getNParameters ()

このメソッドは、入力パラメータの数を返します。

getNColumns

int getNColumns ()

このメソッドは、出力列の数を返します。

getParamType

int getParamType (int pno)

このメソッドは、パラメータ番号pnoのデータ型を返します。返される値は、sql.hに見られる、パラメータのODBC型(SQL_INTEGER、SQL_REAL、SQL_BINARY、SQL_CHARなど)です。その他のTimesTen型(SQL_WCHAR、SQL_WVARCHAR)は、TimesTenヘッダー・ファイルtimesten.hで見られます。

getColumnName

const char * getColumnName (int cno)

このメソッドは、列番号cno の名前を返します。

getColumnType

int getColumnType (int cno)

このメソッドは、列番号cnoのデータ型を返します。返される値は、sql.hに見られる、パラメータのODBC型(SQL_INTEGER、SQL_REAL、SQL_BINARY、SQL_CHARなど)です。その他のTimesTen型(SQL_WCHAR、SQL_WVARCHAR)は、TimesTenヘッダー・ファイルtimesten.hで見られます。

getColumnPrecision

int getColumnPrecision (int cno)

このメソッドは、列番号 cnoの精度を返します。通常、この値は、表のCHAR、VARCHAR2、BINARY、VARBINARY、NCHARおよびNVARCHAR2型の列から出力を生成する場合にのみ重要です。

getColumnScale

int getColumnScale(int cno)

このメソッドは、列番号cno のスケールを返します。

バッチ操作

TimesTenは、挿入、更新および削除のバッチ操作のためにODBC関数SQLBindParamsをサポートします。TTClassesはSQLBindParamsへのインタフェースを提供します。

TTClassesでのバッチ操作は、非バッチ操作と同様に実行されます。最初に、SQL文がPrepareBatchによってコンパイルされます。次に、その文の各パラメータが、BindParameterによって値の配列にバインドされます。最後に、ExecuteBatchによって文が実行されます。通常のTTClasses(非バッチ)操作との類似性に注意してください。Prepareによって文がコンパイルされ、すべてのパラメータのバインドの自動的に実行され、Executeによって文が実行されます。

バッチ操作機能の使用例は、install_dir/demo/ttclassesのTTClassesサンプル・プログラムbulktest.cppを参照してください。

この項では、TTClassesユーザー向けに、バッチの挿入/更新/削除機能を公開するTTCmdメソッドについて説明します。

PrepareBatch

void PrepareBatch(TTConnection*, const char * sqlP,

     TTCmd::TTCMD_USER_BIND_LEVEL level,

     unsigned short batchSize, TTStatus&)

PrepareBatchは、INSERT/UPDATE/DELETE文のバッチ操作に使用されるPrepareの類似メソッドです。TTConnection*、const char*sqlPおよびTTStatus&パラメータは、Prepareメソッドの場合と同様に使用されます。

levelパラメータに有効な値は次の1つのみです。

TTCmd::TTCMD_USER_BIND_PARAMS

batchSizeパラメータは、ExecuteBatchへの後続のコールによって実行される挿入/更新/削除操作の最大数を指定します。

BindParameter

void BindParameter(int pno, unsigned short batchSize,

       TYPE*, [SQLLEN*], TTStatus&)

この項では、オーバーロードされたBindParameterメソッドについて説明します。

BindParameterメソッドは、PrepareBatchによってコンパイルされた文について、値の配列(各パラメータに1つ)をバインドするために使用されます。このコールのbatchSizeパラメータは、PrepareBatchで指定されたbatchSizeの値と一致する必要があります。同様に、バインドされた配列には、PrepareBatchのバインドされた配列以上の値が含まれる必要があります。ユーザーは、各パラメータにバインドする正しい型を判別する必要があります。誤った型をバインドすると、TTLog::TTLOG_ERRロギング・レベルのTTClassesグローバル・ロギング機能に実行時エラーが書き込まれることに注意してください。

ExecuteBatchを起動するたびに、ユーザー・アプリケーションで事前にこれらの配列に有効なパラメータ値を設定する必要があります。

4つのSQL型(SQL_[VAR]BINARYおよびSQL_W[VAR]CHAR)については、追加のSQLLEN*パラメータ(パラメータの長さの配列)が必要です。この追加配列の長さは、batchSizeの長さ以上であり、ExecuteBatchのコール前に、有効な長さの値が設定されている必要があります。

表3.3に、サポートされるSQLデータ型と、各パラメータ型での使用に適したBindParameterのバージョンを示します。

表3.3 サポートされるデータ型に対するTTCmd::BindParameterのバージョン
SQLデータ型
サポートされるBindParameterのバージョン
TT_TINYINT
BindParameter (... SQLTINYINT*...)
TT_SMALLINT
BindParameter (...SQLSMALLINT*...)
TT_INTEGER
BindParameter (...SQLINTEGER*...)
TT_BIGINT
BindParameter (...SQLBIGINT*...)
BINARY_FLOAT
BindParameter (...float*...)
BINARY_DOUBLE
BindParameter (...double*...)
NUMBER
TT_DECIMAL
BindParameter (...char**...)
TT_CHAR
CHAR
TT_VARCHAR
VARCHAR2
BindParameter (...char**...)
TT_NCHAR
NCHAR
TT_NVARCHAR
NVARCHAR2
BindParameter (...SQLWCHAR**, SQLLEN*...)
BINARY
VARBINARY
BindParameter (...const void**, SQLLEN*...)
DATE
TT_TIMESTAMP
TIMESTAMP
BindParameter (... TIMESTAMP_STRUCT*...)
TT_DATE
BindParameter (...DATE_STRUCT*...)
TT_TIME
BindParameter (...TIME_STRUCT*...)

setParamLength

setParamLength(int pno, unsigned short rowno, int len)

このメソッドは、ExecuteBatchをコールする前に、バインドされたいずれかのパラメータ値の長さを設定します。pnoは、文内のどのパラメータを設定するかを指定します。rownoは、長さを設定する行を指定します。lenは、設定する長さを指定します。

SQL_[VAR]BINARYおよびSQL_W[VAR]CHAR以外の型については、ExecuteBatchをコールする前にパラメータの長さを明示的に設定するために使用できるメソッドはこれのみです。SQL_[VAR]BINARYおよびSQL_W[VAR]CHAR型については、BindParameterコールの4番目のパラメータであるSQLLEN*配列の操作によって、長さを明示的に設定することもできます。

setParamNull

setParamNull(int pno, unsigned short rowno)

このメソッドは、ExecuteBatchをコールする前に、バインドされたいずれかのパラメータ値をNULLに設定します。1番目のパラメータpnoは、文内のどのパラメータを設定するかを指定します。2番目のパラメータrownoは、長さを設定する行を指定します。

SQL_[VAR]BINARYおよびSQL_W[VAR]CHAR以外の型については、ExecuteBatchをコールする前にパラメータ値がNULLであることを明示的に設定するために使用できるメソッドはこれのみです。SQL_[VAR]BINARYおよびSQL_W[VAR]CHAR型については、BindParameterコールの4番目のパラメータであるSQLLEN*配列の操作によって、NULLであることを明示的に設定することもできます。

ExecuteBatch

void ExecuteBatch(unsigned short numRows, TTStatus&)

このメソッドはバッチ内の更新された行数を返します。この数は、ODBC SQLSetParamsコールからの*pirowを表します。

PrepareBatchによってSQL文を準備し、そのSQL文の各パラメータ(「?」)に対してBindParameterをコールした後、ExecuteBatchを使用してその文をnumRows回実行します。numRowsの値は、PrepareBatchおよびBindParameterのコールで指定したbatchSize以下にする必要があります。アプリケーション・ロジックで必要な場合は、numRowsbatchSizeより小さくすることは可能です。

アプリケーションでは、ExecuteBatchをコールする前に、BindParameterでバインドされたパラメータの配列に有効な値を設定する必要があります。必要に応じて、setParamNullによってNULL値を指定できます。

install_dir/demo/ttclassesにあるデモbulktest.cppで、ExecuteBatchの使用方法が示されています。また、例3.6にも、ExecuteBatchの使用方法を示します。

例3.6

2つの列を持つ表を作成します。

CREATE TABLE batch_table (a TT_INTEGER, b VARCHAR2(100));

サイズが50のバッチで表の行を移入します。

#define BATCH_SIZE 50

#define VARCHAR_SIZE 100

int int_array[BATCH_SIZE];

char char_array[BATCH_SIZE][VARCHAR_SIZE];

// Prepare the statement

TTCmd insert;

TTConnection connection;

TTStatus stat;

// (assume a connection has already been established)

try {

  insert.PrepareBatch (&connection,

                       (const char*)"insert into batch_table                        values (?,?)",

                       TTCmd::TTCMD_USER_BIND_PARAMS,

                       BATCH_SIZE

                       stat);

// Commit the prepared statement

connection.Commit(stat);

// Bind the arrays of parameters

insert.BindParameter(1, BATCH_SIZE, int_array, stat);

insert.BindParameter(2, BATCH_SIZE, char_array, stat);

// Execute 5 batches, inserting 5 * BATCH_SIZE rows into

// the database

for (int iter = 0; iter < 5; iter++)

{

       // Populate the value arrays with values.

       // (A better way of putting meaningful data into

       // the database is to read values from a file,

       // rather than generating them arbitrarily.)

       for (int i = 0; i < BATCH_SIZE; i++)

      {

         int_array[i] = i * iter + i;

         sprintf(char_array[i], "varchar value # %d", i*iter+ i);

      }

       // Execute the batch insert statement,

       // which inserts the entire contents of the

       // integer and char arrays in one operation.

       int num_ins = insert.ExecuteBatch(BATCH_SIZE, stat);

       cerr << "Inserted " << num_ins << " rows." << endl;

       connection.Commit(stat);

   } // for iter

たとえば、列の1つに一意制約が指定されている場合などは、行数(この例ではnum_ins)をBATCH_SIZEよりも少なくすることができます。この場合は、トランザクションをロールバックし、次のようなコードを使用します。

例3.7

for (int iter = 0; iter < 5; iter++)

    {

       // Populate the value arrays with values.

       // (A better way of putting meaningful data into

       // the database is to read values from a file,

       // rather than generating them arbitrarily.)

       for (int i = 0; i < BATCH_SIZE; i++)

       {

          int_array[i] = i * iter + i;

          sprintf(char_array[i], "varchar value # %d", i*iter+i);

       }

       // now we execute the batch insert statement,

       // which does the work of inserting the entire

       // contents of the integer and char arrays in

       // one operation

       int num_ins = insert.ExecuteBatch(BATCH_SIZE, stat);

       cerr << "Inserted " << num_ins << " rows (expected " <<

            << BATCH_SIZE << " rows)." << endl;

       if (num_ins == BATCH_SIZE) {

         cerr << "Committing batch" << endl;

         connection.Commit(stat);

       }

       else {

         cerr << "Some rows were not inserted as expected, rolling back "

              << "transaction." << endl;

         connection.Rollback(stat);

         break; // jump out of batch insert loop

       }

   } // for iter

SQLParamOptionsについては、ODBCのマニュアルを参照してください。TTCmd::ExecuteBatchの整数出力は、SQLParamOptionsの3番目のパラメータである*pirowです。