CLI の手引きおよび解説書

SQLGetDescRec - 記述子レコードの複数フィールド設定を入手する

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLGetDescRec() は、記述子レコードの複数フィールドの現行設定を返します。返されたフィールドは、名前、データ・タイプ、および列またはパラメーター・データの記憶域を記述します。

構文

SQLRETURN   SQLGetDescRec    (SQLHDESC          DescriptorHandle,
                              SQLSMALLINT       RecNumber,
                              SQLCHAR           *Name,
                              SQLSMALLINT       BufferLength,
                              SQLSMALLINT       *StringLengthPtr,
                              SQLSMALLINT       *TypePtr,
                              SQLSMALLINT       *SubTypePtr,
                              SQLINTEGER        *LengthPtr,
                              SQLSMALLINT       *PrecisionPtr,
                              SQLSMALLINT       *ScalePtr,
                              SQLSMALLINT       *NullablePtr);

関数引き数

表 100. SQLGetDescRec 引き数
データ・タイプ 引き数 使用法 説明
SQLHDESC DescriptorHandle 入力 記述子ハンドル。
SQLSMALLINT RecNumber 入力 アプリケーションが情報を求める記述子レコードを指定します。記述子レコードは 0 から数え、レコード番号 0 がブックマーク・レコードになります。 RecNumber 引き数は、 SQL_DESC_COUNT の値以下でなければなりません。 RecNumber が SQL_DESC_COUNT より小さく、行に列またはパラメーターのデータが含まれない場合、 SQLGetDescRec() の呼び出しはフィールドの省略時値を返します (詳細については、 SQLSetDescField() の『記述子フィールドの初期化』を参照してください)。
SQLCHAR Name 出力 記述子レコードの SQL_DESC_NAME フィールドを返す先のバッファーを指すポインターです。
SQLINTEGER BufferLength 入力 *Name バッファーの長さ (バイト数)。
SQLSMALLINT *StringLengthPtr 出力 *Name バッファーに返すときに利用可能なデータのバイト数 (ヌル終了文字は除く) を返す先のバッファーを指すポインターです。バイト数が BufferLength と同じか大きい場合、 *Name のデータは、BufferLength からヌル終了文字の長さを引いたものに切り捨てられ、 DB2 CLI によってヌル終了になります。
SQLSMALLINT TypePtr 出力 記述子レコードの SQL_DESC_TYPE フィールドの値を返す先のバッファーを指すポインターです。
SQLSMALLINT SubTypePtr 出力 レコード (タイプが SQL_DATETIME または SQL_INTERVAL) の SQL_DESC_TYPE フィールドの値を返す先のバッファーを指すポインターです。
SQLINTEGER LengthPtr 出力 記述子レコードの SQL_DESC_OCTET_LENGTH フィールドの値を返す先のバッファーを指すポインターです。
SQLSMALLINT PrecisionPtr 出力 記述子レコードの SQL_DESC_PRECISION フィールドの値を返す先のバッファーを指すポインターです。
SQLSMALLINT ScalePtr 出力 記述子レコードの SQL_DESC_SCALE フィールドの値を返す先のバッファーを指すポインターです。
SQLSMALLINT *NullablePtr 出力 記述子レコードの SQL_DESC_NULLABLE フィールドの値を返す先のバッファーを指すポインターです。

使用法

アプリケーションは、SQLGetDescRec() を呼び出して、単一の列またはパラメーターについて、以下のフィールドの値を検索します。

SQLGetDescRec() は、ヘッダー・フィールドの値は検索しません。

アプリケーションは、ヌル・ポインターのフィールドに対応する引き数を設定することにより、フィールドの設定を返すことを禁止することができます。特定の記述子タイプが未定義になっているフィールドの値を検索するためにアプリケーションが SQLGetdescRec() を呼び出すとき、この関数は SQL_SUCCESS を返しますが、フィールドに対して返される値は定義されていません。たとえば、APD または ARD の SQL_DESC_NAME または SQL_DESC_NULLABLE に対して SQLGetDescRec() を呼び出すと SQL_SUCCESS が返されますが、フィールドには未定義の値が返されます。

特定の記述子タイプ用に定義済みフィールドの値を検索するためにアプリケーションが SQLGetDescRec() を呼び出したものの、省略時値がなく、まだ設定されていないときには、この関数は SQL HY091 (無効な記述子フィールド識別子) を返します。

フィールドの値は、SQLGetDescField() の呼び出しによって個々に検索することもできます。記述子ヘッダーまたはレコードのフィールドの説明については、SQLSetDescField - 記述子レコードの単一フィールドを設定するを参照してください。記述子の詳細については、記述子の使用を参照してください。

戻りコード

RecNumber が記述子レコードの数よりも大きい場合は、SQL_NO_DATA が返されます。

DescriptorHandle が IRD ハンドルであり、ステートメントが準備済みまたは実行済み状態にあるが、それと関連するオープン・カーソルがない場合、SQL_NO_DATA が返されます。

診断

表 101. SQLGetDescRec SQLSTATE
SQLSTATE 説明 解説
01000 警告。 通知メッセージ。 (関数は、 SQL_SUCCESS_WITH_INFO を返します。)
01004 データが切り捨てられました。 バッファー *Name には記述子フィールド全体を返すのに十分な大きさがなかったため、フィールドが切り捨てられました。切り捨てられていない記述子フィールドの長さが、StringLengthPtr に返されます。 (関数は、 SQL_SUCCESS_WITH_INFO を返します。)
07009 記述子索引が無効です。 RecNumber 引き数は 0 に設定され、 DescriptorHandle 引き数は IPD ハンドルでした。

RecNumber 引き数は 0 に設定され、 SQL_ATTR_USE_BOOKMARKS ステートメント属性は SQL_UB_OFF に設定されました。

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

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

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

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。

制約

なし。

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

参照


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