仕様: | 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);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
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 が返されます。
診断
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 ファイルを参照してください。
参照