アプリケーションでのTimesTenの機能および操作

この項では、どのようにアプリケーションがTimesTenデータベース内のデータを操作するかを説明します。

内容は次のとおりです。(『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTenデータベースでのデータの操作を参照してください。)

• TimesTenのインクルード・ファイル

• TimesTenの遅延準備

• 複数のデータ行のプリフェッチ

• 問合せのパフォーマンスの最適化

• パラメータのバインドと文の実行

• REF CURSORの使用

• DML RETURNING (RETURNING INTO句)の使用

• ROWIDの使用

• ラージ・オブジェクト(LOB)

• プロシージャおよび関数を実行するためのCALLの使用

• SQL文の実行のタイムアウトとしきい値

• ODBCを使用したクライアント/サーバーでの結果セット・バッファ・サイズの構成

• キャッシュの機能

TimesTenのインクルード・ファイル

この項では、TimesTenの機能を使用するためにコードからインクルードする必要があるファイルを示します。これらは、TimesTenインストールのincludeディレクトリにあります。

インクルードされるファイルにアクセスするには、適切なインクルード・パスを設定します。「アプリケーションのコンパイルおよびリンク」を参照してください。

インクルード・ファイル	説明
timesten.h	TimesTenのODBC機能 このファイルには、適切なバージョンのsql.hが含まれています。LinuxまたはUNIXシステムではTimesTenバージョン、Windowsシステムではシステム・バージョンです。 このファイルには、sqltypes.h、sqlext.hおよびsqlucode.hも含まれています。Windowsシステムでは、windows.hも含まれます。
tt_errCode.h	TimesTenエラー・コード(オプション。「ノート」を参照) このファイルは、TimesTenエラー・コードを定義済の定数マップします。

ノート:

• sql.hを(timesten.hを介してではなく)直接含める場合、WindowsにTimesTenバージョンではなくシステム・バージョンのsql.hを含める必要があります。

• これまでsqlunix.hにあった型定義は、sqltypes.hに含まれるようになりました。ただし、sqlunix.hは下位互換性のため(空のファイルとして)引き続き存在します。

• tt_errCode.hを含めるかわりに別の方法もあります。1つは、任意の定数定義をtimesten.hに移動することです。もう1つは、対応する整数値をコード内で直接参照することです。

TimesTenの遅延準備

TimesTenには、データベースへのラウンド・トリップを減らすための遅延準備機能があります。

標準のODBCでは、結果セットの列記述のような文に関する情報をアプリケーションで使用可能にしたり、これらの情報にSQLDescribeColなどのコールでアクセスできるように、SQLPrepareコールはSQL文をコンパイルします。この機能を実現するには、SQLPrepareコールをサーバーに送信して処理する必要があります。

このことは、たとえば、Oracle Call Interface(OCI)で期待される動作とは対照的で、OCIでは、準備コールは単にパラメータの名前と位置を抽出するための、クライアントで実行される軽量処理であることが期待されています。

クライアントとサーバー間の不要なラウンドトリップを回避し、OCIが期待する動作との一貫性を実現するために、TimesTenクライアント・ライブラリに実装されたSQLPrepareでは、遅延準備と呼ばれる処理が実行され、リクエストは要求されるまでサーバーに送信されません。ラウンドトリップが必要になる場合の例を、次に示します。

• SQLExecuteコールがある場合。まだサーバーに送信されていない遅延準備コールがある場合、クライアント上のSQLExecuteコールはSQLExecDirectコールに変換されることに注意してください。

• SQLエンジンからのみ取得可能な、問合せに関する情報のリクエストがある場合(SQLDescribeColコールがある場合など)。標準のODBCのこのようなコールの多くは、以前にSQLPrepareコールで返された情報にアクセスできますが、遅延準備機能を使用している場合は、SQLPrepareコールがサーバーに送信され、情報は必要な場合にのみアプリケーションに返されます。

ノート:

遅延準備機能はTimesTenの直接ドライバでは実装されていません(必須ではありません)。

遅延準備の実装には、アプリケーションまたはユーザー・レベルの変更は必要ありません。ただし、次の関数のいずれかをコールすると、以前に準備された文で必要とされた情報がまだ取得されていなかった場合には、サーバーに対するラウンドトリップが発生する可能性があります。

• SQLColAttributes

• SQLDescribeCol

• SQLDescribeParam

• SQLNumResultCols

• SQLNumParams

• SQLGetStmtOption(SQLエンジンでコンパイルされている文に依存するオプションの場合)

また、これらの関数のいずれかをコールすると、以前のSQLPrepareコールのエラーが、これらのコールの1つが実行されるまで遅延される場合があることに注意してください。また、これらのコールで、コール自体に固有のエラーの他に、SQLPrepareに固有のエラーも返される場合があります。

複数のデータ行のプリフェッチ

TimesTenによるODBCの拡張によって、アプリケーションはODBCドライバのバッファに複数のデータ行をプリフェッチできます。これにより、クライアント/サーバー・アプリケーションのパフォーマンスを向上させることができます。

TT_PREFETCH_COUNT ODBC文オプションによって、1回のSQLFetchコールでプリフェッチする行数が決定されます。このオプションは、TimesTenに直接接続するアプリケーションには何もメリットがないことに注意してください。

コールのTT_PREFETCH_COUNTは、SQLSetStmtOptionまたはSQLSetConnectOptionに設定できます(接続に関連付けられる文すべてのデフォルト値をオプションで設定します)。値には0(ゼロ)から128までの任意の整数を設定できます。次に、その例を示します。

rc = SQLSetConnectOption(hdbc, TT_PREFETCH_COUNT, 100);

この設定を使用すると、接続時の最初のSQLFetchコールで100行がプリフェッチされます。後続のSQLFetchコールは、ODBCバッファが使い果たされるまで、データベースのかわりにODBCバッファからフェッチします。使い果たされると、次のSQLFetchコールでは別の100行がバッファにフェッチされます。

プリフェッチを無効にするには、TT_PREFETCH_COUNTを1に設定します。

プリフェッチ数を0(ゼロ)に設定すると、TimesTenはデータベースに設定した分離レベルに応じてデフォルトのプリフェッチ数を使用し、プリフェッチ数をTT_PREFETCH_COUNT値に設定します。コミット読取り分離レベルでは、デフォルトのプリフェッチの値は5です。シリアライズ可能分離レベルでは、デフォルトは128です。デフォルトのプリフェッチの値はほとんどのアプリケーションに最適な設定です。一般的に、値を高く設定すると、リソースの使用量がわずかに増加しますが、大きい結果セットに対するパフォーマンスは向上する可能性があります。

「ODBC 3.5のSQLSetStmtAttrおよびSQLGetStmtAttrでの属性サポート」も参照してください。

問合せのパフォーマンスの最適化

ODBCのTimesTen拡張機能を使用すると、TT_PREFETCH_CLOSE ODBC接続オプションを使用してアプリケーションでクライアント/サーバー・アプリケーションの読取り専用問合せパフォーマンスを最適化できます。

SQLSetConnectOptionを使用して、TT_PREFETCH_CLOSEをTT_PREFETCH_CLOSE_ONに設定します。

すべてのトランザクションは、読取り専用トランザクションを含め、実行時にコミットされる必要があります。TT_PREFETCH_CLOSEがTT_PREFETCH_CLOSE_ONに設定されている場合、カーソルが自動的にクローズされ、読取り専用問合せの結果セットの行がすべてプリフェッチされた後でトランザクションがコミットされます。これによって、クライアントとサーバー間のネットワーク・ラウンドトリップ数が減少するため、パフォーマンスが向上します。

