CLI の手引きおよび解説書

SQLSetDescRec - 列またはパラメーター・データに複数の記述子フィールドを設定する

目的
仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLSetDescRec() 関数は、列またはパラメーター・データにバインドされているデータ・タイプとバッファーに影響を与える複数の記述子フィールドを設定します。

構文

SQLRETURN   SQLSetDescRec    (SQLHDESC          DescriptorHandle,
                              SQLSMALLINT       RecNumber,
                              SQLSMALLINT       Type,
                              SQLSMALLINT       SubType,
                              SQLINTEGER        Length,
                              SQLSMALLINT       Precision,
                              SQLSMALLINT       Scale,
                              SQLPOINTER        DataPtr,
                              SQLINTEGER        *StringLengthPtr,
                              SQLINTEGER        *IndicatorPtr);

関数引き数

表 162. SQLSetDescRec 引き数
データ・タイプ 引き数 使用法 説明
SQLHDESC DescriptorHandle 入力 記述子ハンドル。 IRD ハンドルであってはなりません。
SQLSMALLINT RecNumber 入力 設定するフィールドを入れる記述子レコードを示します。記述子レコードは 0 から数え、レコード番号 0 がブックマーク・レコードになります。この引き数は、0 以上になっている必要があります。 RecNumber が SQL_DESC_COUNT 値より大きい場合、 RecNumber は SQL_DESC_COUNT 値に変更されます。
SQLSMALLINT Type 入力 記述子レコードに SQL_DESC_TYPE フィールドを設定する値。
SQLSMALLINT SubType 入力 SQL_DATETIME または SQL_INTERVAL タイプのレコードの場合は、この値が SQL_DESC_DATETIME_INTERVAL_CODE フィールドを設定する値になります。
SQLINTEGER Length 入力 記述子レコードに SQL_DESC_OCTET_LENGTH フィールドを設定する値。
SQLSMALLINT Precision 入力 記述子レコードに PRECISION フィールドを設定する値。
SQLSMALLINT Scale 入力 記述子レコードに SCALE フィールドを設定する値。
SQLPOINTER DataPtr 据え置き入出力 記述子レコードに SQL_DESC_DATA_PTR フィールドを設定する値。 DataPtr をヌル・ポインターに設定して、 SQL_DESC_DATA_PTR フィールドをヌル・ポインターに設定することができます。
SQLINTEGER StringLengthPtr 据え置き入出力 記述子レコードに SQL_DESC_OCTET_LENGTH_PTR フィールドを設定する値。 StringLengthPtr をヌル・ポインターに設定して、 SQL_DESC_OCTET_LENGTH_PTR フィールドをヌル・ポインターに設定することができます。
SQLINTEGER IndicatorPtr 据え置き入出力 記述子レコードに SQL_DESC_INDICATOR_PTR フィールドを設定する値。 IndicatorPtr をヌル・ポインターに設定して、 SQL_DESC_INDICATOR_PTR フィールドをヌル・ポインターに設定することができます。

使用法

アプリケーションは、SQLSetDescRec() を呼び出して、単一の列またはパラメーターに以下のフィールドを設定できます。

(SQL_DESC_DATETIME_INTERVAL_CODE も ODBC で定義されていますが、 DB2 CLI ではサポートされていません。)
注:SQLSetDescRec() への呼び出しが失敗した場合、 RecNumber 引き数で識別される記述子レコードの内容は未定義です。

列またはパラメーターをバインドする際、 SQLSetDescRec() を使うと、 SQLBindCol()SQLBindParameter() を呼び出したり、 SQLSetDescField() を何回も呼び出したりしないで、バインド処理に影響を与える複数のフィールドを変更することができます。 SQLSetDescRec() を使うと、現在ステートメントと関連していない記述子にフィールドを設定できます。 SQLBindParameter() を使用すると、 1 回の呼び出しで APD と IPD の両方に設定できるフィールド数が SQLSetDescRec() よりも多く、しかも記述子ハンドルも必要ないことに注目してください。

