分割形式での長いデータの入力および取り出し

アプリケーションが長いデータ値を取り扱う必要がある場合、値全体をストレージにロードすることは実現不可能になることがあります。 そのため、Db2® ODBC では、長いデータ値を分割して取り扱える技法を提供しています。

長いデータ値を分割して処理する技法を、実行時のパラメーター値指定 と呼びます。これは、整数などの固定サイズの非文字データ・タイプを指定するのに使用できる方法と同じです。

次の図では、データを分割して送るプロセスと、データを分割して取り出すプロセスの両方を表しています。図の右側はデータを分割して送るときに使用するプロセスであり、図の左側はデータを 分割して取り出すときに使用するプロセスを示しています。
図 1. 分割形式でのデータの入力および取り出し
図の要約の開始 この図は、データを分割してデータベース・サーバーに送る機能、およびデータを分割して取り出す機能を表したフローチャートです。
詳細な説明が可能

実行時データ・パラメーター

実行時データ・パラメーターとはバインドされたパラメーターのことであり、そのパラメーターに対して 実行時に値の入力を促されます。 通常の場合は、パラメーター用に使用する値をメモリー内に保管してから、SQLExecute() または SQLExecDirect() を 呼び出します。

実行時データ・パラメーターを作成する場合は、SQLBindParameter() を呼び出し、 作成するそれぞれの実行時データ・パラメーターごとに、以下の両方の引数を指定します。
  • 引数 pcbValue を設定して SQL_DATA_AT_EXEC にします。
  • 引数 rgbValue を設定して、ある値にします。この値は、データを提供する必要のある対象 パラメーターを一意的に識別するのに使用可能です。後で参照できるように、この値にはそのパラメーターの 名前を指定します。
SQLExecDirect() および SQLExecute() は、実行時データ・パラメーターを含むステートメントに 対して SQL_NEED_DATA を戻して、値を提供するように促します。SQLExecDirect() または SQLExecute() が SQL_NEED_DATA を戻した場合、アプリケーションで 以下のステップを実行する必要があります。
  1. SQLParamData() を呼び出して、概念的には、最初のその実行時データ・パラメーターに進みます。SQLParamData() は SQL_NEED_DATA を戻し、SQLBindParameter() 呼び出しで指定した 入力バッファー rgbValue の値を提供します。この値は、提供する必要のある情報を確認するのに役立ちます。
  2. SQLPutData() を呼び出し、そのパラメーターごとに実際のデータを渡します。SQLPutData() を繰り返して呼び出し、長いデータを分割して送信します。
  3. この実行時データ・パラメーターのデータ全体を渡した後、SQLParamData() を呼び出します。実行時データ・パラメーターがさらにデータを必要としている場合は、SQLParamData() は SQL_NEED_DATA を 戻します。SQLParamData() が SQL_SUCCESS を戻すまで、ステップ 2 およ び 3 を繰り返します。

すべての実行時データ・パラメーターに値が割り当てられると、SQLParamData() は SQL ステートメント の実行を完了します。また、SQLParamData() は、元の SQLExecDirect() または SQLExecute() が作成した戻り値 および診断情報も戻します。図 1 の右側にこの流れを図示してあります。

実行時データの流れが進行中は、以下の Db2 ODBC 関数のみが呼び出し可能です。
  • SQLParamData() および SQLPutData()。前記の手順に記載したとおり、実行時にパラメーター値を指定します。
  • SQLCancel()。これは、この流れを取り消すために使用するもので、SQL ステートメントを実行せずに、図 1 の右側に記載した流れの繰り返しを強制終了します。
  • SQLGetDiagRec()
実行時データの流れでは、トランザクションを終了することも、接続属性を 設定することもできません。

データを分割して取り出す

SQLGetData() を繰り返し呼び出して、データのより小さな部分を取り出せます。

一般にデータを取り出す場合、取り出したデータを入れるアプリケーション変数を割り振り、これらのアプリケーション変数を結果セットの列に関連付けるために SQLBindCol() を呼び出します。

列に入っている値のサイズを基に、この列からの値がアプリケーションで占有できるメモリーの量を お客様が指定します。(特定の結果列での最大値のサイズを判別するには、SQLDescribeCol() を呼び出します。 出力引数 pcbColDef がこの情報を戻します。)

文字データとバイナリー・データの場合は、大きな値が列に入っている可能性があります。 割り振ったバッファーのサイズよりも列の値が大きい場合は、SQLGetData() を繰り返し呼び出して、この値をいくつかの部分に分割し、より管理しやすいサイズで取得することができます。

図 1 の左側に示すように、SQLGetData() は SQL_SUCCESS_WITH_INFO (SQLSTATE 01004 を伴って) を戻し、この列にはまだデータがあることを 示します。SQLGetData() を繰り返し呼び出して、データの残りの部分を取り出します。データの最後の部分を取り出すと、SQLGetData() は SQL_SUCCESS を戻します。