SQLSetDescRec 関数
準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92
まとめ
SQLSetDescRec 関数は、列またはパラメーター データにバインドされたデータ型とバッファーに影響を与える複数の記述子フィールドを設定します。
構文
SQLRETURN SQLSetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT Type,
SQLSMALLINT SubType,
SQLLEN Length,
SQLSMALLINT Precision,
SQLSMALLINT Scale,
SQLPOINTER DataPtr,
SQLLEN * StringLengthPtr,
SQLLEN * IndicatorPtr);
引数
DescriptorHandle
[入力]記述子ハンドル。 これは IRD ハンドルにすることはできません。
RecNumber
[入力]設定するフィールドを含む記述子レコードを示します。 記述子レコードには 0 から番号が付けられます。レコード番号 0 はブックマーク レコードです。 この引数は、0 以上である必要があります。 RecNumber が SQL_DESC_COUNT の値より大きい場合、SQL_DESC_COUNTis RecNumber の値に変更されます。
Type
[入力]記述子レコードのSQL_DESC_TYPE フィールドを設定する値。
サブタイプ
[入力]型がSQL_DATETIMEまたはSQL_INTERVALレコードの場合、これはSQL_DESC_DATETIME_INTERVAL_CODE フィールドを設定する値です。
[データ型]
[入力]記述子レコードのSQL_DESC_OCTET_LENGTH フィールドを設定する値。
[精度]
[入力]記述子レコードのSQL_DESC_PRECISION フィールドを設定する値。
スケール
[入力]記述子レコードのSQL_DESC_SCALE フィールドを設定する値。
DataPtr
[遅延入力または出力]記述子レコードのSQL_DESC_DATA_PTR フィールドを設定する値。 DataPtr は null ポインターに設定できます。
引数 DataPtr を null ポインターに設定して、SQL_DESC_DATA_PTR フィールドを null ポインターに設定できます。 DescriptorHandle 引数のハンドルが ARD に関連付けられている場合、列のバインドが解除されます。
StringLengthPtr
[遅延入力または出力]記述子レコードのSQL_DESC_OCTET_LENGTH_PTR フィールドを設定する値。 StringLengthPtr を null ポインターに設定して、SQL_DESC_OCTET_LENGTH_PTR フィールドを null ポインターに設定できます。
IndicatorPtr
[遅延入力または出力]記述子レコードのSQL_DESC_INDICATOR_PTR フィールドを設定する値。 IndicatorPtr を null ポインターに設定して、SQL_DESC_INDICATOR_PTR フィールドを null ポインターに設定できます。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLSetDescRec がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値は、HandleType が SQL_HANDLE_DESC で、Handle of DescriptorHandle を使用して SQLGetDiagRec を呼び出すことによって取得できます。 次の表に、 SQLSetDescRec によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 07009 | 記述子インデックスが無効です | RecNumber 引数が 0 に設定され、DescriptorHandle が IPD ハンドルを参照しました。 引数 RecNumber が 0 未満でした。 RecNumber 引数は、データ ソースでサポートできる列またはパラメーターの最大数を超え、DescriptorHandle 引数は APD、IPD、または ARD でした。 RecNumber 引数は 0 に等しく、DescriptorHandle 引数は暗黙的に割り当てられた APD を参照しました。 (このエラーは、明示的に割り当てられたアプリケーション記述子が実行時まで APD か ARD かは不明であるため、明示的に割り当てられたアプリケーション記述子では発生しません)。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されているデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY010 | 関数シーケンス エラー | (DM) DescriptorHandle は、非同期で実行される関数 (この関数ではなく) が呼び出され、この関数が呼び出されたときにまだ実行されていた StatementHandle に関連付けられました。 (DM) DescriptorHandle が関連付けられてSQL_NEED_DATA返された StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 (DM) DescriptorHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 SQLSetDescRec 関数が呼び出されたときに、この非同期関数はまだ実行されていました。 (DM) DescriptorHandle に関連付けられているステートメント ハンドルの 1 つに対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY016 | 実装行記述子を変更できません | DescriptorHandle 引数は IRD に関連付けられました。 |
| HY021 | 一貫性のない記述子情報 | Type フィールド、または記述子の SQL_DESC_TYPE フィールドに関連付けられているその他のフィールドが無効または一貫性が保たれていました。 整合性チェック中に確認された記述子情報に一貫性が見つかりませんでした。 (このセクションの「整合性チェック」を参照してください)。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) ドライバーは ODBC 2.x ドライバー、記述子は ARD、 ColumnNumber 引数は 0 に設定され、引数 BufferLength に指定された値は 4 に等しくありません。 |
| HY117 | トランザクションの状態が不明なため、接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 | (DM) 中断状態の詳細については、「 SQLEndTran 関数」を参照してください。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) DescriptorHandle に関連付けられているドライバーは、 関数をサポートしていません。 |
説明
アプリケーションは SQLSetDescRec を 呼び出して、1 つの列またはパラメーターに対して次のフィールドを設定できます。
SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE (型がSQL_DATETIMEまたはSQL_INTERVALのレコードの場合)
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR
Note
SQLSetDescRec の呼び出しが失敗した場合、引数 RecNumber で識別される記述子レコードの内容は未定義になります。
列またはパラメーターをバインドする場合、 SQLSetDescRec を使用すると、 SQLBindCol または SQLBindParameter を呼び出したり、 SQLSetDescField を複数回呼び出したりすることなく、バインドに影響する複数のフィールドを変更できます。 SQLSetDescRec では 、ステートメントに現在関連付けられていない記述子のフィールドを設定できます。 SQLBindParameter はSQLSetDescRec よりも多くのフィールドを設定し、APD と IPD の両方のフィールドを 1 回の呼び出しで設定でき、記述子ハンドルは必要ありません。
Note
ブックマーク フィールドを設定するには、引数 RecNumber が 0 の SQLSetDescRec を呼び出す前に、ステートメント属性SQL_ATTR_USE_BOOKMARKSを常に設定する必要があります。 これは必須ではありませんが、強くお勧めします。
整合性チェック
整合性チェックは、アプリケーションが APD、ARD、または IPD のSQL_DESC_DATA_PTR フィールドを設定するたびに、ドライバーによって自動的に実行されます。 いずれかのフィールドが他のフィールドと矛盾している場合、 SQLSetDescRec は SQLSTATE HY021 (一貫性のない記述子情報) を返します。
アプリケーションが APD、ARD、または IPD のSQL_DESC_DATA_PTR フィールドを設定するたびに、ドライバーは、SQL_DESC_TYPE フィールドの値と、そのSQL_DESC_TYPE フィールドに適用できる値が有効で一貫性があることを確認します。 このチェックは、 SQLBindParameter または SQLBindCol が呼び出されたとき、または APD、ARD、または IPD に対して SQLSetDescRec が呼び出されたときに常に実行されます。 この整合性チェックには、記述子フィールドに関する次のチェックが含まれます。
SQL_DESC_TYPE フィールドは、有効な ODBC C 型または SQL 型のいずれか、またはドライバー固有の SQL 型である必要があります。 SQL_DESC_CONCISE_TYPE フィールドは、有効な ODBC C 型または SQL 型、またはドライバー固有の C 型または SQL 型のいずれかである必要があります (簡潔な datetime 型と interval 型を含む)。
SQL_DESC_TYPE レコード フィールドがSQL_DATETIMEまたはSQL_INTERVAL場合、SQL_DESC_DATETIME_INTERVAL_CODE フィールドは有効な datetime または interval コードのいずれかである必要があります。 ( SQLSetDescField のSQL_DESC_DATETIME_INTERVAL_CODE フィールドの説明を参照してください)。
SQL_DESC_TYPE フィールドに数値型が示されている場合は、SQL_DESC_PRECISIONフィールドとSQL_DESC_SCALE フィールドが有効であることが確認されます。
SQL_DESC_CONCISE_TYPE フィールドが時刻またはタイムスタンプのデータ型、秒コンポーネントを持つ間隔型、または時間コンポーネントを持つ間隔データ型の 1 つである場合、SQL_DESC_PRECISION フィールドは有効な秒の有効桁数であることが確認されます。
SQL_DESC_CONCISE_TYPEが interval データ型の場合、SQL_DESC_DATETIME_INTERVAL_PRECISION フィールドが有効な間隔先行精度値であることが確認されます。
IPD のSQL_DESC_DATA_PTR フィールドは通常設定されません。ただし、アプリケーションでこれを行って、IPD フィールドの整合性チェックを強制することができます。 IRD に対して整合性チェックを実行することはできません。 IPD のSQL_DESC_DATA_PTR フィールドがに設定されている値は実際には格納されず、 SQLGetDescField または SQLGetDescRec の呼び出しでは取得できません。設定は、整合性チェックを強制するためにのみ行われます。
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| 列のバインド | SQLBindCol 関数 |
| パラメーターのバインド | SQLBindParameter 関数 |
| 1 つの記述子フィールドを取得する | SQLGetDescField 関数 |
| 複数の記述子フィールドの取得 | SQLGetDescRec 関数 |
| 単一記述子フィールドの設定 | SQLSetDescField 関数 |