クライアントでは、SQLFreeStmt(SQL_CLOSE)を使用して文を解放し、SQLTransact(SQL_COMMIT)を使用してトランザクションをコミットする必要がありますが、これらのコールは、クライアントで実行されるため、クライアントとサーバー間のネットワーク・ラウンドトリップを必要としません。

ノート:

• TT_PREFETCH_CLOSEがTT_PREFETCH_CLOSE_ONに設定されている場合、同じ接続に対して複数の文ハンドルを使用しないでください。サーバーでは、クライアントが終了する前に、結果セットのすべてがフェッチされ、トランザクションがコミットされて文ハンドルがクローズされる可能性があります。

• このオプションは、TimesTen直接接続およびSELECT FOR UPDATE文では無視されます。

次の例は、TT_PREFETCH_CLOSEオプションを使用する方法を示しています。

SQLSetConnectOption (hdbc, TT_PREFETCH_CLOSE, TT_PREFETCH_CLOSE_ON);
SQLExecDirect (hstmt, "SELECT * FROM T", SQL_NTS);
while (SQLFetch (hstmt) != SQL_NO_DATA_FOUND)
{
// do the processing and error checking
}
SQLFreeStmt (hstmt, SQL_CLOSE);
SQLTransact(SQL_COMMIT);

パラメータのバインドと文の実行

SQL文の入力パラメータまたは出力パラメータをバインドする方法について説明します。

内容は次のとおりです。

• SQLBindParameter関数

• パラメータのデータ型の割当ておよびデータ型変換

• ODBCのSQLからTimesTenのSQLまたはPL/SQLへのデータ型のマッピング

• 入力パラメータのバインド

• 出力パラメータのバインド

• 入力/出力パラメータのバインド

• SQL文での重複したパラメータのバインド

• PL/SQL文での重複したパラメータのバインド

• 浮動小数点データに関する考慮事項

• ドライバ・マネージャ使用時のSQL_WCHARおよびSQL_WVARCHARの使用

ノート:

TimesTen開発者ガイドで使用される「バインド・パラメータ」という用語(ODBC用語に準拠)は、TimesTenのPL/SQLのマニュアルで使用される「バインド変数」という用語(Oracle Database PL/SQL用語に準拠)と同じです。

SQLBindParameter関数

ODBCのSQLBindParameter関数を使用して、SQL文のパラメータをバインドします。これには、入力、出力または入力/出力パラメータを含むことができます。

ODBCを介して入力パラメータをバインドするには、fParamType引数にSQL_PARAM_INPUTを設定してSQLBindParameter関数を使用します。SQLBindParameter関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。表2-1に、この引数の簡単な概要を示します。

ODBCを介して出力パラメータまたは入力/出力パラメータをバインドするには、fParamType引数にそれぞれSQL_PARAM_OUTPUTまたはSQL_PARAM_INPUT_OUTPUTを設定してSQLBindParameter関数を使用します。入力パラメータと同様に、fSqlType引数、cbColDef引数およびibScale引数を(必要に応じて)使用して、データ型を指定します。

表2-1 SQLBindParameterの引数

引数	型	説明
hstmt	SQLHSTMT	文ハンドル
ipar	SQLUSMALLINT	左から右へ順に、1から始まるパラメータ番号
fParamType	SQLSMALLINT	入力または出力を示す、SQL_PARAM_INPUT、SQL_PARAM_OUTPUTまたはSQL_PARAM_INPUT_OUTPUT
fCType	SQLSMALLINT	パラメータのCデータ型
fSqlType	SQLSMALLINT	パラメータのSQLデータ型
cbColDef	SQLULEN	バイナリ・データに対する最大バイト数、数値に対する最大桁数、文字データに対する最大文字数などのパラメータの精度
ibScale	SQLSMALLINT	パラメータのスケール。該当する場合に、小数点より右の最大桁数を示します
rgbValue	SQLPOINTER	パラメータのデータに使用するバッファへのポインタ
cbValueMax	SQLLEN	rgbValueバッファの最大長(バイト)
pcbValue	SQLLEN*	パラメータの長さに使用するバッファへのポインタ

ノート:

『Oracle TimesTen In-Memory Database SQLリファレンス』のデータ型を参照してください。

パラメータのデータ型の割当ておよびデータ型変換

バインド・パラメータのデータ型の割当ては、実行される場所に応じて異なるエンティティによって決定されます。データ型変換はODBCドライバによって実行されます。

この項では、次のように決定される、バインド・パラメータのデータ型の割当てについて説明します。

• TimesTenで実行される文のパラメータのデータ型の割当ては、TimesTenが決定します。具体的には、次のようになります:

  • TimesTen内で実行されるSQL文の場合、TimesTenの問合せオプティマイザがSQLパラメータのデータ型を決定します。

• Oracle Databaseで実行されるか、Oracle Databaseの機能に基づいた文に対するパラメータのデータ型の割当ては、次のようにアプリケーションが決定します。

  • Oracle Database内で実行されるSQL文(つまり、キャッシュからのパススルー文)の場合は、アプリケーションで、ODBCのSQLBindParameter関数のコールを介して、その関数のfSqlType、cbColDefおよびibScale引数(該当する場合)に従ってデータ型が指定される必要があります。

  • TimesTen内で実行されるPL/SQLブロックまたはプロシージャで、PL/SQL実行エンジンにOracle Databaseと同じ基本的な機能がある場合は、アプリケーションは、SQLBindParameterに対するコールでデータ型を指定する必要があります(Oracle Database内で実行されるSQL文の場合と同様)。

    そのため、PL/SQLのホスト・バインド(PL/SQLブロック内でコロンより前にある変数やパラメータ)については、fSqlTypeおよび該当する他の引数に従って、PL/SQLブロック内ではなく、SQLBindParameterのコールでホスト・バインドのデータ型が事実上宣言されることに留意してください。

ODBCドライバは、C値とSQLまたはPL/SQLのデータ型間で必要な型の変換を行います。サポートされていないCとSQLやCとPL/SQLの組合せでは、エラーが発生します。それらは、C型からSQL型またはPL/SQL型(入力パラメータ)、SQL型またはPL/SQL型からC型(出力パラメータ)または両方(入力/出力パラメータ)の変換の場合です。

ODBCとTimesTenの間のデータ型マッピングの詳細は、次の項を参照してください。

ノート:

TimesTenのバインド・メカニズム(アーリー・バインディング)はOracle Databaseのバインド・メカニズム(レイト・バインディング)とは異なります。TimesTenは、問合せの準備の前にデータ型を必要とします。そのため、各バインド・パラメータのデータ型が指定されていないかSQL文から推測できないと、エラーが発生します。たとえば次のような文が、これに該当します。

SELECT 'x' FROM DUAL WHERE ? = ?;

この問題には、たとえば次のように対処できます。

SELECT 'x' from DUAL WHERE CAST(? as VARCHAR2(10)) = 
                           CAST(? as VARCHAR2(10)); 

ODBCのSQLからTimesTenのSQLまたはPL/SQLへのデータ型のマッピング

ODBCのSQLからTimesTenのSQLまたはPL/SQLへのマッピングについて説明します。

表2-2に、ODBCデータ型とSQL型またはPL/SQLデータ型とのマッピングを示します。

表2-2 ODBCのSQLからTimesTenのSQLまたはPL/SQLへのデータ型のマッピング

