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 Argument」セクションを参照してください。
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 値を取得するには、HandleType が SQL_HANDLE_STMT で、Handle of 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 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| 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 関数 |