SQLGetDescRec 関数
準拠
導入されたバージョン: ODBC 3.0 Standards Compliance: ISO 92
まとめ
SQLGetDescRec は 、記述子レコードの複数のフィールドの現在の設定または値を返します。 返されるフィールドは、列またはパラメーター データの名前、データ型、およびストレージを表します。
構文
SQLRETURN SQLGetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLCHAR * Name,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLengthPtr,
SQLSMALLINT * TypePtr,
SQLSMALLINT * SubTypePtr,
SQLLEN * LengthPtr,
SQLSMALLINT * PrecisionPtr,
SQLSMALLINT * ScalePtr,
SQLSMALLINT * NullablePtr);
引数
DescriptorHandle
[入力]記述子ハンドル。
RecNumber
[入力]アプリケーションが情報をシークする記述子レコードを示します。 記述子レコードには 1 から番号が付けられます。レコード番号 0 はブックマーク レコードです。 引数 RecNumber は、SQL_DESC_COUNTの値以下である必要があります。 RecNumber がSQL_DESC_COUNT以下で、行に列またはパラメーターのデータが含まれていない場合、SQLGetDescRec の呼び出しはフィールドの既定値を返します。 (詳細については、 SQLSetDescField の「記述子フィールドの初期化」を参照してください)。
名前
[出力]記述子レコードのSQL_DESC_NAME フィールドを返すバッファーへのポインター。
Name が NULL の場合でも、StringLengthPtr は Name が指すバッファーで返すことができる文字数の合計 (文字データの null 終端文字を除く) を返します。
BufferLength
[入力]*Name バッファーの長さ (文字数)。
StringLengthPtr
[出力]*Name バッファーで返すことができるデータの文字数を返すバッファーへのポインター (null 終端文字を除く)。 文字数が BufferLength 以上の場合、*Name のデータは BufferLength から null 終端文字の長さを引いた値に切り捨てられ、ドライバーによって null で終了されます。
TypePtr
[出力]記述子レコードのSQL_DESC_TYPE フィールドの値を返すバッファーへのポインター。
SubTypePtr
[出力]型がSQL_DATETIMEまたはSQL_INTERVALレコードの場合、これは、SQL_DESC_DATETIME_INTERVAL_CODE フィールドの値を返すバッファーへのポインターです。
LengthPtr
[出力]記述子レコードのSQL_DESC_OCTET_LENGTH フィールドの値を返すバッファーへのポインター。
PrecisionPtr
[出力]記述子レコードのSQL_DESC_PRECISION フィールドの値を返すバッファーへのポインター。
ScalePtr
[出力]記述子レコードのSQL_DESC_SCALE フィールドの値を返すバッファーへのポインター。
NullablePtr
[出力]記述子レコードのSQL_DESC_NULLABLE フィールドの値を返すバッファーへのポインター。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA、またはSQL_INVALID_HANDLE。
RecNumber が現在の記述子レコード数より大きい場合、SQL_NO_DATAが返されます。
DescriptorHandle が IRD ハンドルであり、ステートメントが準備済みまたは実行済みの状態にあるが、それに関連付けられたオープン カーソルがない場合、SQL_NO_DATAが返されます。
診断
SQLGetDescRec がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合は、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_DESCの HandleType と DescriptorHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLGetDescRec によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01004 | 文字列データ、右切り捨て | バッファー *Name が記述子フィールド全体を返すには十分な大きさではなかった。 したがって、フィールドは切り捨てられました。 *StringLengthPtr では、非侵入記述子フィールドの長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 07009 | 記述子インデックスが無効です | 引数 FieldIdentifier はレコード フィールド、RecNumber 引数は 0、DescriptorHandle 引数は IPD ハンドルでした。 (DM) 引数 RecNumber が 0 に設定され、SQL_ATTR_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF に設定され、 DescriptorHandle 引数が IRD ハンドルでした。 引数 RecNumber が 0 未満でした。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY007 | 関連付けられたステートメントが準備されていません | DescriptorHandle が IRD に関連付けられ、関連付けられたステートメント ハンドルが準備済みまたは実行済みの状態にありません。 |
| HY010 | 関数シーケンス エラー | (DM) DescriptorHandle は StatementHandle に関連付けられていたため、非同期実行関数 (この関数ではなく) が呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) DescriptorHandle は、SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返された StatementHandle に関連付けられています。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) DescriptorHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLGetDescRec が呼び出されたときにまだ実行されていました。 |
| HY013 | メモリ管理エラー | メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY117 | 不明なトランザクション状態が原因で接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) DescriptorHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
説明
アプリケーションは SQLGetDescRec を 呼び出して、1 つの列またはパラメーターに対して次の記述子フィールドの値を取得できます。
SQL_DESC_NAME
SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE (型がSQL_DATETIMEまたはSQL_INTERVALのレコードの場合)
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_NULLABLE
SQLGetDescRec では、ヘッダー フィールドの値は取得されません。
アプリケーションでは、フィールドに対応する引数を null ポインターに設定することで、フィールドの設定が戻らないようにすることができます。
アプリケーションが SQLGetDescRec を 呼び出して、特定の記述子型に対して未定義のフィールドの値を取得すると、関数は SQL_SUCCESSを返しますが、フィールドに対して返される値は未定義です。 たとえば、APD または ARD の SQL_DESC_NAME または SQL_DESC_NULLABLE フィールドに対して SQLGetDescRec を呼び出すと、SQL_SUCCESSが返されますが、フィールドの値は未定義になります。
アプリケーションが SQLGetDescRec を 呼び出して、特定の記述子型に対して定義されているが、既定値がなく、まだ設定されていないフィールドの値を取得すると、関数は SQL_SUCCESSを返しますが、フィールドに対して返される値は未定義です。 詳細については、 SQLSetDescField の「記述子フィールドの初期化」を参照してください。
フィールドの値は、 SQLGetDescField の呼び出しによって個別に取得することもできます。 記述子ヘッダーまたはレコード内のフィールドの説明については、「 SQLSetDescField」を参照してください。 記述子の詳細については、「 記述子」を参照してください。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 列のバインド | SQLBindCol 関数 |
| パラメーターのバインド | SQLBindParameter 関数 |
| 記述子フィールドの取得 | SQLGetDescField 関数 |
| 複数の記述子フィールドの設定 | SQLSetDescRec 関数 |
参照
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示