ODBCのデータ型(fSqlType)	SQLまたはPL/SQLのデータ型	TimesTenでのサポートに関する留意事項
SQL_BIGINT	NUMBER	ノートなし
SQL_BINARY	RAW(p)	ノートなし
SQL_BIT	PLS_INTEGER	ノートなし
SQL_CHAR	CHAR(p)	ノートなし
SQL_DATE	DATE	ノートなし
SQL_DECIMAL	NUMBER	ノートなし
SQL_DOUBLE	NUMBER	ノートなし
SQL_FLOAT	BINARY_DOUBLE	ノートなし
SQL_INTEGER	PLS_INTEGER	ノートなし
SQL_INTERVAL_DAY	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_DAY_TO_HOUR	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_DAY_TO_MINUTE	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_DAY_TO_SECOND	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_HOUR	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_HOUR_TO_MINUTE	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_HOUR_TO_SECOND	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_MINUTE	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_MINUTE_TO_SECOND	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_MONTH	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_YEAR	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_YEAR_TO_MONTH	該当なし	この表の後のノートを参照してください。
SQL_INTERVAL_SECOND	該当なし	この表の後のノートを参照してください。
SQL_NUMERIC	NUMBER	ノートなし
SQL_REAL	BINARY_FLOAT	ノートなし
SQL_REFCURSOR	REF CURSOR	ノートなし
SQL_ROWID	ROWID	ノートなし
SQL_SMALLINT	PLS_INTEGER	ノートなし
SQL_TIME	TIME	TimesTenでは、TIMEZONEはサポートされません。TIMEデータ型の値は、時差の調整を行わずに格納されます。アプリケーションでは、あるタイムゾーンを想定し、データベースに値を送信する前に、TIME値をそのタイムゾーンに変換する必要があります。
SQL_TIMESTAMP	TIMESTAMP(s)	TIMEと同じ考慮事項。
SQL_TINYINT	PLS_INTEGER	ノートなし
SQL_VARBINARY	RAW(p)	ノートなし
SQL_VARCHAR	VARCHAR2(p)	ノートなし
SQL_WCHAR	NCHAR(p)	ノートなし
SQL_WVARCHAR	NVARCHAR2(p)	ノートなし

ノート:

• (p)という表記は、精度がSQLBindParameterの引数cbColDefに従うことを示します。

• (s)という表記は、スケールがSQLBindParameterの引数ibScaleに従うことを示します。

• SQL_INTERVAL_xxxx型は、SQL式などの計算値についてのみサポートされており、データベースの列のデータ型としてはサポートされていません。

• ほとんどのアプリケーションでは、文字データのバインドにSQL_CHARではなくSQL_VARCHARを使用してください。SQL_CHARを使用すると、パラメータ・タイプの完全な精度に不要な空白文字が含まれる可能性があります。

• たとえば、TIMEおよびTIMESTAMPについて、アプリケーションはタイムゾーンを太平洋標準時とみなすことができます。アプリケーションで太平洋夏時間または東部標準時間のTIMEおよびTIMESTAMP値を使用している場合は、TIMEおよびTIMESTAMPを太平洋標準時間に変換する必要があります。

入力パラメータのバインド

TimesTenのPL/SQLへの入力パラメータをバインドするには、ODBCのSQLBindParameter関数のfSqlType、cbColDefおよびibScale引数(該当する場合)を使用して、データ型を指定します。

これは、「パラメータのデータ型の割当ておよびデータ型変換」で示されているとおり、SQLの入力パラメータのサポート方法とは異なります。

また、入力パラメータについては、次のようにSQLBindParameterのrgbValue、cbValueMaxおよびpcbValue引数を使用します。

• rgbValue: 文を実行する前に、アプリケーションに渡されるパラメータ値の格納先となるバッファを指します。

• cbValueMax: 文字データおよびバイナリ・データの場合、rgbValueで指している入力値の最大長(バイト)を示します。他のすべてのデータ型の場合、cbValueMaxは無視され、rgbValueで指している値の長さは、SQLBindParameterのfCType引数に指定したCデータ型の長さで決まります。

• pcbValue: 文を実行する前に、次のいずれかを含むバッファを指します。

  • rgbValueで指している値の実際の長さ

    ノート: 入力パラメータの場合、文字データまたはバイナリ・データにのみ有効です。

  • 空文字で終了する文字列の場合は、SQL_NTS

  • NULL値の場合は、SQL_NULL_DATA

出力パラメータのバインド

TimesTenのPL/SQLからの出力パラメータをバインドするには、前述の入力パラメータについての説明と同様で、ODBCのSQLBindParameter関数のfSqlType、cbColDefおよびibScale引数(該当する場合)を使用して、データ型を指定します。

また、出力パラメータについては、次のようにSQLBindParameterのrgbValue、cbValueMaxおよびpcbValue引数を使用します。

• rgbValue: 文の実行中に、文から返された値の格納先となるバッファを指します。

• cbValueMax: 文字データおよびバイナリ・データの場合、rgbValueで指している出力値の最大長(バイト)を示します。他のすべてのデータ型の場合、cbValueMaxは無視され、rgbValueで指している値の長さは、SQLBindParameterのfCType引数に指定したCデータ型の長さで決まります。

  ODBCでは、データが切り捨てられる場合でも、すべての文字データが空文字で終了することに注意してください。そのため、出力パラメータに文字データが含まれる場合、cbValueMaxはデータの最長値+空文字を保持できる十分な大きさである必要があります(CHARおよびVARCHARパラメータでは1バイト大きい値、またはNCHARおよびNVARCHARパラメータでは2バイト大きい値)。

• pcbValue: 文を実行した後に、次のいずれかを含むバッファを指します。

  • rgbValueで指している値の実際の長さ(文字データおよびバイナリ・データのみでなく、すべてのCデータ型が対象)

    ノート: これは、rgbValueで指しているバッファに値が収まるかどうかに関係なく、完全なパラメータ値の長さです。

  • NULL値の場合は、SQL_NULL_DATA

次の例では、PL/SQLの無名ブロックを準備、バインドおよび実行する方法を示します。

• 無名ブロックでは、値abcdeをバインド・パラメータaに、値123をバインド・パラメータbに割り当てます。

• SQLPrepareは無名ブロックを準備します。

• SQLBindParameterは、最初のパラメータ(a)をデータ型SQL_VARCHARの出力パラメータとしてバインドし、2番目のパラメータ(b)をデータ型SQL_INTEGERの出力パラメータとしてバインドします。

• SQLExecuteは無名ブロックを実行します。

{
  SQLHSTMT      hstmt;
  char          aval[11];
  SQLLEN        aval_len;
  SQLINTEGER    bval;
  SQLLEN        bval_len;
 
  SQLAllocStmt(hdbc, &hstmt);
 
  SQLPrepare(hstmt,
        (SQLCHAR*)"begin :a := 'abcde'; :b := 123; end;",
        SQL_NTS);
 
  SQLBindParameter(hstmt, 1, SQL_PARAM_OUTPUT, SQL_C_CHAR, SQL_VARCHAR,
         10, 0, (SQLPOINTER)aval, sizeof(aval), &aval_len);
 
  SQLBindParameter(hstmt, 2, SQL_PARAM_OUTPUT, SQL_C_SLONG, SQL_INTEGER,
         0, 0, (SQLPOINTER)&bval, sizeof(bval), &bval_len);
 
  SQLExecute(hstmt);
  printf("aval = [%s] (length = %d), bval = %d\n", aval, (int)aval_len, bval);
}

入力/出力パラメータのバインド

TimesTenのPL/SQLに対する入力/出力パラメータをバインドするには、前述の入力および出力パラメータについての説明と同様で、ODBCのSQLBindParameter関数のfSqlType、cbColDefおよびibScale引数(該当する場合)を使用して、データ型を指定します。

また、入力/出力パラメータについては、次のようにSQLBindParameterのrgbValue、cbValueMaxおよびpcbValue引数を使用します。

