仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLGetDescField() は、記述子レコードの単一フィールドの現行設定値を返します。
構文
SQLRETURN SQLGetDescField (SQLHDESC DescriptorHandle, SQLSMALLINT RecNumber, SQLSMALLINT FieldIdentifier, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER *StringLengthPtr);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHDESC | DescriptorHandle | 入力 | 記述子ハンドル。 |
SQLSMALLINT | RecNumber | 入力 | アプリケーションが情報を求める記述子レコードを指定します。記述子レコードは 0 から数え、レコード番号 0 がブックマーク・レコードになります。 FieldIdentifier 引き数が記述子ヘッダー・レコードのフィールドを指定する場合、 RecNumber は 0 でなければなりません。 RecNumber が SQL_DESC_COUNT より小さく、行に列またはパラメーターのデータが含まれない場合、 SQLGetDescField() の呼び出しはフィールドの省略時値を返します。詳しくは、『記述子フィールドの初期設定』 の SQLSetDescField() を参照してください。 |
SQLSMALLINT | FieldIdentifier | 入力 | 値を返す記述子のフィールドを指定します。詳しくは、『FieldIdentifier 引き数』 の SQLSetDescField() を参照してください。 |
SQLPOINTER | ValuePtr | 出力 | 記述子情報を返す先のバッファーを指すポインターです。データ・タイプは、FieldIdentifier の値により異なります。 |
SQLINTEGER | BufferLength | 入力 |
|
SQLSMALLINT | *StringLengthPtr | 出力 | *ValuePtr 内に戻すために使用できる総バイト数 (ヌル終了文字に必要なバイト数を除く) を指すポインター。 |
使用法
アプリケーションは、SQLGetDescField() を呼び出して、記述子レコードの単一フィールドの値を返すことができます。 SQLGetDescField() への呼び出しでは、ヘッダー・フィールド、レコード・フィールド、およびブックマーク・フィールドを含むすべての記述子タイプのどのフィールドの設定でも返すことができます。 SQLGetDescField() を繰り返し呼び出すなら、アプリケーションは同じ記述子または異なる記述子にある複数のフィールドの設定を、任意の順序で獲得することができます。 SQLGetDescField() を呼び出して DB2 CLI 定義済み記述子フィールドを返すこともできます。
パフォーマンス上の理由で、ステートメントを実行する前にアプリケーションは IRD の SQLGetDescField() を呼び出すことはできません。
名前、データ・タイプ、および列またはパラメーター・データの記憶域を記述できる複数のフィールドの設定を、 SQLGetDescRec() への単一呼び出しで検索することもできます。 SQLGetStmtAttr() を呼び出して、記述子ヘッダー (ステートメント属性でもある) にある単一のフィールドの設定を返すことができます。
特定の記述子タイプが未定義になっているフィールドの値を検索するためにアプリケーションが SQLGetDescField() を呼び出すとき、この関数は SQLSTATE HY091 (無効な記述子フィールド識別子) を返します。特定の記述子タイプ用に定義済みフィールドの値を検索するためにアプリケーションが SQLGetDescField() を呼び出したものの、省略時値がなく、まだ設定されていないときには、この関数は SQL_SUCCESS を返しますがフィールドに返される値は未定義です。詳しくは、『記述子フィールドの初期設定』の SQLSetDescField() を参照してください。
SQL_DESC_ALLOC_TYPE ヘッダー・フィールドは、読み取り専用として使用可能です。このフィールドは、すべてのタイプの記述子に定義されます。
以下のレコード・フィールドは、読み取り専用として使用可能です。これらのフィールドそれぞれは、IRD 専用か、または IRD と IPD の両方のどちらかに定義されます。
SQL_DESC_AUTO_UNIQUE_VALUE SQL_DESC_LITERAL_SUFFIX SQL_DESC_BASE_COLUMN_NAME SQL_DESC_LOCAL_TYPE_NAME SQL_DESC_CASE_SENSITIVE SQL_DESC_SCHEMA_NAME SQL_DESC_CATALOG_NAME SQL_DESC_SEARCHABLE SQL_DESC_DISPLAY_SIZE SQL_DESC_TABLE_NAME SQL_DESC_FIXED_PREC_SCALE SQL_DESC_TYPE_NAME SQL_DESC_LABEL SQL_DESC_UNSIGNED SQL_DESC_LITERAL_PREFIX SQL_DESC_UPDATABLE
上記のフィールドの説明と、記述子ヘッダーまたはレコードに設定可能なフィールドの説明については、 SQLSetDescField() のセクションを参照してください。記述子の詳細については、記述子の使用を参照してください。
戻りコード
RecNumber が記述子レコードの数よりも大きい場合は、SQL_NO_DATA が返されます。
DescriptorHandle が IRD ハンドルであり、ステートメントが準備済みまたは実行済み状態にあるが、それと関連するオープン・カーソルがない場合、SQL_NO_DATA が返されます。
診断
表 99. SQLGetDescField SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | HandleType 引き数が SQL_HANDLE_DBC、 SQL_HANDLE_STMT、または SQL_HANDLE_DESC であり、基礎メモリー・オブジェクトにアクセスできない (メモリー不足が原因と考えられる) ため、関数呼び出しを処理できませんでした。 |
HY021 | 記述子情報が不整合です。 | 整合性検査時に検査された記述子情報は、整合性がとれていませんでした。詳細については、『整合性検査』 の SQLSetDescField() を参照してください。 |
01004 | データが切り捨てられました。 | バッファー *ValuePtr には記述子フィールド全体を返すのに十分な大きさがなかったため、フィールドが切り捨てられました。切り捨てられていない記述子フィールドの長さが、StringLengthPtr に返されます。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
07009 | 記述子索引が無効です。 | RecNumber 引き数に指定された値は 1 より小さく、
SQL_ATTR_USE_BOOKMARK ステートメント属性は SQL_UB_OFF であり、フィールドはヘッダー・フィールドまたは DB2 CLI 定義済みフィールドではありませんでした。
FieldIdentifier 引き数はレコード・フィールドであり、 RecNumber 引き数は 0 でした。
RecNumber 引き数は 0 より小さく、フィールドはヘッダー・フィールドまたは DB2 CLI 定義済みフィールドではありませんでした。 |
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 は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 名前の長さ引き数のうちの 1 つの値は 0 より小さい値でしたが、 SQL_NTS と等しくありませんでした。 |
HY091 | 記述子タイプが範囲外です。 | DescriptorHandle には FieldIdentifier が定義されていません。
SQL_DESC_COUNT フィールド内の値よりも大きい値が RecNumber 引き数に指定されました。 |
制約
なし。
(ここで完全サンプル dbuse.c を使用することもできます 。)
/* From the CLI sample DBUSE.C */ /* ... */ /* bind the file-parameter /* see how the header field SQL_DESC_ALLOC_TYPE is set. */ sqlrc = SQLGetDescField( hIPD, 0, /* ignored for header fields */ SQL_DESC_ALLOC_TYPE, &descFieldAllocType, /* The result */ SQL_IS_SMALLINT, NULL ); /* ignored */ STMT_HANDLE_CHECK( hstmt, sqlrc); /* ... */ /* see how the field SQL_DESC_PARAMETER_TYPE is set. */ sqlrc = SQLGetDescField( hIPD, 1, /* Look at the parameter */ SQL_DESC_PARAMETER_TYPE, &descFieldParameterType, /* The result */ SQL_IS_SMALLINT, NULL ); /* ignored */ STMT_HANDLE_CHECK( hstmt, sqlrc); /* ... */ /* see how the descriptor record field SQL_DESC_TYPE_NAME is set */ rc = SQLGetDescField( hIRD, (SQLSMALLINT)colCount, SQL_DESC_TYPE_NAME, /* record field */ descFieldTypeName, /* The result */ 25, NULL ); /* ignored */ STMT_HANDLE_CHECK( hstmt, sqlrc);
参照