TTCmdリファレンス
TTCmdオブジェクトは、アプリケーション・プログラムで複数回使用される単一のSQL文をカプセル化します。TTCmdは、ODBC文ハンドル(SQLHSTMT)の付加価値C++ラッパーとみなすことができます。TTCmdには、次の3種類のパブリック・メソッドがあります。
パブリック・メンバー
| メンバー | 説明 |
|---|---|
|
|
これは、パラメータの登録時、そのパラメータが入力、出力または入力/出力のどれかを指定するために使用します。サポートされる値は、 |
一般的な用途およびバッチ以外の操作用のパブリック・メソッド
この項では、一般的な用途およびバッチ以外の操作用のTTCmdパブリック・メソッドの概要を説明します。
一般的な用途およびバッチ以外の操作用のパブリック・メソッドの概要
| メソッド | 説明 |
|---|---|
|
アプリケーションでの行のフェッチが終了したら、結果セットを閉じます。 |
|
|
準備済のSQL文とそれに関連付けられたすべてのリソースを解放します。 |
|
|
実行のために準備されたSQL文を起動します。 |
|
|
事前に準備されていないSQL文を起動します。 |
|
|
結果セットの行を1行ずつフェッチします。行のフェッチに成功した場合は0を、フェッチする行がなくなった場合は1を返します。 |
|
|
結果セットの現在の行の指定した列の値を取得します。 |
|
|
指定された列の長さをバイト単位で返します。 |
|
|
結果セットの現在の行の指定した列の値を取得し、値が |
|
|
基礎となるODBC文ハンドルを取得します。 |
|
|
|
|
|
結果セットの現在の行の次の列の値を取得します。 |
|
|
結果セットの現在の行の次の列の値を取得し、値が |
|
|
準備済のSQL文の実行後、各コールは指定した出力または入力/出力パラメータの出力値を取得します。 |
|
|
問合せのしきい値を取得します。 |
|
|
最近実行されたSQL操作の影響を受けた行の数を返します。 |
|
|
現在の列の指定した行値が |
|
|
SQL文と |
|
|
現在の行の指定した列の値を出力ストリームに出力します。 |
|
|
バインド用にパラメータを登録します。これは、入力または入力/出力パラメータで必要です。 |
|
|
|
|
|
準備済のSQL文を実行する前に、各コールは指定したパラメータの値を設定します。 |
|
|
指定した入力パラメータの長さをバイト単位で設定します。 |
|
|
準備済のSQL文を実行する前にパラメータの値を |
|
|
各SQL文の実行時間制限のしきい値を設定します。これを超えた場合、警告がサポート・ログに書き込まれます。 |
|
|
SQL文のタイムアウト値を設定します。 |
Close()
void Close()
Execute()メソッドを使用してSQL SELECT文を実行すると、結果セットから行をフェッチするために使用できるカーソルがオープンされます。アプリケーションが結果セットから行をフェッチし終えたら、Close()メソッドを使用してクローズする必要があります。
結果セットを閉じることに失敗すると、行のロックが保持される時間が長くなりすぎるため、同時実行性の問題、メモリー・リークおよびその他のエラーが発生する可能性があります。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
Drop()
void Drop()
準備済のSQL文を今後使用しない場合は、Drop()メソッドをコールして、その文とそれに関連付けられたリソースを解放できます。再度Prepare()をコールすると、TTCmdオブジェクトを別の文に再利用できます。
複数のTTCmdオブジェクトを使用して複数のSQL文を実行した方が、より効率的です。特定のSQL文を今後使用しない場合にのみ、Drop()メソッドを使用してください。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
Execute()
void Execute()
setParam()コールで必要なパラメータ値を定義後、このメソッドは、Prepare()メソッドを使用して実行されるよう事前準備されたSQL文を起動します。エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
SQL文がSELECT文の場合は、このメソッドによって問合せが実行されますが、結果セットから行が返されません。FetchNext()メソッドを使用すると、結果セットから一度に1行ずつフェッチされます。該当するすべての行がフェッチされたら、Close()メソッドを使用して結果セットを閉じます。SELECT以外のSQL文の場合は、カーソルがオープンされないため、Close()メソッドをコールする必要はありません。
ExecuteImmediate()
int ExecuteImmediate(TTConnection* cP, const char* sqlp)このメソッドは、事前に準備されていないSQL文を起動します。
少数回のみ実行されるSQL文については、Prepare()およびExecute()のかわりにExecuteImmediate()を使用すると便利です。DDL文(CREATE TABLE、DROP TABLEなど)や、使用頻度が低く結果セットを返さないDML文(DELETE FROM table_nameなど)にExecuteImmediate()を使用します。
ExecuteImmediate()は、結果セットを返すSQL文と互換性がありません。また、ExecuteImmediate()によって実行された文は、後でgetRowCount()(DML操作によって影響を受けた行の数を取得する)を使用して問い合せることができません。このため、ExecuteImmediate()は自動的にgetRowCount()をコールし、その値がこのメソッドの整数の戻り値となります。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
FetchNext()
int FetchNext()
Execute()メソッドを使用して準備済のSQL SELECT文を実行した後、FetchNext()メソッドを使用して、結果セットから一度に1行ずつフェッチします。
結果セットから1行をフェッチした後に、オーバーロードされた適切なgetColumn()メソッドを使用して、現在の行から値をフェッチします。
結果セットに行がなくなると、FetchNext()は1を返します。行が返されると、FetchNext()は0を返します。
Execute()メソッドを使用してSELECTを実行した後、要求されるすべての行がフェッチされてから、Close()メソッドで結果セットを閉じる必要があります。Close()メソッドをコールした後は、FetchNext()メソッドを使用して結果セットからそれ以上の行をフェッチできないことに注意してください。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
getColumn()
void getColumn (int cno, TYPE* valueP)
void getColumn (int cno, TYPE* valueP, SQLLEN* byteLenP)getColumn()メソッドおよびgetColumnNullable()メソッドでは、結果セットの現在の行の列の値をフェッチできます。getColumn()またはgetColumnNullable()をコールする前に、FetchNext()メソッドをコールして、SELECT文の結果セットの次の(または最初の)行をフェッチする必要があります。SQL文はExecute()メソッドを使用して実行されます。
次の表3-2には、サポートされるTimesTenの列型と、各パラメータ型での使用に適したgetColumn()とgetColumnNullable()のバージョンを示します。(ただし、この表には示されていませんが、getColumnNullable()はブール値も返すことに注意してください。このセクションで後述するgetColumnNullable()メソッドのドキュメントを参照してください)。
各getColumn()コールは、特定の列に関連付けられた値を返します。列は序数で参照され、1はSELECT文で指定された最初の列を示します。すべての場合において、getColumn()メソッドに渡される最初の引数cnoは、値がフェッチされる列の序数です。2番目の引数valuePは、指定された列の値を保存する変数のポインタです。この引数の型は、返される列の型に依存します。表に示すとおり、NCHAR、NVARCHARおよびバイナリ型については、メソッド・コールでbyteLenPを指定します(これは、valuePバッファに書き込まれるバイト数の整数値へのポインタです)。
TTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。準備済のSQLの出力列ごとに、適切なバージョンのgetColumn()をコールする必要があります。誤ったバージョンをコールする(たとえば、整数の列をchar*値にフェッチしようとする)と、例外がスローされます(TTStatusオブジェクト)。
NUMBER列から整数型のデータをフェッチする場合、getColumn()では、SQLTINYINT、SQLSMALLINT、SQLINTEGERおよびSQLBIGINTのバージョンがサポートされています。これらは、スケール・パラメータが0に設定された、NUMBER(p)またはNUMBER(p,0)などのNUMBERフィールドのみに適しています。前述の関数の精度範囲を次に示します。
| ファンクション | 精度範囲 |
|---|---|
|
|
0<= |
|
|
0<= |
|
|
0<= |
|
|
0<= |
アプリケーションがデータベースから情報を取得するために使用する変数に列内のすべての値が収まるようにするには、データ型NUMBER(p)のすべての表列に対してSQLBIGINTを使用します(ここで、0 <= p <= 18です)。次に例を示します。
getColumn(int cno, SQLBIGINT* iP)この表は、サポートされるSQLデータ型と、各データ型での使用に適したgetColumnおよびgetColumnNullableの入力シグネチャを示しています。このデータ型のサポートは、getNextColumn、getNextColumnNullableおよびgetParamにも適用されます。
表3-2 サポートされるTimesTenの表の列型に対するgetColumn()およびgetColumnNullable()の入力シグネチャ
| データ型 | サポートされるgetColumn()およびgetColumnNullable()の入力シグネチャ |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ノート: |
|
|
ノート: |
|
|
ノート: オプションで、返される値のバイト数に関する |
|
|
ノート: |
|
|
|
|
|
|
|
|
|
このリリースのTTClassesライブラリでは、他のTimesTen表列型はサポートされていません。
getColumnLength()
SQLULEN getColumnLength(int cno)NULL終了文字はカウントされない、現在の行の列番号cnoの値の長さをバイト単位で返します。また、値がNULLの場合はSQL_NULL_DATAが返されます。(ODBCに詳しいユーザー向け: これは、SQLFetchへのコール後に、ODBCによってSQLBindColから最後のパラメータのpcbValueに保存される値です)。NULLでない値がある場合、0から行の精度の間の長さが返されます。getColumnPrecision()を参照してください。
たとえば、VARCHAR2(25)列を考えてみてください。この値がNullの場合、返される長さは-1になります。この値がabcdeの場合、返される長さは5になります。
このメソッドは、CHAR、VARCHAR2、NCHAR、NVARCHAR2、BINARYおよびVARBINARY型の列にアクセスする場合のみ通常役立ちます。
getColumnNullable()
bool getColumnNullable(int cno, TYPE* valueP)
bool getColumnNullable(int cno, TYPE* valueP, SQLLEN* byteLenP)getColumnNullable()メソッドはgetColumn()メソッドと類似しており、前述の表3-2のとおり同じデータ型およびシグネチャをサポートしています。ただし、getColumn()の動作に加えて、getColumnNullable()メソッドは値がSQLのNULL疑似値であるかどうかを示すブールを返します。値がNULLである場合、2番目のパラメータは特徴的な値(-9999など)に設定され、メソッドの戻り値はTRUEとなります。値がNULLでない場合、2番目のパラメータが指す変数を介して値は返され、getColumnNullable()メソッドによってFALSEが返されます。
getHandle()
SQLHSTMT getHandle()基礎となるODBC文オブジェクトを操作する必要がある場合、このメソッドを使用して文ハンドルを取得します。
getMaxRows()
SQLULEN getMaxRows()このメソッドは、SELECT文によってこのTTCmdオブジェクトから返される行数について現在設定されている上限を返します。戻り値0は、すべての行が返されることを示します。setMaxRows()も参照してください。
getNextColumn()
void getNextColumn(TYPE* valueP)
void getNextColumn(TYPE* valueP, SQLLEN* byteLenP)getNextColumn()メソッドおよびgetNextColumnNullable()メソッドでは、結果セットの現在の行の次の列の値がフェッチされます。getNextColumn()またはgetNextColumnNullable()をコールする前に、FetchNext()メソッドをコールして、SELECT文の結果セットの次の(または最初の)行をフェッチする必要があります。getNextColumn()を使用する場合、列は順番にフェッチされます。フェッチする順番は変更できません。
サポートされるSQLのデータ型および各データ型の適切なメソッド・バージョンについては、表3-2を参照してください。この情報はgetNextColumn()に使用できますが、getNextColumn()にはcno列番号パラメータはありません。
getNextColumnNullable()
bool getNextColumnNullable(TYPE* valueP)
bool getNextColumnNullable(TYPE* valueP, SQLLEN* byteLenP)getNextColumnNullable()メソッドは、getNextColumn()メソッドに類似しています。ただし、getNextColumnNullable()メソッドはgetNextColumn()の動作に加え、値がSQLのNULL疑似値であるかどうかを示すブールを返します。値がNULLである場合、2番目のパラメータは特徴的な値(-9999など)に設定され、メソッドの戻り値はTRUEとなります。値がNULLでない場合、2番目のパラメータが指す変数を介して値が返され、メソッドはFALSEを返します。getNextColumnNullable()を使用する場合、列は順番にフェッチされます。フェッチする順番は変更できません。
サポートされるSQLのデータ型および各データ型の適切なメソッド・バージョンについては、表3-2を参照してください。この情報は、getNextColumnNullable()に使用できますが、getNextColumnNullable()にはcno列番号パラメータはありません。
getParam()
bool getParam(int pno, TYPE* valueP)
bool getParam(int pno, TYPE* valueP, SQLLEN* byteLenP)各getParam()バージョンは、準備済のSQL文の実行後、パラメータ番号で指定した出力または入力/出力パラメータの値を取得するために使用します。SQL文は、使用前にPrepare()メソッドで準備され、Execute()メソッドで実行されます。getParam()メソッドは、文の実行後、各出力パラメータに適切なデータ型の変数を提供するために使用します。
getParam()に最初に渡される引数は、出力値のパラメータの位置です。SQL文の最初のパラメータはパラメータ1です。getParam()に2番目に渡される引数は、出力値の変数です。オーバーロードされたバージョンのgetParam()は、2番目の引数で様々なデータ型を受け入れます。
getParam()メソッドは、表3-2に記載されているデータ型と同じものをサポートしています。ただし、列番号に対応するcnoのかわりに、getParam()はパラメータ番号に対応するpnoを受け入れます。表に示すとおり、NCHAR、NVARCHARおよびバイナリ型については、メソッド・コールでbyteLenPを指定します(これは、パラメータ値内のバイト数の整数値へのポインタです)。
getParam()では、パラメータ値がNULLの場合はTRUEを返し、それ以外の場合はFALSEを返します。
TTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。準備済のSQLの出力パラメータごとに、オーバーロードされた適切なバージョンのgetParam()をコールする必要があります。誤ったバージョンをコールする(たとえば、整数パラメータをchar*値に使用しようとする)と、プログラム障害が発生するおそれがあります。
getParam()の使用方法の詳細は、出力または入力/出力パラメータのバインドを参照してください。
REF CURSORについては、REF CURSOR (データ型SQL_REFCURSOR)の文ハンドルとしてTTCmdオブジェクトを使用できるよう、次のシグネチャがサポートされています。情報および例については、REF CURSORの使用を参照してください。
bool getParam(int pno, TTCmd** rcCmd)getQueryThreshold()
int getQueryThreshold()
setQueryThreshold()で説明した、TTCmdオブジェクトのしきい値を返します。
setQueryThreshold()で値が設定されていない場合、このメソッドはODBC接続オプションTT_QUERY_THRESHOLD(設定されている場合)の値またはTimesTenの一般接続属性QueryThresholdを返します。
getRowCount()
int getRowCount()
このメソッドをExecute()の直後にコールして、実行されたSQL操作の影響を受けた行の数を返すことができます。たとえば、10行を削除するDELETE文が実行された後には、getRowCount()は10を返します。
isColumnNull()
bool isColumnNull(int cno)このメソッドでも、現在の行の列番号cnoの値がNULLであるかどうかを判断できます(そうである場合はTRUE、そうでない場合はFALSEを返します)。
「getColumnNullable()」メソッドの情報も参照してください。
Prepare()
void Prepare(TTConnection* cP, const char* sqlp)このメソッドは、SQL文とTTCmdオブジェクトを関連付けます。2つのパラメータを使用します。
-
TTConnectionオブジェクトへのポインタTTConnection::Connect()をコールし、接続オブジェクトをデータベースに接続する必要があります。 -
準備されているSQL文の
const char*パラメータ
ノート:
-
クライアント/サーバー接続を使用している場合に、クライアントとサーバー間の不要なラウンドトリップを回避するために、
Prepare()メソッドによって遅延準備と呼ばれる処理が実行され、リクエストは要求されるまでサーバーに送信されません。Oracle TimesTen In-Memory Database C開発者ガイドのTimesTenの遅延準備を参照してください。 -
デフォルトでは(接続属性が
PrivateCommands=0の場合)、TimesTenは準備されたSQL文を接続間で共有するため、それ以降の別の接続での同じSQL文の準備はすばやく実行されます。
printColumn()
void printColumn(int cno, STDOSTREAM& os, const char* nullString) constこのメソッドでは、出力ストリームosに現在の行の列番号値cnoを出力します。これは、デバッグまたはデモ・プログラム用に使用します。nullStringでは、列値がNULLの場合(たとえば"NULL"または"?")の場合、何を出力するかを指定します。
registerParam()
void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType,
short sqltype)
void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType,
short sqltype, int precision)
void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType,
short sqltype, int precision, short scale)このメソッドは、バインド用のパラメータを登録するために使用します。これは出力および入力/出力パラメータで必要で、SQLデータ型、精度(該当する場合、データ型で使用される最大桁数)、スケール(該当する場合、小数点以下の最大桁数)を必要に応じて指定するためにも使用できます。パラメータの登録を参照してください。
setMaxRows()
void setMaxRows(const int nMaxRows)このメソッドは、SELECT文によって返される行数に制限を設定します。結果セット内の行数が設定された上限を超過すると、リクエストされた設定サイズの最後の行のフェッチ後にTTCmd::FetchNext()メソッドによって1が返されます。getMaxRows()も参照してください。
デフォルトでは、すべての行が返されます。すべての行を返すように制限をリセットするには、nMaxRowsを0に設定してsetMaxRows()をコールします。この制限はSELECT文に対してのみ意味があります。
setParam()
void setParam(int pno, TYPE value)
void setParam(int pno, TYPE* valueP)
void setParam(int pno, TYPE* valueP, int byteLen)この項では、オーバーロードされたすべてのsetParam()バージョンについて説明します。
各setParam()バージョンは、準備済のSQL文を実行する前に、パラメータ番号で指定したパラメータの値を設定するために使用されます。SQL文は、使用前にPrepare()メソッドで準備され、Execute()メソッドで実行されます。SQL文にパラメータ・マーカー(リテラル定数が有効である位置で使用される"?"文字)が含まれている場合、そのSQL文を実行するには、それらのパラメータに値を割り当てる必要があります。文を実行する前に、setParam()メソッドを使用して各パラメータの値を定義します。Oracle TimesTen In-Memory Database SQLリファレンスの動的パラメータを参照してください。
次の表3-3に、サポートされるSQLデータ型と、各型での使用に適したsetParam()のバージョンを示します。表に示されていないSQLデータ型は、このバージョンのTTClassesではサポートされていません。表に示すとおり、NCHAR、NVARCHARおよびバイナリ型については、メソッド・コールでbyteLenを指定します(これは、パラメータ値内のバイト数の整数値です)。
setParam()に最初に渡される引数は、設定されるパラメータの位置です。SQL文の最初のパラメータはパラメータ1です。setParam()に2番目に渡される引数はパラメータの値です。オーバーロードされたバージョンのsetParam()は、2番目の引数で様々なデータ型を受け入れます。
TTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。準備済のSQLのパラメータごとに、オーバーロードされた適切なバージョンのsetParam()をコールする必要があります。誤ったバージョンをコールする(たとえば、整数パラメータをchar*値に設定しようとする)と、プログラム障害が発生するおそれがあります。
setParam()に渡された値は、TTCmdオブジェクトによってメンテナンスされる内部バッファにコピーされます。これらのバッファは静的に割り当てられ、Prepare()メソッドによってバインドされます。パラメータ値はsetParam()のコール時にsetParam()に渡される値であって、後続のExecute()メソッドのコール時の値ではありません。
setParam()の使用例は、入力パラメータのバインドおよび出力または入力/出力パラメータのバインドを参照してください。重複パラメータについては、重複パラメータのバインドを参照してください。
ノート:
-
バインドされたパラメータの値の長さを設定する方法は、
「setParamLength()」を参照してください。 -
バインドされたパラメータに
NULL値を設定する方法は、「setParamNull()」を参照してください。
表3-3 サポートされるTimesTenの表の列型のsetParam()シグネチャ
| データ型 | サポートされるsetParam()のバージョン |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ノート: 整数のバージョンは、たとえば |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
setParamLength()
(バッチ以外の操作バージョン)
void setParamLength(int pno, int byteLen)準備済文の実行前に、パラメータ番号で指定した入力パラメータのバインド後の値の長さをバイト単位で設定します。
ノート:
このメソッドには、バッチ・バージョンもあります。setParamLength()を参照してください。
setParamNull()
(バッチ以外の操作バージョン)
void setParamNull(int pno)パラメータ番号で指定したバインドされた入力パラメータにSQL NULLの値を設定します。
ノート:
このメソッドには、バッチ・バージョンもあります。setParamNull()を参照してください。
setQueryThreshold()
void setQueryThreshold(const int nSecs)このメソッドは、TTCmdオブジェクトの時間制限のしきい値を秒単位で指定するために使用します。(これは、問合せだけでなく、すべてのSQL文に使用できます。)文の実行時間がしきい値を超過した場合、サポート・ログに警告が書き込まれます。実行は継続され、しきい値による影響は受けません。getQueryThreshold()も参照してください。
setQueryThreshold()メソッドは、TT_QUERY_THRESHOLDまたはTimesTenの一般接続属性QueryThresholdを設定するSQLSetStmtOptionを使用するのと同じ効果があります。
SQL文の実行に対するタイムアウトまたはしきい値の設定を参照してください。
setQueryTimeout()
void setQueryTimeout(const int nSecs)このメソッドは、(問合せだけではなく)すべてのSQL文の実行時、タイムアウトまでの長さを秒単位で指定するために使用します。デフォルトでは、タイムアウトはありません。
これは、SQL_QUERY_TIMEOUTまたはTimesTenの一般接続属性SQLQueryTimeout (またはミリ秒を使用するSQLQueryTimeoutMsec)を設定するためにSQLSetStmtOptionを使用するのと同じ効果があります。
SQL文の実行に対するタイムアウトまたはしきい値の設定を参照してください。
TTCmdオブジェクトのプロパティを取得するためのパブリック・メソッド
準備済のTTCmdオブジェクトの、バインドされた入力パラメータおよび出力列のプロパティについて問い合せる場合に有効なメソッドがいくつかあります。通常、これらのメソッドでは、文が事前に準備されている場合にのみ、有効な結果が得られます。
この項では、TTCmdオブジェクト・プロパティの取得方法の概要を説明します。
TTCmdオブジェクトのプロパティを取得するためのパブリック・メソッドの概要
| メソッド | 説明 |
|---|---|
|
指定された列の名前を返します。 |
|
|
指定した列のデータとして値 |
|
|
指定された列の精度を返します。 |
|
|
指定された列のスケールを返します。 |
|
|
指定された列のODBCデータ型を返します。 |
|
|
出力列の数を返します。 |
|
|
入力パラメータの数を返します。 |
|
|
指定したパラメータの値として |
|
|
準備済の文に指定されたパラメータの精度を返します。 |
|
|
準備済の文に指定されたパラメータのスケールを返します。 |
|
|
指定されたパラメータのODBCデータ型を返します。 |
|
|
|
getColumnName()
const char* getColumnName(int cno)列番号cnoの名前を返します。
getColumnNullability()
int getColumnNullability(int cno)列番号cnoとしてNULLデータが可能であるかどうかを示します。SQL_NO_NULLS、SQL_NULLABLEまたはSQLNULLABLE_UNKNOWNが返されます。
getColumnPrecision()
SQLULEN getColumnPrecision(int cno)列番号cno内のデータのデータベースの列サイズを参照する精度を返します。たとえば、VARCHAR2(25)列では、25の精度が返されます。
通常、この値は、表のCHAR、VARCHAR2、NCHAR、NVARCHAR2、BINARYおよびVARBINARY型の列から出力を生成する場合にのみ重要です。
getColumnScale()
int getColumnScale(int cno)列番号cnoのデータのスケールを返します(小数点以下の最大桁数)。
getColumnType()
int getColumnType(int cno)列番号cnoのデータ型を返します。返される値は、sql.hに見られる、パラメータのODBC型(SQL_INTEGER、SQL_REAL、SQL_BINARY、SQL_CHARなど)です。その他のTimesTen ODBC型(SQL_WCHAR、SQL_WVARCHAR)は、TimesTenヘッダー・ファイルtimesten.hで見られます。
getNColumns()
int getNColumns()出力列の数を返します。
getNParameters()
int getNParameters()SQL文の入力パラメータ数を返します。
getParamNullability()
int getParamNullability(int pno)パラメータ値pnoとして値NULLが可能かどうかを示します。SQL_NO_NULLS、SQL_NULLABLEまたはSQLNULLABLE_UNKNOWNが返されます。
ノート:
以前のリリースでは、このメソッドではintではなくboolが返されました。
getParamPrecision()
SQLULEN getParamPrecision(int pno)パラメータ番号pnoのそのデータ型で使用される最大桁数を参照する精度を返します。前述の「getColumnPrecision()」の情報も参照してください。
getParamScale()
int getParamScale(int pno)パラメータ番号pnoのデータの小数点以下の最大桁数を参照するスケールを返します。
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で見られます。
isBeingExecuted()
bool isBeingExecuted()TTCmdオブジェクトで表現された文が実行されたかどうかを示します。
バッチ操作のためのパブリック・メソッド
TimesTenは、挿入、更新および削除のバッチ操作のためにODBC関数SQLBindParamsをサポートします。TTClassesには、ODBC関数SQLBindParamsへのインタフェースが用意されています。
TTClassesでバッチ操作を実行する際の方法は、バッチ以外の操作を実行する場合と似ています。まずPrepareBatch()を使用してSQL文をコンパイルします。その後、その文の各パラメータを、BindParameter()を使用して値の配列にバインドします。最後にExecuteBatch()を使用して文を実行します。
バッチ操作の使用例については、TimesTen Classicのクイック・スタートにあるサンプル・プログラムTTClasses bulktestを参照してください。TimesTenクイック・スタートおよびサンプル・アプリケーションについてを参照してください。
この項では、TTClassesユーザー向けに、バッチのINSERT、UPDATEおよびDELETE機能を公開するTTCmdメソッドの概要を説明します。
バッチ操作のためのパブリック・メソッドの概要
| メソッド | 説明 |
|---|---|
|
バッチ内の文の数を返します。 |
|
|
|
|
|
|
|
|
|
|
|
準備済文の実行の前に、指定したバインド・パラメータの長さをバイト単位で設定します。 |
|
|
準備済文を実行の前に指定したバインド・パラメータの値を |
batchSize()
u_short batchSize()バッチ内の文の数を返します。
BindParameter()
void BindParameter(int pno, unsigned short batSz, TYPE* valueP)
void BindParameter(int pno, unsigned short batSz, TYPE* valueP, size_t maxByteLen)
void BindParameter(int pno, unsigned short batSz, TYPE* valueP,
SQLLEN* userByteLenP, size_t maxByteLen)オーバーロードされたBindParameter()メソッドは、PrepareBatch()によってコンパイルされたSQL文について、指定したパラメータをバインドするために使用されます。これによって、バッチ内で文が繰り返し実行される際に違う値を使用できます。pnoパラメータは、バインドするパラメータの文内の左から開始される位置(最初のパラメータは1で次は2と続きます)を示します。
次の表3-4に、サポートされるSQLデータ型および各パラメータ型で使用するBindParameter()の適切なバージョンを示します。
重複パラメータのバインドも参照してください。
このコールのbatSz (バッチ・サイズ)値は、PrepareBatch()に指定したbatSzと一致する必要があり、バインドされた配列には少なくともbatSzの数の値が含まれる必要があります。各パラメータの正しい型を判別する必要があります。指定されたパラメータ番号が無効であるか、指定したバッチ・サイズが一致しないか、またはデータ・バッファがnullの場合、TTStatusオブジェクトが例外としてスローされ、実行時エラーがTTClassesグローバル・ロギング機能にTTLog::TTLOG_ERRロギング・レベルで書き込まれます。
ExecuteBatch()を起動するたびに、アプリケーションで事前にバインド配列に有効なパラメータ値を設定する必要があります。setParamNull()の説明のとおり、null値の設定にはsetParamNull()メソッドを使用できることに注意してください(バッチ・モードでは、rownoを指定するsetParamNull()の2つのパラメータを使用するバージョンを使用する必要があります。パラメータを1つ使用するバージョンは、バッチ以外の用途のみで使用します。)
TT_CHAR、CHAR、TT_VARCHARおよびVARCHAR2のSQLデータ型については、BindParameter()コールに最大長のパラメータを追加する必要があります。
-
型
size_tのmaxByteLenは、このパラメータ位置の任意の値(バイト単位)の最大長用です。
TT_NCHAR、NCHAR、TT_NVARCHAR、NVARCHAR2、BINARYおよびVARBINARYのSQLデータ型については、BindParameter()コールにパラメータ長および最大長の2つパラメータを追加する必要があります。
-
userByteLenPは、バッチ内のSQL文のこのパラメータ位置の各値の長さを指定する、バイト単位のSQLLENパラメータ長の配列です。この配列の長さには、batSzの長さ以上が必要であり、ExecuteBatch()のコール前に、有効な長さの値が設定されている必要があります。(null値の場合は、パラメータ長の配列に、setParamNull()バッチ・メソッドを使用する場合と同等のSQL_NULL_DATAを格納できます。) -
maxByteLenは、前述の説明のとおりです。これは、userByteLenP配列の任意の要素に指定する値の最大長を示します。
userByteLenPを利用できないデータ型では(または利用できるが別の方法が必要な場合は)、オプションでデータ長の設定にsetParamLength()バッチ・メソッドを(setParamLength()を参照)、またnull値の設定にsetParamNull()バッチ・メソッドを(setParamNull()を参照)使用できます。
BindParameter()の使用方法の例については、次の項ExecuteBatch()の例を参照してください。
表3-4 サポートされるTimesTenの表の列型のBindParameter()シグネチャ
| SQLデータ型 | サポートされるBindParameter()のバージョン |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ExecuteBatch()
SQLULEN ExecuteBatch(unsigned short numRows)PrepareBatch()によってSQL文を準備し、そのSQL文の各パラメータに対してBindParameter()をコールした後、ExecuteBatch()を使用してその文をnumRows回実行します。numRowsの値は、PrepareBatch()とBindParameter()コールで指定したbatSz (バッチ・サイズ)値未満である必要がありますが、アプリケーション・ロジックで必要な場合はbatSz未満であってもかまいません。
このメソッドでは、0からbatSzの範囲の値の、更新された行数を返します。(ODBCに詳しいユーザー向け: これは、ODBCのSQLParamOptionsコールの3番目のパラメータ*pirowです。SQLParamOptionsの詳細は、ODBC APIのリファレンス・マニュアルを参照してください。)
アプリケーションでは、ExecuteBatch()をコールする前に、BindParameter()で以前にバインドしたパラメータの配列に有効な値を入力する必要があります。
(通常は一意性の制約違反が原因の)エラーが発生した場合、例外としてTTStatusオブジェクトがスローされます。このとき、戻り値は無効で、バッチは完了していないので、一般的にはロールバックを行う必要があります。
次の例に、ExecuteBatch()メソッドの使用方法を示します。bulktest TimesTen Classicクイック・スタート・デモでも、このメソッドの使用方法を確認できます。(TimesTenクイック・スタートおよびサンプル・アプリケーションについてを参照してください。)
次のとおり、まず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;
// (assume a connection has been established)
try {
insert.PrepareBatch (&connection,
(const char*)"insert into batch_table values (?,?)",
BATCH_SIZE);
// Commit the prepared statement
connection.Commit();
// Bind the arrays of parameters
insert.BindParameter(1, BATCH_SIZE, int_array);
insert.BindParameter(2, BATCH_SIZE, (char **)char_array, VARCHAR_SIZE);
// Execute 5 batches, inserting a total of 5 * BATCH_SIZE rows into
// the database
for (int iter = 0; iter < 5; iter++)
{
// Populate the value arrays with values.
// (A more meaningful way of putting data into
// the database is to read values from a file, for example,
// 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.
SQLULEN num_ins = insert.ExecuteBatch(BATCH_SIZE);
cerr << "Inserted " << num_ins << " rows." << endl;
connection.Commit();
} // for iter
} catch (TTError er1) {
cerr << er1 << endl;
}たとえば、列の1つに一意制約の違反がある場合などは、更新された行数(この例ではnum_ins)をBATCH_SIZEよりも少なくなる可能性があります。次の例のようなコード使用して、この状況を確認し、必要に応じてトランザクションをロールバックできます。
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
SQLULEN num_ins = insert.ExecuteBatch(BATCH_SIZE);
cerr << "Inserted " << num_ins << " rows (expected "
<< BATCH_SIZE << " rows)." << endl;
if (num_ins == BATCH_SIZE) {
cerr << "Committing batch" << endl;
connection.Commit();
}
else {
cerr << "Some rows were not inserted as expected, rolling back "
<< "transaction." << endl;
connection.Rollback();
break; // jump out of batch insert loop
}
} // for loopPrepareBatch()
void PrepareBatch(TTConnection* cP, const char* sqlp, unsigned short batSz)PrepareBatch()は、Prepare()の類似メソッドですが、バッチでのINSERT、UPDATEまたはDELETE文が可能です。Prepare()では、cPパラメータとsqlpパラメータを使用します。Prepare()を参照してください。
batSz (バッチ・サイズ)パラメータでは、ExecuteBatch()への後続のコールによって実行される挿入、更新、削除操作の最大数を指定します。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
ノート:
クライアント/サーバー接続を使用している場合に、クライアントとサーバー間の不要なラウンドトリップを回避するために、PrepareBatch()メソッドによって遅延準備と呼ばれる処理が実行され、リクエストは要求されるまでサーバーに送信されません。Oracle TimesTen In-Memory Database C開発者ガイドのTimesTenの遅延準備を参照してください。
setParamLength()
(バッチ操作のバージョン)
void setParamLength(int pno, unsigned short rowno, int byteLen)このメソッドは、ExecuteBatch()をコールする前に、バインドされたパラメータ値の長さを設定します。pno引数は、SQL文内のパラメータ番号を指定します(最初のパラメータが番号1)。rowno引数は、バインド対象のパラメータ配列の行番号を指定します(最初の行が行番号1)。byteLenパラメータでは、希望の長さをバイト単位で指定します(終わりのNULLはカウントしません)。NULLで終わる文字列については、byteLenのかわりにSQL_NTSを設定することも可能です。(また、次で説明するsetParamNull()バッチ・メソッドと同等の、SQL_NULL_DATAに設定することも可能です。)
ノート:
-
表3-4に示すように、バイナリおよび
NCHAR型のパラメータ長の設定には、BindParameter()userByteLenP配列を使用した方が簡単な場合があります。バインドされるパラメータ配列の行の番号は、userByteLenP配列では0から開始しますが、setParamLength()を使用した場合は1になる点に注意してください。 -
このメソッドには、バッチ以外でのバージョンもあります。setParamLength()を参照してください。(バッチ以外の操作の場合は、2つのパラメータを使用するバージョンのみを使用し、バッチ操作では
rownoを指定する3つのパラメータを使用するバージョンのみを使用することが重要です)。
setParamNull()
(バッチ操作のバージョン)
void setParamNull(int pno, unsigned short rowno)このメソッドでは、ExecuteBatch()のコール前に、バインドされたパラメータ値をNULLに設定します。pno引数は、SQL文内のパラメータ番号を指定します(最初のパラメータが番号1)。rowno引数は、バインド対象のパラメータ配列の行番号を指定します(最初の行が行番号1)。
ノート:
-
表3-4に示すように、バイナリおよび
NCHAR型には、BindParameter()userByteLenP配列があります。これらの型では、setParamNull()の使用と同等のSQL_NULL_DATAをこの配列に指定することによりNULL値が可能になります。バインドされるパラメータ配列の行の番号は、userByteLenPでは0から開始しますが、setParamNull()を使用した場合は番号が1で開始する点に注意してください。 -
このメソッドには、バッチ以外でのバージョンもあります。setParamNull()を参照してください。(バッチ以外の操作の場合は、1つのパラメータを使用するバージョンのみを使用し、バッチ操作では
rownoを指定する2つのパラメータを使用するバージョンのみを使用することが重要です)。