• rgbValue: 「入力パラメータのバインド」で説明したとおりに、文を実行する前に先に使用します。次に、前の項「出力パラメータのバインド」で説明したとおり、文の実行中に使用します。入力/出力パラメータの場合、文の実行で出力された値は、アプリケーションによって上書きされないかぎり、直後に続く文の実行に対する入力値になります。また、実行時データの使用中にバインドされる入力/出力値の場合、rgbValueの値は、ODBCのSQLParamData関数で返されるトークン、および出力値の格納先となるバッファへのポインタとして機能します。

• cbValueMax: 文字データおよびバイナリ・データの場合に、「入力パラメータのバインド」で説明したとおりに、先に使用します。次に、前の項「出力パラメータのバインド」で説明したとおりに使用します。他のすべてのデータ型の場合、cbValueMaxは無視され、rgbValueで指している値の長さは、SQLBindParameterのfCType引数に指定したCデータ型の長さで決まります。

  ODBCでは、データが切り捨てられる場合でも、すべての文字データが空文字で終了することに注意してください。そのため、入力/出力パラメータに文字データが含まれる場合、cbValueMaxはデータの最長値+空文字を保持できる十分な大きさである必要があります(CHARおよびVARCHARパラメータでは1バイト大きい値、またはNCHARおよびNVARCHARパラメータでは2バイト大きい値)。

• pcbValue: 「入力パラメータのバインド」で説明したとおりに、文を実行する前に先に使用します。次に、前の項「出力パラメータのバインド」で説明したとおり、文の実行後に使用します。

ヒント:

文字データおよびバイナリ・データの場合は、cbValueMaxに使用する値を慎重に検討してください。実際のバッファ・サイズよりも小さい値を使用すると、誤った切捨て警告が発生します。実際のバッファ・サイズよりも大きい値を使用すると、ODBCドライバによってrgbValueバッファが上書きされ、メモリーが破損することがあります。

SQL文での重複したパラメータのバインド

TimesTenは、SQLでのパラメータ重複に対処します。TimesTenでは、SQL文に同じパラメータ名が複数ある場合、それぞれ別のパラメータであるとみなされます。(これは、重複したパラメータのバインドに対するOracle Databaseでのサポートと整合性があります。)

ノート:

• この説明は、PL/SQL経由などではなく、ODBCから直接発行されるSQL文にのみ当てはまります。(PL/SQL文については、次の「PL/SQLでの重複したパラメータのバインド」の項を参照してください。)

• 重複したパラメータをバインドするためのTimesTenモードと、DuplicateBindMode接続属性は非推奨になっています。

• パラメータでの?の使用はOracle Databaseではサポートされていませんが、TimesTenではサポートされています。

次の問合せについて考えてみましょう:

SELECT * FROM employees
  WHERE employee_id < :a AND manager_id > :a AND salary < :b;

パラメータの位置番号が割り当てられるとき、名前の重複に関係なく、パラメータの出現ごとに番号が与えられます。アプリケーションは、少なくとも各パラメータ名の最初の出現時に値をバインドする必要があります。特定のパラメータ名の2回目以降の出現に関して、アプリケーションでは次の選択肢があります。

• 出現ごとに異なる値をバインドします。

• 出現したパラメータをバインドしないでおきます。この場合には、最初の出現時と同じ値が使用されます。

いずれの場合も、出現ごとに異なるパラメータ位置番号が付けられます。

前述のSQL文のaの2回目の出現に対して異なる値を使用するには、次のように指定します。

SQLBindParameter(..., 1, ...); /* first occurrence of :a */
SQLBindParameter(..., 2, ...); /* second occurrence of :a */
SQLBindParameter(..., 3, ...); /* occurrence of :b */

aの両方の出現に対して同じ値を使用するには、次のように指定します。

SQLBindParameter(..., 1, ...); /* both occurrences of :a */
SQLBindParameter(..., 3, ...); /* occurrence of :b */

いずれの場合も、パラメータbは位置3に存在するとみなされます。

SQLNumParams ODBC関数はこの例のパラメータの数として3を返します。

PL/SQL文での重複したパラメータのバインド

TimesTenは、PL/SQLでのパラメータ重複に対処します。PL/SQLでは、それぞれの一意のパラメータ名に値をバインドします。たとえば、次のブロックを実行するアプリケーションは、:aに対応する1つのパラメータのみをバインドします。

前の「SQL文での重複したパラメータのバインド」の項での説明は、PL/SQLには当てはまりません。PL/SQLには独自のセマンティクスがあります。

DECLARE
   x NUMBER;
   y NUMBER;
BEGIN
   x:=:a;
   y:=:a;
END;

次のブロックを実行するアプリケーションでも、1つのパラメータのみをバインドします。

BEGIN
   INSERT INTO tab1 VALUES(:a, :a);
END

さらに、次のCALL文でも同様です。

...CALL proc(:a, :a)...

次のブロックを実行するアプリケーションでは、:aを1番目のパラメータ、:bを2番目のパラメータとして、2つのパラメータをバインドします。各INSERT文の2番目のパラメータは、最初のINSERT文の最初のパラメータと同じ値を使用します。

BEGIN
   INSERT INTO tab1 VALUES(:a, :a);
   INSERT INTO tab1 VALUES(:b, :a);
END

浮動小数点データに関する考慮事項

浮動小数点データに関する考慮事項を示します。

BINARY_DOUBLEおよびBINARY_FLOATデータ型は、IEEEの浮動小数点の値Inf、-InfおよびNaNを格納および取得します。アプリケーションでprintf、scanfまたはstrtodのような文字データへの変換を必要とするC言語機能を使用した場合、浮動小数点の値はINF、-INFおよびNANとして返されます。これらのキャラクタ文字列を浮動小数点の値に戻すことはできません。

ドライバ・マネージャ使用時のSQL_WCHARおよびSQL_WVARCHARの使用

この項では、ドライバ・マネージャ使用時にSQL_WCHARまたはSQL_WVARCHARを使用した場合のエラー状態を回避する方法について説明します。

Windowsのドライバ・マネージャを使用するアプリケーションでは、SQLBindParameterで、SQL_WCHARまたはSQL_WVARCHARのfSqlType値を渡すと、SQL状態S1004(SQLデータ型が範囲外)でエラーが発生する場合があります。この問題は、かわりにfSqlTypeに次のいずれかの値を渡すことで回避できます。

• SQL_WCHARではなくSQL_WCHAR_DM_SQLBINDPARAMETER_BYPASS

• SQL_WVARCHARではなくSQL_WVARCHAR_DM_SQLBINDPARAMETER_BYPASS

これらの値は、意味的にはSQL_WCHARおよびSQL_WVARCHARと同じですが、Windowsのドライバ・マネージャからのエラーを回避します。これらは、ドライバ・マネージャとリンクするアプリケーションまたはTimesTen ODBCの直接ドライバやODBCクライアント・ドライバと直接リンクするアプリケーションで使用できます。

「SQLBindParameter関数」を参照してください。

REF CURSORの使用

REF CURSORはPL/SQLの1つの概念で、SQL結果セット上のカーソルに対するハンドルであり、PL/SQLとアプリケーションの間で受渡しすることができます。TimesTenでは、PL/SQL内でカーソルをオープンでき、そのREF CURSORをアプリケーションに渡すことができます。 結果は、アプリケーション内でODBCコールを使用して処理できます。

これがOUT REF CURSOR(PL/SQLに対するOUTパラメータ)です。REF CURSORは文ハンドルにアタッチされ、アプリケーションは任意の結果セットと同じAPIを使用して結果セットを記述およびフェッチできます。

