SQLGetDescField 関数
準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92
まとめ
SQLGetDescField は 、記述子レコードの 1 つのフィールドの現在の設定または値を返します。
構文
SQLRETURN SQLGetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
引数
DescriptorHandle
[入力]記述子ハンドル。
RecNumber
[入力]アプリケーションが情報をシークする記述子レコードを示します。 記述子レコードの番号は 0 で、レコード番号 0 はブックマーク レコードです。 引数 FieldIdentifier がヘッダー フィールドを示す場合、RecNumber は無視されます。 RecNumber がSQL_DESC_COUNT以下で、行に列またはパラメーターのデータが含まれていない場合、SQLGetDescField の呼び出しはフィールドの既定値を返します。 (詳細については、 SQLSetDescField の「記述子フィールドの初期化」を参照してください)。
FieldIdentifier
[入力]値が返される記述子のフィールドを示します。 詳細については、SQLSetDescField の「FieldIdentifier 引数」セクションを参照してください。
ValuePtr
[出力]記述子情報を返すバッファーへのポインター。 データ型は FieldIdentifier の値によって異なります。
ValuePtr が整数型の場合、アプリケーションは SQLULEN のバッファーを使用し、この関数を呼び出す前に値を 0 に初期化する必要があります。一部のドライバーでは、バッファーの下位 32 ビットまたは 16 ビットのみを書き込み、上位ビットは変更されません。
ValuePtr が NULL の場合、StringLengthPtr は、ValuePtr が指すバッファーで返すことができる合計バイト数 (文字データの null 終端文字を除く) を返します。
BufferLength
[入力] FieldIdentifier が ODBC で定義されたフィールドで 、ValuePtr が文字列またはバイナリ バッファーを指している場合、この引数は *ValuePtr の長さにする必要があります。 FieldIdentifier が ODBC 定義フィールドで、*ValuePtr が整数の場合、BufferLength は無視されます。 *ValuePtr の値が Unicode データ型の場合 (SQLGetDescFieldW を呼び出すとき)、BufferLength 引数は偶数である必要があります。
FieldIdentifier がドライバー定義フィールドの場合、アプリケーションは BufferLength 引数を設定することによって、ドライバー マネージャーにフィールドの性質を示します。 BufferLength には、次の値を指定できます。
*ValuePtr が文字列へのポインターの場合、BufferLength は文字列またはSQL_NTSの長さになります。
*ValuePtr がバイナリ バッファーへのポインターである場合、アプリケーションは SQL_LEN_BINARY_ATTR(length) マクロの結果を BufferLength に配置します。 これにより 、BufferLength に負の値が配置されます。
*ValuePtr が文字列またはバイナリ文字列以外の値へのポインターである場合、BufferLength には値がSQL_IS_POINTER必要があります。
*ValuePtr に固定長データ型が含まれている場合、BufferLength は必要に応じて、SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT、またはSQL_IS_USMALLINTのいずれかになります。
StringLengthPtr
[出力]*ValuePtr で返すことができる合計バイト数 (null 終端文字に必要なバイト数を除く) を返すバッファーへのポインター。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA、またはSQL_INVALID_HANDLE。
RecNumber が現在の記述子レコード数より大きい場合、SQL_NO_DATAが返されます。
DescriptorHandle が IRD ハンドルであり、ステートメントが準備済みまたは実行済みの状態にあるが、開いているカーソルが関連付けられていない場合は、SQL_NO_DATAが返されます。
診断
SQLGetDescField がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLGetDescField によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられているリターン コードはSQL_ERROR。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します)。 |
| 01004 | 文字列データ、右切り捨て | バッファー *ValuePtr は記述子フィールド全体を返すには十分な大きさではなかったため、フィールドは切り捨てられました。 *StringLengthPtr で、未使用の記述子フィールドの長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します)。 |
| 07009 | 記述子インデックスが無効です | (DM) RecNumber 引数が 0、SQL_ATTR_USE_BOOKMARKステートメント属性がSQL_UB_OFF、 DescriptorHandle 引数が IRD ハンドルでした。 (このエラーは、記述子がステートメント ハンドルに関連付けられている場合にのみ、明示的に割り当てられた記述子に対して返すことができます)。 FieldIdentifier 引数はレコード フィールド、RecNumber 引数は 0、DescriptorHandle 引数は IPD ハンドルでした。 引数 RecNumber が 0 未満でした。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因について説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY007 | 関連付けられたステートメントが準備されていません | DescriptorHandle が IRD として StatementHandle に関連付けられ、関連付けられたステートメント ハンドルが準備または実行されていませんでした。 |
| HY010 | 関数シーケンス エラー | (DM) DescriptorHandle は、非同期実行関数 (この関数ではなく) が呼び出され、この関数が呼び出されたときにまだ実行されていた StatementHandle に関連付けられています。 (DM) DescriptorHandle は、SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返された StatementHandle に関連付けられています。 この関数は、実行時のすべてのデータ パラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) DescriptorHandle に関連付けられている接続ハンドルに対して非同期的に実行される関数が呼び出されました。 この非同期関数は、 SQLGetDescField 関数が呼び出されたときにまだ実行されていました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY021 | 一貫性のない記述子情報 | SQL_DESC_TYPEフィールドとSQL_DESC_DATETIME_INTERVAL_CODEフィールドは、有効な ODBC SQL型、有効なドライバー固有のSQL型 (IPD の場合)、または有効な ODBC C 型 (APD または ARD の場合) を形成しません。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) *ValuePtr は文字列で、 BufferLength は 0 未満でした。 |
| HY091 | 記述子フィールド識別子が無効です | FieldIdentifier は ODBC で定義されたフィールドではなく、実装定義の値でなかった。 DescriptorHandle の FieldIdentifier が未定義でした。 |
| HY117 | 不明なトランザクション状態が原因で接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、 SQLEndTran 関数を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を介して設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) DescriptorHandle に関連付けられているドライバーは、関数をサポートしていません。 |
コメント
アプリケーションは 、SQLGetDescField を呼び出して、記述子レコードの 1 つのフィールドの値を返すことができます。 SQLGetDescField を呼び出すと、ヘッダー フィールド、レコード フィールド、ブックマーク フィールドなど、任意の記述子型の任意のフィールドの設定を返すことができます。 アプリケーションは、 SQLGetDescField を繰り返し呼び出すことで、同じ記述子または異なる記述子内の複数のフィールドの設定を任意の順序で取得できます。 SQLGetDescField を呼び出して、ドライバー定義の記述子フィールドを返すこともできます。
パフォーマンス上の理由から、アプリケーションはステートメントを実行する前に、IRD に対して SQLGetDescField を呼び出さないでください。
列またはパラメーター データの名前、データ型、およびストレージを記述する複数のフィールドの設定は、 SQLGetDescRec の 1 回の呼び出しでも取得できます。 SQLGetStmtAttr を呼び出して、ステートメント属性でもある記述子ヘッダー内の 1 つのフィールドの設定を返すことができます。 SQLColAttribute、 SQLDescribeCol、 SQLDescribeParam の戻りレコードまたはブックマーク フィールド。
アプリケーションが SQLGetDescField を呼び出して、特定の記述子型に対して未定義のフィールドの値を取得すると、関数はSQL_SUCCESSを返しますが、フィールドに対して返される値は未定義です。 たとえば、APD または ARD のSQL_DESC_NAMEフィールドまたはSQL_DESC_NULLABLE フィールドに対して SQLGetDescField を呼び出すと、SQL_SUCCESSが返されますが、フィールドの未定義の値が返されます。
アプリケーションが SQLGetDescField を呼び出して、特定の記述子型に対して定義されているフィールドの値を取得しますが、既定値がなく、まだ設定されていない場合、関数はSQL_SUCCESSを返しますが、フィールドに対して返される値は未定義です。 記述子フィールドの初期化とフィールドの説明の詳細については、 SQLSetDescField の「記述子フィールドの初期化」を参照してください。 記述子の詳細については、「 記述子」を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 複数の記述子フィールドの取得 | SQLGetDescRec 関数 |
| 1 つの記述子フィールドを設定する | SQLSetDescField 関数 |
| 複数の記述子フィールドの設定 | SQLSetDescRec 関数 |