ステートメント・ハンドル SQL_ATTR_USE_BOOKMARKS は、必ず、 RecNumber 引き数を 0 にしてブックマーク・フィールドを設定し、 SQLSetDescRec() を呼び出す前に設定してください。これは必須ではありませんが、強くお勧めします。

整合性検査

アプリケーションが APD、ARD、または IPD の SQL_DESC_DATA_PTR フィールドを設定すると、 DB2 CLI により整合性検査が自動的に実行されます。 SQLSetDescRec() を呼び出すと、必ず整合性検査が実行されます。他のフィールドと整合性がとれていないフィールドが見つかると、 SQLSetDescRec() が SQLSTATE HY021「整合性がとれていない記述子に関する情報です。 (Inconsistent descriptor information.)」を戻します。

アプリケーション記述子

アプリケーションが APD、ARD、または IPD の SQL_DESC_DATA_PTR フィールドを設定すると、 DB2 CLI は SQL_DESC_TYPE の値とその SQL_DESC_TYPE フィールドに適用可能な値が有効で整合性がとれているかどうか検査します。この検査は、SQLBindParameter() または SQLBindCol() が呼び出されたり、 APD、ARD、または IPD の SQLSetDescRec() が呼び出されたりすると、必ず実行されます。この整合性検査には、アプリケーション記述子フィールドに関する以下の検査も含まれます。

IPD の SQL_DESC_DATA_PTR フィールドは通常設定されませんが、アプリケーションはこのフィールドを設定して、 IPD フィールドの整合性検査を強行できます。整合性検査は、IRD では実行できません。 IPD の SQL_DESC_DATA_PTR フィールドに設定される値は実際には保管されず、 SQLGetDescField() または SQLGetDescRec() では取り出せません。この設定は、整合性検査を強行する目的で行われます。

戻りコード

診断

表 163. SQLSetDescRec SQLSTATE
SQLSTATE 説明 解説
01000 警告。 通知メッセージです。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
07009 記述子索引が無効です。 RecNumber 引き数は 0 に設定されており、 DescriptorHandle は IPD ハンドルでした。

RecNumber 引き数は 0 未満でした。

RecNumber 引き数はデータ・ソースがサポートできる列やパラメーターの最大数より大きな値になっており、 DescriptorHandle 引き数は APD、IPD、または ARD でした。

RecNumber 引き数は 0 と等しく、 DescriptorHandle 引き数は暗黙的に割り当てられた APD を参照していました。 (このエラーは、明示的に割り当てられたアプリケーション記述子が APD か ARD かは実行時までは分からないので、明示的に割り当てられたアプリケーション記述子では発生しません。)

08S01 通信リンクに障害が起きました。 関数が処理を完了する前に、DB2 CLI とその接続先データ・ソースとの間の通信リンクが失敗しました。
HY000 一般的なエラーです。 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。
HY010 関数の順序エラーです。 DescriptorHandle は、非同期で実行中の関数が呼び出された StatementHandle と関連しており、この関数が呼び出された時点でまだ実行中でした。

DescriptorHandle と関連する StatementHandleSQLExecute() または SQLExecDirect() が呼び出され、SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。
HY016 インプリメンテーションの行記述子を変更することはできません。 DescriptorHandle 引き数は、IRD と関連していました。
HY021 記述子情報が不整合です。 記述子の Type フィールド、または TYPE フィールドと関連する他のフィールドは、有効でなかったか、整合性がとれていませんでした。

整合性検査時に検査された記述子情報は、整合性がとれていませんでした。 (『整合性検査』にある SQLSetDescField() を参照してください。)

制約

なし。

該当するサンプルの一覧については、 sqllib\samples\cli (または sqllib/samples/cli) サブディレクトリー内の README ファイルを参照してください。

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]