REF CURSORを使用するには、次のステップを実行します。REF CURSOR OUTパラメータを使用してカーソルを返すPL/SQL文を想定しています。なお、REF CURSORでは、「ODBCでの問合せの準備と実行およびカーソルの操作の手順」内のカーソル例と同様の、準備、バインド、実行およびフェッチの基本的な手順を使用します。

1. SQLPrepareを使用して、最初の文ハンドルと関連付けるPL/SQL文を準備します。

2. SQLBindParameterを使用して、文の各パラメータをバインドします。REF CURSOR出力パラメータをバインドする場合、割り当てられた2番目の文ハンドルをrgbValue(データ・バッファへのポインタ)として使用します。

   pcbValue、ibScale、cbValueMaxおよびpcbValue引数は、REF CURSORに対しては無視されます。

   「SQLBindParameter関数」および「出力パラメータのバインド」を参照してください。

3. SQLBindColをコールして、結果列をローカル変数の記憶域にバインドします。

4. SQLExecuteをコールして、文を実行します。

5. SQLFetchをコールして結果をフェッチします。PL/SQLからアプリケーションにREF CURSORが渡された後、アプリケーションは結果セットの場合と同様に、その結果を記述およびフェッチできます。

6. SQLFreeStmtを使用して文ハンドルを解放します。

これらのステップを、次の例で実際に行ってみます。これらの関数の詳細は、ODBC APIのリファレンス・マニュアルを参照してください。『Oracle TimesTen In-Memory Database PL/SQL開発者ガイド』のPL/SQL REF CURSORを参照してください。

ノート:

PL/SQLとアプリケーションの間でREF CURSORを渡す場合、TimesTenでは、PL/SQLからアプリケーションへのOUTREF CURSORのみがサポートされます。

この例では、REF CURSORをループで使用して、問合せの準備、パラメータのバインド、問合せの実行、ローカル変数記憶域への結果のバインド、および結果のフェッチを行う基本的なステップを示します。わかりやすくするためにエラー処理は省略しています。以前に概要を示したODBC関数以外に、この例ではSQLAllocStmtを使用して文ハンドルにメモリーを割り当てます。

refcursor_example(SQLHDBC hdbc)
{
  SQLCHAR*      stmt_text;
  SQLHSTMT      plsql_hstmt;
  SQLHSTMT      refcursor_hstmt;
  SQLINTEGER    deptid;
  SQLINTEGER    depts[3] = {10,30,40};
  SQLINTEGER    empid;
  SQLCHAR       lastname[30];
  SQLINTEGER    i;
 
  /* allocate 2 statement handles: one for the plsql statement and
   * one for the ref cursor */
  SQLAllocStmt(hdbc, &plsql_hstmt);
  SQLAllocStmt(hdbc, &refcursor_hstmt);
 
  /* prepare the plsql statement */
  stmt_text = (SQLCHAR*)
    "begin "
      "open :refc for "
        "select employee_id, last_name "
        "from employees "
        "where department_id = :dept; "
    "end;";
  SQLPrepare(plsql_hstmt, stmt_text, SQL_NTS);
 
  /* bind parameter 1 (:refc) to refcursor_hstmt */
  SQLBindParameter(plsql_hstmt, 1, SQL_PARAM_OUTPUT, SQL_C_REFCURSOR,
                   SQL_REFCURSOR, 0, 0, refcursor_hstmt, 0, 0);
 
  /* bind parameter 2 (:deptid) to local variable deptid */
  SQLBindParameter(plsql_hstmt, 2, SQL_PARAM_INPUT, SQL_C_SLONG,
                   SQL_INTEGER, 0, 0, &deptid, 0, 0);
 
  /* loop through values for :deptid */
  for (i=0; i<3; i++)
  {
     deptid = depts[i];
 
     /* execute the plsql statement */
     SQLExecute(plsql_hstmt);
     /*
      * The result set is now attached to refcursor_hstmt.
      * Bind the result columns and fetch the result set.
      */
 
     /* bind result column 1 to local variable empid */
     SQLBindCol(refcursor_hstmt, 1, SQL_C_SLONG,
                (SQLPOINTER)&empid, 0, 0);
 
     /* bind result column 2 to local variable lastname */
     SQLBindCol(refcursor_hstmt, 2, SQL_C_CHAR,
                (SQLPOINTER)lastname, sizeof(lastname), 0);
 
     /* fetch the result set */
     while(SQLFetch(refcursor_hstmt) != SQL_NO_DATA_FOUND){
       printf("%d, %s\n", empid, lastname);
     }
 
     /* close the ref cursor statement handle */
     SQLFreeStmt(refcursor_hstmt, SQL_CLOSE);
  }
   
  /* drop both handles */
  SQLFreeStmt(plsql_hstmt, SQL_DROP);
  SQLFreeStmt(refcursor_hstmt, SQL_DROP);
}

DML RETURNING (RETURNING INTO句)の使用

DML RETURNINGと呼ばれるRETURNING INTO句をINSERT、UPDATEまたはDELETE文で使用すると、処理の影響を受けた行の特定の項目を返すことができます。

これにより、処理の影響を受けた対象を確認する場合などに、後続のSELECT文および別個のラウンドトリップが不要になります。

ODBCの場合、DML RETURNINGは単一行処理から項目を返すことに限定されます。この句では、項目を出力パラメータのリストに返します。「パラメータのバインドおよび文の実行」の説明に従って、出力パラメータをバインドします。

TimesTenでのRETURNING INTO句のSQL構文および制限事項については、『Oracle TimesTen In-Memory Database SQLリファレンス』のINSERT、UPDATEおよびDELETEで説明されています。

DML RETURNINGの詳細は、『Oracle Database PL/SQL言語リファレンス』のRETURNING INTO句を参照してください。

この例では、「ODBCでのデータベースに対する変更のコミット」内の例を元に、重要な部分を太字で示しています。

void
update_example(SQLHDBC hdbc)
{
   SQLCHAR*      stmt_text;
   SQLHSTMT      hstmt;
   SQLINTEGER    raise_pct;
   char          hiredate_str[30];
   char          last_name[30];
   SQLLEN        hiredate_len;
   SQLLEN        numrows;

   /* allocate a statement handle */
   SQLAllocStmt(hdbc, &hstmt);

   /* prepare an update statement to give a raise to one employee hired
      before a given date and return that employee's last name */
   stmt_text = (SQLCHAR*)
     "update employees "
     "set salary = salary * ((100 + :raise_pct) / 100.0) "
     "where hire_date < :hiredate and rownum = 1 returning last_name into "
                       ":last_name";
   SQLPrepare(hstmt, stmt_text, SQL_NTS);

   /* bind parameter 1 (:raise_pct) to variable raise_pct */
   SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG,
                    SQL_DECIMAL, 0, 0, (SQLPOINTER)&raise_pct, 0, 0);

   /* bind parameter 2 (:hiredate) to variable hiredate_str */
   SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR,
                    SQL_TIMESTAMP, 0, 0, (SQLPOINTER)hiredate_str,
                    sizeof(hiredate_str), &hiredate_len);
   /* bind parameter 3 (:last_name) to variable last_name */
   SQLBindParameter(hstmt, 3, SQL_PARAM_OUTPUT, SQL_C_CHAR,
                    SQL_VARCHAR, 30, 0, (SQLPOINTER)last_name,
                    sizeof(last_name), NULL);
   /* set parameter values to give a 10% raise to an employee hired before
    * January 1, 1996. */
   raise_pct = 10;
   strcpy(hiredate_str, "1996-01-01");
   hiredate_len = SQL_NTS;

   /* execute the update statement */
   SQLExecute(hstmt);

   /* tell us who the lucky person is */
   printf("Gave raise to %s.\n", last_name );

   /* drop the statement handle */
   SQLFreeStmt(hstmt, SQL_DROP);

   /* commit the changes */
   SQLTransact(henv, hdbc, SQL_COMMIT);

}

この例では、昇給の対象者としてKingが返されます。

ROWIDの使用

データベース表の各行には、ROWIDと呼ばれる一意の識別子があります。アプリケーションでは、ROWID擬似列から行のROWIDを取得できます。ROWIDはバイナリまたは文字形式で表すことができます。

アプリケーションでは、SQL文のWHERE句などで、一重引用符で囲んだCHAR定数としてリテラルのROWID値を指定できます。

表2-2に示すとおり、ODBC SQLデータ型のSQL_ROWIDはSQLデータ型のROWIDに対応します。

パラメータおよび結果セット列では、ROWIDは、Cデータ型のSQL_C_BINARY、SQL_C_WCHARおよびSQL_C_CHARとの間で双方向に変換可能です。SQL_C_CHARは、ROWIDのデフォルトのCデータ型です。ROWIDのサイズは、SQL_C_BINARYとしては12バイト、SQL_C_CHARとしては18バイトおよびSQL_C_WCHARとしては36バイトです。

『Oracle TimesTen In-Memory Database SQLリファレンス』のROWIDデータ型およびROWID疑似列を参照してください。

ノート:

TimesTenでは、PL/SQL型UROWIDはサポートされていません。

ラージ・オブジェクト(LOB)

TimesTen ClassicではLOB (ラージ・オブジェクト)がサポートされています。これには、CLOB(Character LOB)、NCLOB(National Character LOB)およびBLOB(Binary LOB)が含まれます。

次の各項では、LOBの概要、およびODBCでのその使用方法について説明します。次のトピックが含まれています。

• LOBについて

• TimesTenにおけるLOBとOracle DatabaseにおけるLOBの相違点

• LOBのプログラム的アプローチとプログラミング・インタフェース

• ODBCにおけるLOB簡易データ・インタフェースの使用

• ODBCにおけるLOBピース単位データ・インタフェースの使用

• ODBCでのパススルーLOB

次の情報も参照できます。

• API固有の情報は、「TimesTen OCIでのLOB」および「TimesTen Pro*C/C++でのLOB」を参照してください。

• TimesTenでのLOBに関する追加情報は、『Oracle TimesTen In-Memory Database SQLリファレンス』のLOBのデータ型を参照してください。

• LOBを使用したプログラミングの全般情報は、Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド(TimesTenの機能に特化した内容ではありません)を参照してください。

LOBについて

LOBは、ラージ・バイナリ・オブジェクト(BLOB)またはキャラクタ・オブジェクト(CLOBまたはNCLOB)です。TimesTenでは、BLOBは最大16 MBで、CLOBまたはNCLOBは最大4 MBです。他に注記がなければ、TimesTenでのLOBには、Oracle Databaseと基本的に同じ機能があります。

「TimesTenにおけるLOBとOracle DatabaseにおけるLOBの相違点」を参照してください。

LOBは、永続または一時のいずれかです。永続LOBは、データベースのLOB列に存在します。一時LOBは、アプリケーション内にのみ存在します。一時LOBが暗黙的に作成される場合があります。たとえば、SELECT文で追加の文字列が連結されたLOBを指定した場合に、連結されたデータを含むためにTimesTenによって一時LOBが作成されます。TimesTen ODBCでは、すべての一時LOBは暗黙的に管理されます。

一時LOBは、TimesTenの一時データ領域に格納されます。

TimesTenにおけるLOBとOracle DatabaseにおけるLOBの相違点

TimesTenとOracle DatabaseとでのLOBの機能の主な違いを示します。

• TimesTenでは、アプリケーションで使用されるLOBは、トランザクションが終了すると無効になります。アプリケーションで使用されたLOBはすべて(明示的、暗黙的のどちらの場合も)、コミットまたはロールバックの後に無効化されます。これにはDDL文の後も含まれます。

• TimesTenでは、BFILE、SecureFile、LOBに対する配列読取りおよび書込みまたはLOBに対するコールバック関数をサポートしていません。

• TimesTenでは、LOBに対する配列のバインドをサポートしていません。

• TimesTenでは、LOBに対するバッチ処理をサポートしていません。

• BLOBに関しては、TimesTenでの16進リテラルの使用方法に違いがあります。『Oracle TimesTen In-Memory Database SQLリファレンス』の定数でHexadecimalLiteralを参照してください。

LOBのプログラム的アプローチとプログラミング・インタフェース

CまたはC++プログラムでのTimesTenからLOBへのアクセスには、3つのプログラミング方法があります。

• 簡易データ・インタフェース(ODBC、OCI、Pro*C/C++、TTClasses): その他のスカラー型と同様に、バインドおよび定義を使用してLOBデータを1チャンクで転送します。

• ピース単位のデータ・インタフェース(ODBC): バインドおよび定義の拡張書式を使用して複数ピース単位でLOBデータを転送します。これは、ストリーミングまたはdata-at-execの使用(プログラムの実行時)と呼ばれることがあります。TimesTenでは、LOBデータをピース単位で探索するポーリング・ループを使用した、ピース単位のデータ・インタフェースをサポートしています。(ピース単位による別の方法であるコールバック関数の使用は、Oracle Databaseではサポートされていますが、TimesTenではサポートされていません。)

  ピース単位のインタフェースを使用すると、アプリケーションから、LOBデータの各部分に個別にアクセスできます。簡易データ・インタフェースで実行されるのと同様のアクションで、アプリケーションによってパラメータがバインドされ、結果が定義されますが、プログラム実行時(at exec)にデータが提供されたものか取得されたものであるかが示されます。TimesTenでは、すべてのLOBデータが読み取られるか書き込まれるまで継続されるポーリング・ループを介してピース単位のデータ・インタフェースを実装できます。

• LOBロケータ・インタフェース(OCI、Pro*C/C++): SQLでLOBロケータを選択し、ファイル・システムへのアクセスで使用するAPIと概念的に似ているAPIを介して、LOBデータにアクセスします。LOBロケータ・インタフェースを使用すると、LOBデータを分割してまたは単一チャンクで使用できます。「TimesTen OCIでのLOB」および「TimesTen Pro*C/C++でのLOB」を参照してください。

LOBロケータ・インタフェースは、使用できる場合は最適なユーティリティを提供します。

ODBCにおけるLOB簡易データ・インタフェースの使用

ODBCでの簡易データ・インタフェースでは、パラメータのバインドにSQLBindParameterを使用し、結果列の定義にSQLBindColを使用します。

アプリケーションは、SQLデータ型を使用してバインドまたは定義することが可能で、このSQLデータ型は次に示すように対応する変数型と互換性があります。

• BLOBデータでは、SQL型SQL_LONGVARBINARYおよびC型SQL_C_BINARYを使用します。

• CLOBデータでは、SQL型SQL_LONGVARCHARおよびC型SQL_C_CHARを使用します。

• NCLOBデータでは、SQL型SQL_WLONGVARCHARおよびC型SQL_C_WCHARを使用します。

LOBデータに対するSQLBindParameterコールおよびSQLBindColコールは、この章で前述した他のデータ型に対するコールとよく似ています。

ノート:

CLOBまたはNCLOBでC型のSQL_C_BINARYを使用したバインドは禁止されています。

ODBCにおけるLOBピース単位データ・インタフェースの使用

ODBCにおけるピース単位データ・インタフェースの場合、パラメータをバインドするにはポーリング・ループでSQLPutDataを指定してSQLParamDataを使用し、結果を取得するにはポーリング・ループでSQLGetDataを使用します。

BLOB、CLOBおよびNCLOBでのサポートされているSQLデータ型とCデータ型については、前述の「ODBCにおけるLOB簡易データ・インタフェースの使用」の項を参照してください。

ノート:

様々なAPIに対する同様のピース単位のデータ・アクセスは、TimesTenの以前のリリースからサポートされています(varデータ型の場合)。

このプログラムの抜粋では、SQLPutDataとSQLParamDataをポーリング・ループで使用して、LOBデータをピース単位でデータベースに挿入します。コードが実行されるとき、CLOB列には"123ABC"の値が含まれています。

...
  /* create a table */
  create_stmt = "create table clobtable ( c clob )";
  rc = SQLExecDirect(hstmt, (SQLCHAR *)create_stmt, SQL_NTS);
  if(rc != SQL_SUCCESS){/* ...error handling... */}
 
  /* initialize an insert statement */
  insert_stmt = "insert into clobtable values(?)";
  rc = SQLPrepare(hstmt, (SQLCHAR *)insert_stmt, SQL_NTS);
  if(rc != SQL_SUCCESS){/* ...error handling... */}
 
  /* bind the parameter and specify that we will be using
   * SQLParamData/SQLPutData */
  rc = SQLBindParameter(
    hstmt,            /* statement handle */
    1,                /* colnum number */
    SQL_PARAM_INPUT,  /* param type */
    SQL_C_CHAR,       /* C type */
    SQL_LONGVARCHAR,  /* SQL type (ignored) */
    2,                /* precision (ignored) */
    0,                /* scale (ignored) */
    0,                /* putdata token */
    0,                /* ignored */
    &pcbvalue);       /* indicates use of SQLPutData */
  if(rc != SQL_SUCCESS){/* ...error handling... */}
 
  pcbvalue = SQL_DATA_AT_EXEC;
 
  /* execute the statement -- this should return SQL_NEED_DATA */
  rc = SQLExecute(hstmt);
  if(rc != SQL_NEED_DATA){/* ...error handling... */}
 
  /* while we still have parameters that need data... */
  while((rc = SQLParamData(hstmt, &unused)) == SQL_NEED_DATA){
 
    memcpy(char_buf, "123", 3);
    rc = SQLPutData(hstmt, char_buf, 3);
    if(rc !=  SQL_SUCCESS){/* ...error handling... */}
 
    memcpy(char_buf, "ABC", 3);
    rc = SQLPutData(hstmt, char_buf, 3);
    if(rc !=  SQL_SUCCESS){/* ...error handling... */}
 
  }
...

ODBCでのパススルーLOB

パススルーLOB (TimesTenを介してアクセスする、Oracle Database内のLOB)は、TimesTenのLOBとして公開され、TimesTenのLOBとほぼ同様にTimesTenでサポートされています。

次の点に留意してください:

• TimesTen LOBのサイズ制限は、パススルーによるOracle DatabaseのLOBの格納には適用されません。

• TimesTenのローカルLOBと同様に、アプリケーションで使用されるパススルーLOBは、トランザクションの終了後は有効ではありません。

プロシージャおよび関数を実行するためのCALLの使用

TimesTen Classicでは、スタンドアロンまたはパッケージの一部であるPL/SQLプロシージャ(procname)またはPL/SQLファンクション(funcname)をコールするため、またはTimesTenの組込みプロシージャ(procname)をコールするためのプログラミング・インタフェースの、次の各構文書式がサポートされています。

CALL procname[(argumentlist)]

CALL funcname[(argumentlist)] INTO :returnparam

CALL funcname[(argumentlist)] INTO ?

TimesTen ODBCでは、次の各構文書式もサポートされています。

{ CALL procname[(argumentlist)] }

{ ? = [CALL] funcname[(argumentlist)] }

{ :returnparam = [CALL] funcname[(argumentlist)] }

次のODBCの例では、TimesTen ttCkpt組込みプロシージャをコールします。

rc = SQLExecDirect (hstmt, (SQLCHAR*) "call ttCkpt",SQL_NTS);

これらの例では、PL/SQLプロシージャmyprocを2つのパラメータでコールします。

rc = SQLExecDirect(hstmt, (SQLCHAR*) "{ call myproc(:param1, :param2) }",SQL_NTS);

rc = SQLExecDirect(hstmt, (SQLCHAR*) "{ call myproc(?, ?) }",SQL_NTS);

PL/SQLファンクションmyfuncをコールするいくつかの方法を次に示します。

rc = SQLExecDirect (hstmt, (SQLCHAR*) "CALL myfunc() INTO :retparam",SQL_NTS);

rc = SQLExecDirect (hstmt, (SQLCHAR*) "CALL myfunc() INTO ?",SQL_NTS);

rc = SQLExecDirect (hstmt, (SQLCHAR*) "{ :retparam = myfunc() }",SQL_NTS);

rc = SQLExecDirect (hstmt, (SQLCHAR*) "{ ? = myfunc() }",SQL_NTS);

『Oracle TimesTen In-Memory Database SQLリファレンス』のCALLを参照してください。

ノート:

• ユーザー独自のプロシージャは、同じ名前のTimesTen組込みプロシージャより優先されますが、このようなネーミングの競合は避けることが最適です。

• TimesTenでは、CALL文に対するSQL_DEFAULT_PARAMとSQLBindParameterの使用はサポートされていません。

SQL文の実行のタイムアウトとしきい値

TimesTenには、SQL文またはプロシージャ・コールの実行時間を制限する方法として、タイムアウト期間の設定と、しきい値期間の設定の2つがあります。これは、SQLExecuteコール、SQLExecDirectコールまたはSQLFetchコールに適用されます。

この項の内容は次のとおりです。

• SQL文のタイムアウト期間の設定

• SQL文のしきい値期間の設定

SQL文のタイムアウト期間の設定

タイムアウトまでのSQL文の実行時間を制御するには、SQLSetStmtOptionまたはSQLSetConnectOptionコールを使用してSQL_QUERY_TIMEOUTオプションを設定することで、タイムアウト値を秒単位で指定できます。値0はタイムアウトが発生しないことを示します。タイムアウト期間に達すると、文の実行が停止し、エラーがスローされます。

ノート:

このような名前にもかかわらず、このタイムアウト値は問合せのみではなく、実行可能なすべてのSQL文に適用されます。

TimesTenでは、SQLQueryTimeout一般接続属性(秒)またはSQLQueryTimeoutMsec一般接続属性(ミリ秒)を使用することで、タイムアウト値を接続、つまり接続の任意の文に対して指定できます。各デフォルト値は0で、タイムアウトはありません。(『Oracle TimesTen In-Memory Databaseリファレンス』のSQLQueryTimeoutおよびSQLQueryTimeoutMsecも参照してください。)

名前によらず、これらのタイムアウト値は問合せだけでなく実行可能なSQL文に適用されます。

SQL_QUERY_TIMEOUTオプションを指定したSQLSetConnectOptionのコールは、前の問合せタイムアウトの設定を上書きします。SQL_QUERY_TIMEOUTオプションを指定したSQLSetStmtOptionのコールは、特定の文の接続設定を上書きします。

問合せのタイムアウト制限は、SQL文がアクティブに実行されている場合にのみ有効です。コミット中またはロールバック中にはタイムアウトは発生しません。多数の行に対して更新、削除または挿入を行うトランザクションでは、コミットまたはロールバックが完了するまでに時間がかかる場合があります。その間、タイムアウト値は無視されます。

『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のSQLおよびPL/SQLのタイムアウト値の選択を参照してください。

ノート:

ロック・タイムアウト値およびSQL問合せタイムアウト値の両方が指定されている場合は、まず、2つの値の小さい方の値によってタイムアウトが発生します。ロック・タイムアウトについては、『Oracle TimesTen In-Memory Databaseリファレンス』のttLockWait (組込みプロシージャ)またはLockWait (一般接続属性)、あるいは『Oracle TimesTen In-Memory Databaseモニタリングおよびトラブルシューティング・ガイド』のデッドロックとタイムアウトの確認を参照してください。

SQL文のしきい値期間の設定

SQL文の実行時間が、指定した期間(秒)を超えたときに、サポート・ログに警告を書き込むように、TimesTenを構成できます。実行は継続され、しきい値による影響は受けません。

デフォルトでは、アプリケーションはしきい値をQueryThreshold一般接続属性設定から取得します(『Oracle TimesTen In-Memory Databaseリファレンス』のQueryThresholdを参照)。デフォルト値は0で、警告は書き込まれません。SQLSetConnectOptionコールでTT_QUERY_THRESHOLDオプションを設定すると、現在の接続の接続属性の設定が上書きされます。このような名前であっても、しきい値は実行可能なすべてのSQL文に適用されます。

SQLSetConnectOptionでしきい値を設定するには、次のように入力します。

RETCODE SQLSetConnectOption(hdbc, TT_QUERY_THRESHOLD, seconds);

SQLSetStmtOptionコールでTT_QUERY_THRESHOLDオプションを設定すると、その文に対する接続属性の設定およびSQLSetConnectOptionによる設定が上書きされます。この設定は、ODBC文ハンドルを使用して実行されるSQL文に適用されます。

SQLSetStmtOptionでしきい値を設定するには、次のように入力します。

RETCODE SQLSetStmtOption(hstmt, TT_QUERY_THRESHOLD, seconds);

SQLGetConnectOptionまたはSQLGetStmtOption ODBC関数を使用して、TT_QUERY_THRESHOLDの現在の値を取得できます。

RETCODE SQLGetConnectOption(hdbc, TT_QUERY_THRESHOLD, paramvalue);

RETCODE SQLGetStmtOption(hstmt, TT_QUERY_THRESHOLD, paramvalue);

ODBCを使用したクライアント/サーバーでの結果セット・バッファ・サイズの構成

クライアント/サーバーでSELECT文から返されるデータについては、クライアントに返されるデータのバッファ・サイズは構成可能であり、パフォーマンス向上のために調整できます。(以前のリリースでは、バッファ・サイズを変更できませんでした。)

バッファ・サイズは、データの行数またはデータのバイト数の単位で設定できます。下限が優先されます。一方の制限を使用し、もう一方は先に到達しないように十分大きい値に設定することをお薦めします。

TimesTenには、次のODBC文属性があります。

• TT_NET_MSG_MAX_ROWS: 行単位でのバッファ・サイズ(デフォルトは8192)
• TT_NET_MSG_MAX_BYTES: バイト単位でのバッファ・サイズ(デフォルトは2097152、つまり2 MB)

これらは接続レベルで設定することもできます。それらを接続ハンドルで設定すると、新しい値は、その接続で将来作成される文ハンドル、およびその接続上の既存の文ハンドルに適用されます。ただし、それらを文レベルで設定することをお薦めします(または、作成する文ハンドルの初期値として設定する場合のみ接続レベルで設定)。

これらの属性は、SQLSetStmtAttr()またはSQLSetConnectAttr()を使用してODBC 3.5属性として、またはSQLSetStmtOption()またはSQLSetConnectOption()を使用してODBC 2.5オプションとしてサポートされます。ODBC 3.5ではSQLGetStmtAttr()、またはODBC 2.5ではSQLGetStmtOption()を使用して、文ハンドルでのみODBCのget関数で値を取得できます。

次に例を示します。

SQLRETURN rc = SQL_SUCCESS;
/* Double the default number of rows */
UDWORD maxRows = 16384;
....
rc = SQLSetConnectAttr(hdbc, TT_NET_MSG_MAX_ROWS, (SQLPOINTER) maxRows, SQL_IS_INTEGER);

ノート:

• これらの属性は、TimesTen接続属性TT_NetMsgMaxRowsおよびTT_NetMsgMaxBytesに対応しており、TimesTen接続文字列またはDSNで設定して、接続で作成されるすべての文の初期値として使用できます。
• 各属性の最小値は1であり、少なくとも1行が必ず返されます。どちらの値も、0に設定するとデフォルト値が使用されます。データ型の最大値(32ビット符号なし整数)以外の最大値設定はありません。
• これらの属性をサポートするクライアント・バージョンが、それらをサポートしていないサーバー・バージョンに接続する場合、設定はすべて無視されます。

キャッシュの機能

TimesTen Classicでのキャッシュの使用に関連する機能を示します。

• ttOptSetFlag組込みプロシージャを使用した一時的なパススルー・レベルの設定

• パススルー・ステータスの確認

• キャッシュ・グループに関する情報の取得

キャッシュについては、『Oracle TimesTen In-Memory Databaseキャッシュ・ガイド』を参照してください。

『Oracle TimesTen In-Memory Databaseキャッシュ・ガイド』のパススルーおよびパススルー・レベルの設定を参照してください。

ttOptSetFlag組込みプロシージャを使用した一時的なパススルー・レベルの設定

TimesTenでは、パススルー・レベルを一時的に設定するためのPassThroughフラグを含む、様々なフラグを設定するためのttOptSetFlag組込みプロシージャが提供されています。

次の例のとおり、ttOptSetFlagを使用して、CアプリケーションでPassThroughを設定できます(この例では、パススルー・レベルは1に設定されます)。この設定によって、トランザクションが終了するまで、準備されたすべての文に適用されます。

rc = SQLExecDirect (hstmt, "call ttOptSetFlag ('PassThrough', 1)",SQL_NTS);

『Oracle TimesTen In-Memory Databaseリファレンス』のttOptSetFlagを参照してください。

パススルー・ステータスの確認

SQL文がTimesTenデータベースで実行されるか、またはOracle Databaseにパススルーされて実行されるかを確認するには、TT_STMT_PASSTHROUGH_TYPE文オプションを指定したODBC関数SQLGetStmtOptionをコールします。

これは次の例のようになります。

rc = SQLGetStmtOption(hStmt, TT_STMT_PASSTHROUGH_TYPE, &passThroughType);

SQL文の準備の後に、このコールを実行できます。これは、PassThrough設定1または2の場合(文が実際にパススルーされるかどうかの確認がコンパイル時まで行われない)に有効です。TT_STMT_PASSTHROUGH_NONEが返された場合、文はTimesTenで実行されます。TT_STMT_PASSTHROUGH_ORACLEが返された場合、文はOracle Databaseにパススルーされて実行されます。

『Oracle TimesTen In-Memory Databaseキャッシュ・ガイド』のパススルー・レベルの設定を参照してください。

ノート:

TT_STMT_PASSTHROUGH_TYPEは、SQLGetStmtOptionでのみサポートされていて、SQLSetStmtOptionではサポートされていません。

キャッシュ・グループに関する情報の取得

キャッシュの使用時は、FLUSH CACHE GROUP、LOAD CACHE GROUP、REFRESH CACHE GROUPまたはUNLOAD CACHE GROUP文の実行の後、ODBC関数SQLRowCountを使用するとフラッシュ、ロード、リフレッシュまたはアンロードされたキャッシュ・インスタンスの数が返されます。

関連情報は、『Oracle TimesTen In-Memory Databaseキャッシュ・ガイド』の処理の影響を受けるキャッシュ・インスタンスの数の確認を参照してください。

SQLRowCountの全般的な情報については、ODBC APIのリファレンス・マニュアルを参照してください。