SQLSetDescField 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 3.0 標準準拠: ISO 92

まとめ
SQLSetDescField は、記述子レコードの 1 つのフィールドの値を設定します。

構文

SQLRETURN SQLSetDescField(  
     SQLHDESC      DescriptorHandle,  
     SQLSMALLINT   RecNumber,  
     SQLSMALLINT   FieldIdentifier,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    BufferLength);

引数

DescriptorHandle
[入力]記述子ハンドル。

RecNumber
[入力]アプリケーションが設定しようとしているフィールドを含む記述子レコードを示します。 記述子レコードには 0 から番号が付けられます。レコード番号 0 はブックマーク レコードです。 ヘッダー フィールドの RecNumber 引数は無視されます。

FieldIdentifier
[入力]値が設定される記述子のフィールドを示します。 詳細については、「コメント」セクションの「FieldIdentifier 引数」を参照してください。

ValuePtr
[入力]記述子情報または整数値を含むバッファーへのポインター。 データ型は FieldIdentifier の値によって異なります。 ValuePtr が整数値の場合、FieldIdentifier 引数の値に応じて、8 バイト (SQLLEN)、4 バイト (SQLINTEGER) または 2 バイト (SQLSMALLINT) と見なされる場合があります。

BufferLength
[入力] FieldIdentifier が ODBC で定義されたフィールドで 、ValuePtr が 文字列またはバイナリ バッファーを指している場合、この引数は *ValuePtr の長さである必要があります。 文字列データの場合、この引数には文字列内のバイト数を含める必要があります。

FieldIdentifier が ODBC で定義されたフィールドで、ValuePtr が整数の場合、BufferLength は無視されます。

FieldIdentifier がドライバー定義フィールドの場合、BufferLength 引数を設定することで、フィールドの性質がドライバー マネージャーに示されます。 BufferLength には、次の値を指定できます。

  • ValuePtr が文字列へのポインターの場合、BufferLength は文字列またはSQL_NTSの長さになります。

  • ValuePtr がバイナリ バッファーへのポインターの場合、アプリケーションは bufferLength に SQL_LEN_BINARY_ATTR(length) マクロの結果を配置します。 これにより 、BufferLength に負の値が配置されます。

  • ValuePtr が文字列またはバイナリ文字列以外の値へのポインターである場合、BufferLength には値がSQL_IS_POINTER必要があります。

  • ValuePtr に固定長の値が含まれている場合、BufferLength は必要に応じて、SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT、またはSQL_IS_USMALLINTのいずれかになります。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLSetDescField がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値は、SQL_HANDLE_DESCの HandleType と DescriptorHandle のハンドルを使用して SQLGetDiagRec を呼び出すことによって取得できます。 次の表に、 SQLSetDescField によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S02 オプションの値が変更されました ドライバーは 、*ValuePtr で指定された値 ( ValuePtr がポインターの場合) または ValuePtr の値 ( ValuePtr が整数値の場合) または *ValuePtr が実装作業条件のために無効であったため、ドライバーが同様の値を置き換えました。 (関数はSQL_SUCCESS_WITH_INFOを返します。
07009 記述子インデックスが無効です FieldIdentifier 引数はレコード フィールド、RecNumber 引数は 0、DescriptorHandle 引数は IPD ハンドルを参照しました。

RecNumber 引数が 0 未満で、DescriptorHandle 引数が ARD または APD を参照しました。

RecNumber 引数は、データ ソースがサポートできる列またはパラメーターの最大数を超え、DescriptorHandle 引数が APD または ARD を参照していました。

(DM) FieldIdentifier 引数がSQL_DESC_COUNTされ、 *ValuePtr 引数が 0 未満でした。

RecNumber 引数は 0 に等しく、DescriptorHandle 引数は暗黙的に割り当てられた APD を参照しました。 (このエラーは、明示的に割り当てられたアプリケーション記述子が実行時まで APD または ARD であるかどうかは不明であるため、明示的に割り当てられたアプリケーション記述子では発生しません)。
08S01 通信リンクエラー ドライバーとドライバーが接続されているデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。
22001 文字列データ、右切り捨て FieldIdentifier 引数がSQL_DESC_NAMEされ、BufferLength 引数が SQL_MAX_IDENTIFIER_LEN より大きい値でした。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因について説明します。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。
HY010 関数シーケンス エラー (DM) DescriptorHandle は、非同期で実行される関数 (この関数ではなく) が呼び出され、この関数が呼び出されたときにまだ実行されていた StatementHandle に関連付けられています。

(DM) DescriptorHandle が関連付けられてSQL_NEED_DATA返された StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出されました。 この関数は、実行中のすべてのデータ パラメーターまたは列に対してデータが送信される前に呼び出されました。

(DM) DescriptorHandle に関連付けられている接続ハンドルに対して非同期に実行される関数が呼び出されました。 この非同期関数は、 SQLSetDescField 関数が呼び出されたときにまだ実行されていました。

(DM) DescriptorHandle に関連付けられているステートメント ハンドルの 1 つに対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターに対してデータが取得される前に呼び出されました。
HY013 メモリ管理エラー 基になるメモリ オブジェクトにアクセスできなかったため、メモリの状態が低いため、関数呼び出しを処理できませんでした。
HY016 実装行記述子を変更できません DescriptorHandle 引数は IRD に関連付けられていたが、FieldIdentifier 引数がSQL_DESC_ARRAY_STATUS_PTRまたはSQL_DESC_ROWS_PROCESSED_PTRされませんでした。
HY021 一貫性のない記述子情報 SQL_DESC_TYPEフィールドとSQL_DESC_DATETIME_INTERVAL_CODE フィールドは、有効な ODBC SQL型、または有効なドライバー固有のSQL型 (IPD の場合) または有効な ODBC C 型 (APD または ARD の場合) を形成しません。

整合性チェック中に確認された記述子情報に一貫性がありません。 ( SQLSetDescRec の「整合性チェック」を参照してください)。
HY090 文字列またはバッファーの長さが無効です (DM) *ValuePtr は文字列で、 BufferLength は 0 未満ですが、SQL_NTSと等しくありません。

(DM) ドライバーは ODBC 2*.x* ドライバーで、記述子は ARD、 ColumnNumber 引数は 0 に設定され、 引数 BufferLength に指定された値は 4 に等しくありません。
HY091 記述子フィールド識別子が無効です FieldIdentifier 引数に指定された値は ODBC 定義フィールドではなく、実装定義値でなかった。

FieldIdentifier 引数が DescriptorHandle 引数に対して無効でした。

FieldIdentifier 引数は、読み取り専用の ODBC 定義フィールドでした。
HY092 無効な属性/オプション識別子 *ValuePtr の値が FieldIdentifier 引数に対して無効でした。

引数 FieldIdentifier がSQL_DESC_UNNAMEDされ、ValuePtr がSQL_NAMEDされました。
HY105 パラメーターの型が無効です (DM) SQL_DESC_PARAMETER_TYPE フィールドに指定された値が無効です。 (詳細については、SQLBindParameter の「InputOutputType 引数」セクションを参照してください)。
HY117 不明なトランザクション状態が原因で接続が中断されます。 切断と読み取り専用の関数のみが許可されます。 (DM) 中断状態の詳細については、「 ODBC 3.8 の新機能」を参照してください。
HYT01 接続のタイムアウト 接続タイムアウト期間は、データ ソースが要求に応答する前に期限切れになりました。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。
IM001 ドライバーは、この関数をサポートしていません。 (DM) DescriptorHandle に関連付けられているドライバーは、関数をサポートしていません。

コメント

アプリケーションは SQLSetDescField を呼び出して、記述子フィールドを一度に 1 つずつ設定できます。 SQLSetDescField を 1 回呼び出すと、1 つの記述子に 1 つのフィールドが設定されます。 フィールドを設定できる場合は、この関数を呼び出して、任意の記述子型の任意のフィールドを設定できます。 (このセクションの後半の表を参照してください)。

注意

SQLSetDescField の呼び出しが失敗した場合、RecNumber 引数によって識別される記述子レコードの内容は未定義になります。

他の関数を呼び出して、関数の 1 回の呼び出しで複数の記述子フィールドを設定できます。 SQLSetDescRec 関数は、列またはパラメーターにバインドされたデータ型とバッファー (SQL_DESC_TYPE、SQL_DESC_DATETIME_INTERVAL_CODE、SQL_DESC_OCTET_LENGTH、SQL_DESC_PRECISION、SQL_DESC_SCALE、SQL_DESC_DATA_PTR、SQL_DESC_OCTET_LENGTH_PTR、およびSQL_DESC_INDICATOR_PTRフィールド) に影響するさまざまなフィールドを設定します。 SQLBindCol または SQLBindParameter を使用して、列またはパラメーターのバインドの完全な仕様を作成できます。 これらの関数は、1 つの関数呼び出しで記述子フィールドの特定のグループを設定します。

SQLSetDescField を呼び出してバインド バッファーを変更するには、バインド ポインター (SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、またはSQL_DESC_OCTET_LENGTH_PTR) にオフセットを追加します。 これにより、 SQLBindCol または SQLBindParameter を呼び出さずにバインド バッファーが変更されます。これにより、アプリケーションは他のフィールド (SQL_DESC_DATA_TYPE など) を変更せずにSQL_DESC_DATA_PTRを変更できます。

アプリケーションが SQLSetDescField を呼び出して、SQL_DESC_COUNT以外のフィールドまたは遅延フィールドSQL_DESC_DATA_PTR、SQL_DESC_OCTET_LENGTH_PTR、またはSQL_DESC_INDICATOR_PTRを設定すると、レコードはバインド解除されます。

記述子ヘッダー フィールドは、適切な FieldIdentifier を使用して SQLSetDescField を呼び出すことによって設定されます。 多くのヘッダー フィールドもステートメント属性であるため、 SQLSetStmtAttr の呼び出しで設定することもできます。 これにより、アプリケーションは最初に記述子ハンドルを取得せずに記述子フィールドを設定できます。 SQLSetDescField を呼び出してヘッダー フィールドを設定すると、RecNumber 引数は無視されます。

RecNumber 0 は、ブックマーク フィールドを設定するために使用されます。

注意

SQLSetDescField を呼び出してブックマーク フィールドを設定する前に、ステートメント属性SQL_ATTR_USE_BOOKMARKSを常に設定する必要があります。 これは必須ではありませんが、強くお勧めします。

記述子フィールドの設定シーケンス

SQLSetDescField を呼び出して記述子フィールドを設定する場合、アプリケーションは特定のシーケンスに従う必要があります。

  1. アプリケーションでは、最初に SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE、または SQL_DESC_DATETIME_INTERVAL_CODE フィールドを設定する必要があります。

  2. これらのフィールドのいずれかが設定されると、アプリケーションはデータ型の属性を設定でき、ドライバーはデータ型の属性フィールドをデータ型の適切な既定値に設定します。 型属性フィールドの自動既定値により、アプリケーションがデータ型を指定した後に記述子を常に使用する準備が整います。 アプリケーションがデータ型属性を明示的に設定すると、既定の属性がオーバーライドされます。

  3. 手順 1 に示すフィールドの 1 つが設定され、データ型属性が設定されたら、アプリケーションはSQL_DESC_DATA_PTR設定できます。 これにより、記述子フィールドの整合性チェックが求められます。 SQL_DESC_DATA_PTR フィールドの設定後にアプリケーションでデータ型または属性を変更した場合、ドライバーはSQL_DESC_DATA_PTRを null ポインターに設定し、レコードのバインドを解除します。 これにより、記述子レコードが使用可能になる前に、アプリケーションが適切な手順を順番に完了するように強制されます。

記述子フィールドの初期化

記述子が割り当てられると、記述子内のフィールドを既定値に初期化したり、既定値なしで初期化したり、記述子の型に対して未定義にしたりできます。 次の表は、記述子の種類ごとに各フィールドの初期化を示し、"D" はフィールドが既定値で初期化されていることを示し、"ND" はフィールドが既定値なしで初期化されることを示します。 数値が表示されている場合、フィールドの既定値はその数値になります。 テーブルは、フィールドが読み取り/書き込み (R/W) か読み取り専用 (R) かを示します。

IRD のフィールドには、ステートメントが準備または実行され、ステートメント ハンドルまたは記述子が割り当てられている場合ではなく、IRD が設定された後にのみ既定値があります。 IRD が設定されるまで、IRD のフィールドにアクセスしようとするとエラーが返されます。

一部の記述子フィールドは、記述子の種類 (ARD と IRD、および APD と IPD) の 1 つ以上 (すべてではない) に対して定義されます。 フィールドが記述子の種類に対して未定義の場合、その記述子を使用する関数では必要ありません。

SQLGetDescField からアクセスできるフィールドは、必ずしも SQLSetDescField で設定できるわけではありません。 SQLSetDescField で設定できるフィールドを次の表に示します。

ヘッダー フィールドの初期化の概要については、次の表を参照してください。

ヘッダー フィールド名 種類 R/W Default
SQL_DESC_ALLOC_TYPE SQLSMALLINT ARD: R APD: R IRD: R IPD: R ARD: 暗黙的または明示的なSQL_DESC_ALLOC_USERのSQL_DESC_ALLOC_AUTO

APD: 暗黙的または明示的なSQL_DESC_ALLOC_USERのSQL_DESC_ALLOC_AUTO

IRD: SQL_DESC_ALLOC_AUTO

IPD: SQL_DESC_ALLOC_AUTO
SQL_DESC_ARRAY_SIZE SQLULEN ARD: R/W APD: R/W IRD: 未使用 IPD: 未使用 ARD:[1] APD:[1] IRD: 未使用 IPD: 未使用
SQL_DESC_ARRAY_STATUS_PTR SQLUSMALLINT* ARD: R/W APD: R/W IRD: R/W IPD: R/W ARD: Null ptr APD: Null ptr IRD: Null ptr IPD: Null ptr
SQL_DESC_BIND_OFFSET_PTR SQLLEN* ARD: R/W APD: R/W IRD: 未使用 IPD: 未使用 ARD: Null ptr APD: Null ptr IRD: 未使用 IPD: 未使用
SQL_DESC_BIND_TYPE SQLINTEGER ARD: R/W APD: R/W IRD: 未使用 IPD: 未使用 ARD: SQL_BIND_BY_COLUMN

APD: SQL_BIND_BY_COLUMN

IRD: 未使用

IPD: 未使用
SQL_DESC_COUNT SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: 0 APD: 0 IRD: D IPD: 0
SQL_DESC_ROWS_PROCESSED_PTR SQLULEN* ARD: 未使用 APD: 未使用 IRD: R/W IPD: R/W ARD: 未使用 APD: 未使用 IRD: Null ptr IPD: Null ptr

[1] これらのフィールドは、ドライバーによって IPD が自動的に設定される場合にのみ定義されます。 そうでない場合は未定義です。 アプリケーションがこれらのフィールドを設定しようとすると、SQLSTATE HY091 (無効な記述子フィールド識別子) が返されます。

レコード フィールドの初期化は、次の表に示すとおりです。

レコード フィールド名 種類 R/W Default
SQL_DESC_AUTO_UNIQUE_VALUE SQLINTEGER ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_BASE_COLUMN_NAME SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_BASE_TABLE_NAME SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_CASE_SENSITIVE SQLINTEGER ARD: 未使用 APD: 未使用 IRD: R IPD: R ARD: 未使用 APD: 未使用 IRD: D IPD: D[1]
SQL_DESC_CATALOG_NAME SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_CONCISE_TYPE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: SQL_C_ DEFAULT APD: SQL_C_ DEFAULT IRD: D IPD: ND
SQL_DESC_DATA_PTR SQLPOINTER ARD: R/W APD: R/W IRD: 未使用 IPD: 未使用 ARD: Null ptr APD: Null ptr IRD: 未使用 IPD: 未使用[2]
SQL_DESC_DATETIME_INTERVAL_CODE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_DATETIME_INTERVAL_PRECISION SQLINTEGER ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_DISPLAY_SIZE SQLLEN ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_FIXED_PREC_SCALE SQLSMALLINT ARD: 未使用 APD: 未使用 IRD: R IPD: R ARD: 未使用 APD: 未使用 IRD: D IPD: D[1]
SQL_DESC_INDICATOR_PTR SQLLEN * ARD: R/W APD: R/W IRD: 未使用 IPD: 未使用 ARD: Null ptr APD: Null ptr IRD: 未使用 IPD: 未使用
SQL_DESC_LABEL SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_LENGTH SQLULEN ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_LITERAL_PREFIX SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_LITERAL_SUFFIX SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_LOCAL_TYPE_NAME SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: R ARD: 未使用 APD: 未使用 IRD: D IPD: D[1]
SQL_DESC_NAME SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_NULLABLE SQLSMALLINT ARD: 未使用 APD: 未使用 IRD: R IPD: R ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_NUM_PREC_RADIX SQLINTEGER ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_OCTET_LENGTH SQLLEN ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_OCTET_LENGTH_PTR SQLLEN * ARD: R/W APD: R/W IRD: 未使用 IPD: 未使用 ARD: Null ptr APD: Null ptr IRD: 未使用 IPD: 未使用
SQL_DESC_PARAMETER_TYPE SQLSMALLINT ARD: 未使用 APD: 未使用 IRD: 未使用 IPD: R/W ARD: 未使用 APD: 未使用 IRD: 未使用 IPD: D=SQL_PARAM_INPUT
SQL_DESC_PRECISION SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_ROWVER SQLSMALLINT ARD: 未使用

APD: 未使用

IRD: R

IPD: R		 ARD: 未使用

APD: 未使用

IRD: ND

IPD: ND
SQL_DESC_SCALE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_SCHEMA_NAME SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_SEARCHABLE SQLSMALLINT ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_TABLE_NAME SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用
SQL_DESC_TYPE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: SQL_C_DEFAULT APD: SQL_C_DEFAULT IRD: D IPD: ND
SQL_DESC_TYPE_NAME SQLCHAR * ARD: 未使用 APD: 未使用 IRD: R IPD: R ARD: 未使用 APD: 未使用 IRD: D IPD: D[1]
SQL_DESC_UNNAMED SQLSMALLINT ARD: 未使用 APD: 未使用 IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_UNSIGNED SQLSMALLINT ARD: 未使用 APD: 未使用 IRD: R IPD: R ARD: 未使用 APD: 未使用 IRD: D IPD: D[1]
SQL_DESC_UPDATABLE SQLSMALLINT ARD: 未使用 APD: 未使用 IRD: R IPD: 未使用 ARD: 未使用 APD: 未使用 IRD: D IPD: 未使用

[1] これらのフィールドは、IPD がドライバーによって自動的に設定される場合にのみ定義されます。 そうでない場合、それらは未定義です。 アプリケーションがこれらのフィールドを設定しようとすると、SQLSTATE HY091 (無効な記述子フィールド識別子) が返されます。

[2] IPD のSQL_DESC_DATA_PTR フィールドは、整合性チェックを強制するように設定できます。 SQLGetDescField または SQLGetDescRec の後続の呼び出しでは、ドライバーは、SQL_DESC_DATA_PTRに設定された値を返す必要はありません。

FieldIdentifier 引数

FieldIdentifier 引数は、設定する記述子フィールドを示します。 記述子には、次のセクション「ヘッダー フィールド」で説明されているヘッダー フィールドと 0 個以上の記述子レコードで構成される記述子ヘッダーが含まれており、"ヘッダー フィールド" セクションの後のセクションで説明されているレコード フィールドで構成されます。

ヘッダー フィールド

各記述子には、次のフィールドで構成されるヘッダーがあります。

SQL_DESC_ALLOC_TYPE [すべて]
この読み取り専用 SQLSMALLINT ヘッダー フィールドは、記述子がドライバーによって自動的に割り当てられたか、アプリケーションによって明示的に割り当てられたかを指定します。 アプリケーションはこのフィールドを取得できますが、変更することはできません。 記述子がドライバーによって自動的に割り当てられた場合、フィールドはドライバーによってSQL_DESC_ALLOC_AUTOに設定されます。 記述子がアプリケーションによって明示的に割り当てられている場合は、ドライバーによってSQL_DESC_ALLOC_USERに設定されます。

SQL_DESC_ARRAY_SIZE [アプリケーション記述子]
ARD では、この SQLULEN ヘッダー フィールドは行セット内の行数を指定します。 これは、SQLFetch または SQLFetchScroll の呼び出しによって返される、または SQLBulkOperations または SQLSetPos の呼び出しによって操作される行の数です。

APD では、この SQLULEN ヘッダー フィールドは、各パラメーターの値の数を指定します。

このフィールドの既定値は 1 です。 SQL_DESC_ARRAY_SIZEが 1 より大きい場合、APD または ARD ポイントの配列のSQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、およびSQL_DESC_OCTET_LENGTH_PTR。 各配列のカーディナリティは、このフィールドの値と等しくなります。

ARD のこのフィールドは、SQL_ATTR_ROW_ARRAY_SIZE属性を使用して SQLSetStmtAttr を呼び出すことでも設定できます。 APD のこのフィールドは、SQL_ATTR_PARAMSET_SIZE属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。

SQL_DESC_ARRAY_STATUS_PTR [すべて]
記述子の種類ごとに、この SQLUSMALLINT * ヘッダー フィールドは SQLUSMALLINT 値の配列を指します。 これらの配列の名前は、行状態配列 (IRD)、パラメーター状態配列 (IPD)、行操作配列 (ARD)、およびパラメーター操作配列 (APD) です。

IRD では、このヘッダー フィールドは、SQLBulkOperations、SQLFetch、SQLFetchScroll、または SQLSetPos の呼び出し後に状態値を含む行状態配列を指します。 配列には、行セット内の行と同じ数の要素があります。 アプリケーションは、SQLUSMALLINT の配列を割り当て、このフィールドを配列を指す値に設定する必要があります。 既定では、このフィールドは null ポインターに設定されます。 ドライバーは、SQL_DESC_ARRAY_STATUS_PTR フィールドが null ポインターに設定されていない限り、配列に値を設定します。その場合、状態値は生成されず、配列は設定されません。

注意事項

アプリケーションが IRD の SQL_DESC_ARRAY_STATUS_PTR フィールドが指す行状態配列の要素を設定する場合、ドライバーの動作は未定義です。

配列は、最初は SQLBulkOperations、SQLFetch、SQLFetchScroll、または SQLSetPos の呼び出しによって設定されます。 呼び出しでSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOが返されなかった場合、このフィールドが指す配列の内容は未定義です。 配列内の要素には、次の値を含めることができます。

  • SQL_ROW_SUCCESS: 行は正常にフェッチされ、最後にフェッチされてから変更されていません。

  • SQL_ROW_SUCCESS_WITH_INFO: 行は正常にフェッチされ、最後にフェッチされてから変更されていません。 ただし、行に関する警告が返されました。

  • SQL_ROW_ERROR: 行のフェッチ中にエラーが発生しました。

  • SQL_ROW_UPDATED: 行は正常にフェッチされ、最後にフェッチされてから更新されました。 行が再びフェッチされた場合、その状態はSQL_ROW_SUCCESS。

  • SQL_ROW_DELETED: 行は最後にフェッチされてから削除されています。

  • SQL_ROW_ADDED: 行は SQLBulkOperations によって挿入されました。 行が再びフェッチされた場合、その状態はSQL_ROW_SUCCESS。

  • SQL_ROW_NOROW: 行セットは結果セットの末尾に重なり、行ステータス配列のこの要素に対応する行は返されませんでした。

IRD のこのフィールドは、SQL_ATTR_ROW_STATUS_PTR属性を使用して SQLSetStmtAttr を呼び出すことでも設定できます。

IRD のSQL_DESC_ARRAY_STATUS_PTR フィールドは、SQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOが返された後にのみ有効です。 戻りコードがこれらのいずれかでない場合、SQL_DESC_ROWS_PROCESSED_PTRによって指される場所は未定義です。

IPD では、このヘッダー フィールドは、 SQLExecute または SQLExecDirect の呼び出し後にパラメーター値の各セットの状態情報を含むパラメーター状態配列を指します。 SQLExecute または SQLExecDirect の呼び出しでSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOが返されなかった場合、このフィールドが指す配列の内容は未定義になります。 アプリケーションは、SQLUSMALLINT の配列を割り当て、このフィールドが配列を指すよう設定する必要があります。 ドライバーは、SQL_DESC_ARRAY_STATUS_PTR フィールドが null ポインターに設定されていない限り、配列を設定します。その場合、状態値は生成されず、配列は設定されません。 配列内の要素には、次の値を含めることができます。

  • SQL_PARAM_SUCCESS: SQL ステートメントは、この一連のパラメーターに対して正常に実行されました。

  • SQL_PARAM_SUCCESS_WITH_INFO: SQL ステートメントは、この一連のパラメーターに対して正常に実行されましたが、警告情報は診断データ構造で使用できます。

  • SQL_PARAM_ERROR: このパラメーターセットの処理中にエラーが発生しました。 追加のエラー情報は、診断データ構造で入手できます。

  • SQL_PARAM_UNUSED: このパラメーター セットは使用されていませんでした。これは、以前のパラメーター セットによってエラーが発生して処理が中止された、または APD の SQL_DESC_ARRAY_STATUS_PTR フィールドで指定された配列内のパラメーターセットに対してSQL_PARAM_IGNOREが設定されたことが原因である可能性があります。

  • SQL_PARAM_DIAG_UNAVAILABLE: 診断情報は使用できません。 この例として、ドライバーがパラメーターの配列をモノリシック単位として扱い、このレベルのエラー情報が生成されない場合があります。

IPD 内のこのフィールドは、SQL_ATTR_PARAM_STATUS_PTR属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。

ARD では、このヘッダー フィールドは、 SQLSetPos 操作でこの行を無視するかどうかを示すためにアプリケーションで設定できる値の行操作配列を指します。 配列内の要素には、次の値を含めることができます。

  • SQL_ROW_PROCEED: 行は 、SQLSetPos を使用した一括操作に含まれます。 (この設定では、行に対して操作が行われることは保証されません。行の状態が IRD 行の状態配列にSQL_ROW_ERROR場合、ドライバーは行で操作を実行できない可能性があります。

  • SQL_ROW_IGNORE: 行は、SQLSetPos を使用した一括操作から除外されます。

配列の要素が設定されていない場合、すべての行が一括操作に含まれます。 ARD の SQL_DESC_ARRAY_STATUS_PTR フィールドの値が null ポインターの場合、すべての行が一括操作に含まれます。解釈は、ポインターが有効な配列を指していて、配列のすべての要素がSQL_ROW_PROCEEDされた場合と同じです。 配列内の要素が SQL_ROW_IGNORE に設定されている場合、無視された行の行ステータス配列の値は変更されません。

ARD のこのフィールドは、SQL_ATTR_ROW_OPERATION_PTR属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。

APD では、このヘッダー フィールドは、 SQLExecute または SQLExecDirect が呼び出されたときにこのパラメーターセットを無視するかどうかを示すためにアプリケーションで設定できる値のパラメーター操作配列を指します。 配列内の要素には、次の値を含めることができます。

  • SQL_PARAM_PROCEED: パラメーターのセットは 、SQLExecute または SQLExecDirect 呼び出しに含まれます。

  • SQL_PARAM_IGNORE: パラメーターのセットは 、SQLExecute または SQLExecDirect 呼び出しから除外されます。

配列の要素が設定されていない場合、配列内のすべてのパラメーター セットが SQLExecute または SQLExecDirect 呼び出しで使用されます。 APD の SQL_DESC_ARRAY_STATUS_PTR フィールドの値が null ポインターの場合は、パラメーターのすべてのセットが使用されます。解釈は、ポインターが有効な配列を指していて、配列のすべての要素がSQL_PARAM_PROCEEDされた場合と同じです。

APD のこのフィールドは、SQL_ATTR_PARAM_OPERATION_PTR属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。

SQL_DESC_BIND_OFFSET_PTR [アプリケーション記述子]
この SQLLEN * ヘッダー フィールドは、バインディング オフセットを指します。 既定では null ポインターに設定されています。 このフィールドが null ポインターでない場合、ドライバーはポインターを逆参照し、フェッチ時に記述子レコード (SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、SQL_DESC_OCTET_LENGTH_PTR) に null 以外の値を持つ遅延フィールドのそれぞれに逆参照値を追加し、バインド時に新しいポインター値を使用します。

バインド オフセットは常に、SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、SQL_DESC_OCTET_LENGTH_PTR フィールドの値に直接追加されます。 オフセットが別の値に変更された場合でも、新しい値は各記述子フィールドの値に直接追加されます。 新しいオフセットは、フィールド値にそれ以前のオフセットを加えたものには追加されません。

このフィールドは 遅延フィールドです。これは設定時には使用されませんが、データ バッファーのアドレスを決定する必要がある場合は、ドライバーによって後で使用されます。

ARD のこのフィールドは、SQL_ATTR_ROW_BIND_OFFSET_PTR属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。 ARD のこのフィールドは、SQL_ATTR_PARAM_BIND_OFFSET_PTR属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。

詳細については、 SQLFetchScroll と SQLBindParameter の行方向バインドの説明を参照してください。

SQL_DESC_BIND_TYPE [アプリケーション記述子]
この SQLUINTEGER ヘッダー フィールドは、列またはパラメーターのバインドに使用するバインドの向きを設定します。

ARD では、このフィールドは、関連付けられたステートメント ハンドルで SQLFetchScroll または SQLFetch を呼び出すときのバインディングの向きを指定します。

列に対して列方向のバインドを選択するには、このフィールドを SQL_BIND_BY_COLUMN (既定値) に設定します。

ARD のこのフィールドは、SQL_ATTR_ROW_BIND_TYPE属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。

APD では、このフィールドは動的パラメーターに使用するバインドの向きを指定します。

パラメーターに対して列方向のバインドを選択するには、このフィールドを SQL_BIND_BY_COLUMN (既定値) に設定します。

APD のこのフィールドは、SQL_ATTR_PARAM_BIND_TYPE属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。

SQL_DESC_COUNT [すべて]
この SQLSMALLINT ヘッダー フィールドは、データを含む最も番号の大きいレコードの 1 から始まるインデックスを指定します。 ドライバーは、記述子のデータ構造を設定するときにも、重要なレコードの数を表示するSQL_DESC_COUNTフィールドを設定する必要があります。 アプリケーションがこのデータ構造のインスタンスを割り当てるときに、領域を予約するレコードの数を指定する必要はありません。 アプリケーションがレコードの内容を指定すると、ドライバーは、記述子ハンドルが適切なサイズのデータ構造を参照していることを確認するために必要なアクションを実行します。

SQL_DESC_COUNTは、バインドされているすべてのデータ列 (フィールドが ARD 内にある場合) またはバインドされているすべてのパラメーター (フィールドが APD 内にある場合) の数ではなく、最も番号の多いレコードの数です。 番号が最も大きい列またはパラメーターがバインドされていない場合、SQL_DESC_COUNTは、次に番号の大きい列またはパラメーターの番号に変更されます。 (TargetValuePtr 引数を null ポインターに設定して SQLBindCol を呼び出すか、ParameterValuePtr 引数を null ポインターに設定した SQLBindParameter を呼び出して)、列または数値が最も大きい列の数より小さいパラメーターがバインドされていない場合、SQL_DESC_COUNTは変更されません。 追加の列またはパラメーターが、データを含む最も大きい番号のレコードより大きい数値でバインドされている場合、ドライバーは自動的に SQL_DESC_COUNT フィールドの値を増やします。 SQL_UNBIND オプションを指定して SQLFreeStmt を呼び出してすべての列がバインドされていない場合、ARD と IRD のSQL_DESC_COUNTフィールドは 0 に設定されます。 SQL_RESET_PARAMS オプションを指定して SQLFreeStmt を呼び出すと、APD と IPD のSQL_DESC_COUNTフィールドは 0 に設定されます。

SQL_DESC_COUNT内の値は、 SQLSetDescField を呼び出すことによって、アプリケーションによって明示的に設定できます。 SQL_DESC_COUNTの値を明示的に小さくすると、SQL_DESC_COUNTの新しい値より大きい数値を持つすべてのレコードが実質的に削除されます。 SQL_DESC_COUNTの値が明示的に 0 に設定され、フィールドが ARD 内にある場合は、バインドされたブックマーク列を除くすべてのデータ バッファーが解放されます。

ARD のこのフィールドのレコード数には、バインドされたブックマーク列は含まれません。 ブックマーク列のバインドを解除する唯一の方法は、SQL_DESC_DATA_PTR フィールドを null ポインターに設定することです。

SQL_DESC_ROWS_PROCESSED_PTR [実装記述子]
IRD では、この SQLULEN * ヘッダー フィールドは、SQLFetch または SQLFetchScroll の呼び出し後にフェッチされた行数、またはエラー行を含む SQLBulkOperations または SQLSetPos の呼び出しによって実行される一括操作で影響を受ける行数を含むバッファーを指します。

IPD では、この SQLUINTEGER * ヘッダー・フィールドは、処理されたパラメーターのセットの数 (エラー・セットを含む) を含むバッファーを指します。 null ポインターの場合、数値は返されません。

SQL_DESC_ROWS_PROCESSED_PTRは、SQLFetch または SQLFetchScroll (IRD フィールドの場合) または SQLExecute、SQLExecDirect、または SQLParamData (IPD フィールドの場合) の呼び出し後に、SQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOが返された後にのみ有効です。 このフィールドが指すバッファーを埋める呼び出しがSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOを返さない場合、バッファーの内容は定義されません。ただし、SQL_NO_DATAが返されない限り、バッファー内の値は 0 に設定されます。

ARD のこのフィールドは、SQL_ATTR_ROWS_FETCHED_PTR属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。 APD のこのフィールドは、SQL_ATTR_PARAMS_PROCESSED_PTR属性を使用して SQLSetStmtAttr を呼び出すことによっても設定できます。

このフィールドが指すバッファーは、アプリケーションによって割り当てられます。 これは、ドライバーによって設定される遅延出力バッファーです。 既定では null ポインターに設定されています。

レコード フィールド

各記述子には、記述子の種類に応じて列データまたは動的パラメーターを定義するフィールドで構成される 1 つ以上のレコードが含まれます。 各レコードは、単一の列またはパラメーターの完全な定義です。

SQL_DESC_AUTO_UNIQUE_VALUE [IRD]
この読み取り専用 SQLINTEGER レコード フィールドには、列が自動インクリメント列の場合はSQL_TRUE、列が自動インクリメント列でない場合はSQL_FALSEが含まれます。 このフィールドは読み取り専用ですが、基になる自動インクリメント列は必ずしも読み取り専用ではありません。

SQL_DESC_BASE_COLUMN_NAME [IRD]
この読み取り専用 SQLCHAR * レコード フィールドには、結果セット列のベース列名が含まれています。 基本列名が存在しない場合 (式である列の場合と同様)、この変数には空の文字列が含まれます。

SQL_DESC_BASE_TABLE_NAME [IRD]
この読み取り専用 SQLCHAR * レコード フィールドには、結果セット列のベース テーブル名が含まれています。 ベース テーブル名を定義できない場合、または適用できない場合、この変数には空の文字列が含まれます。

SQL_DESC_CASE_SENSITIVE [実装記述子]
この読み取り専用 SQLINTEGER レコード フィールドには、列またはパラメーターが照合順序と比較で大文字と小文字が区別される場合、または列が照合順序や比較で大文字と小文字を区別しない場合、または非文字列である場合にSQL_FALSE SQL_TRUEが含まれます。

SQL_DESC_CATALOG_NAME [IRD]
この読み取り専用 SQLCHAR * レコード フィールドには、列を含むベース テーブルのカタログが含まれています。 列が式の場合、または列がビューの一部である場合、戻り値はドライバーに依存します。 データ ソースがカタログをサポートしていない場合、またはカタログを特定できない場合、この変数には空の文字列が含まれます。

SQL_DESC_CONCISE_TYPE [すべて]
この SQLSMALLINT ヘッダー フィールドは、datetime および interval データ型を含むすべてのデータ型の簡潔なデータ型を指定します。

SQL_DESC_CONCISE_TYPE、SQL_DESC_TYPE、およびSQL_DESC_DATETIME_INTERVAL_CODEフィールドの値は相互に依存しています。 フィールドの 1 つが設定されるたびに、もう 1 つのフィールドも設定する必要があります。 SQL_DESC_CONCISE_TYPEは、 SQLBindCol または SQLBindParameter、または SQLSetDescField の呼び出しによって設定できます。 SQL_DESC_TYPEは、 SQLSetDescField または SQLSetDescRec の呼び出しによって設定できます。

SQL_DESC_CONCISE_TYPEが間隔または datetime データ型以外の簡潔なデータ型に設定されている場合、SQL_DESC_TYPE フィールドは同じ値に設定され、SQL_DESC_DATETIME_INTERVAL_CODE フィールドは 0 に設定されます。

SQL_DESC_CONCISE_TYPEが簡潔な datetime または interval データ型に設定されている場合、SQL_DESC_TYPE フィールドは対応する詳細型 (SQL_DATETIMEまたはSQL_INTERVAL) に設定され、SQL_DESC_DATETIME_INTERVAL_CODE フィールドは適切なサブコードに設定されます。

SQL_DESC_DATA_PTR [アプリケーション記述子と IPD]
この SQLPOINTER レコード フィールドは、パラメーター値 (APD の場合) または列値 (ARD の場合) を含む変数を指します。 このフィールドは 遅延フィールドです。 設定された時点では使用されませんが、後でドライバーがデータを取得するために使用されます。

SQLBindCol の呼び出しで TargetValuePtr 引数が null ポインターの場合、または ARD の SQL_DESC_DATA_PTR フィールドが SQLSetDescField または SQLSetDescRec の呼び出しによって null ポインターに設定されている場合、ARD の SQL_DESC_DATA_PTR フィールドで指定された列はバインドされません。 SQL_DESC_DATA_PTR フィールドが null ポインターに設定されている場合、その他のフィールドは影響を受けません。

このフィールドが指すバッファーを埋める SQLFetch または SQLFetchScroll への呼び出しでSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOが返されなかった場合、バッファーの内容は未定義です。

APD、ARD、または IPD のSQL_DESC_DATA_PTR フィールドが設定されるたびに、ドライバーは、SQL_DESC_TYPE フィールドの値に有効な ODBC C データ型またはドライバー固有のデータ型のいずれかが含まれていること、およびデータ型に影響を与える他のすべてのフィールドに一貫性があることを確認します。 整合性チェックを求めるのは、IPD のSQL_DESC_DATA_PTR フィールドの唯一の使用です。 具体的には、アプリケーションが IPD のSQL_DESC_DATA_PTR フィールドを設定し、後でこのフィールドで SQLGetDescField を呼び出した場合、設定した値が必ずしも返されるとは限りません。 詳細については、 SQLSetDescRec の「整合性チェック」を参照してください。

SQL_DESC_DATETIME_INTERVAL_CODE [すべて]
この SQLSMALLINT レコード フィールドには、SQL_DESC_TYPE フィールドがSQL_DATETIMEまたはSQL_INTERVALされている場合の特定の日時または間隔データ型のサブコードが含まれます。 これは、SQLデータ型と C データ型の両方に当てはまります。 このコードは、"TYPE" または "C_TYPE" (datetime 型の場合) に "CODE" が置き換わるデータ型名、または "INTERVAL" または "C_INTERVAL" に置き換えた "CODE" (間隔型の場合) で構成されます。

アプリケーション記述子のSQL_DESC_TYPEとSQL_DESC_CONCISE_TYPEがSQL_C_DEFAULTに設定されていて、記述子がステートメント ハンドルに関連付けられていない場合、SQL_DESC_DATETIME_INTERVAL_CODEの内容は未定義です。

このフィールドは、次の表に示す datetime データ型に設定できます。

Datetime 型 DATETIME_INTERVAL_CODE
SQL_TYPE_DATE/SQL_C_TYPE_DATE SQL_CODE_DATE
SQL_TYPE_TIME/SQL_C_TYPE_TIME SQL_CODE_TIME
SQL_TYPE_TIMESTAMP/SQL_C_TYPE_TIMESTAMP SQL_CODE_TIMESTAMP

このフィールドは、次の表に示す間隔データ型に設定できます。

[間隔の種類] DATETIME_INTERVAL_CODE
SQL_INTERVAL_DAY/SQL_C_INTERVAL_DAY SQL_CODE_DAY
SQL_INTERVAL_DAY_TO_HOUR/SQL_C_INTERVAL_DAY_TO_HOUR SQL_CODE_DAY_TO_HOUR
SQL_INTERVAL_DAY_TO_MINUTE/SQL_C_INTERVAL_DAY_TO_MINUTE SQL_CODE_DAY_TO_MINUTE
SQL_INTERVAL_DAY_TO_SECOND/SQL_C_INTERVAL_DAY_TO_SECOND SQL_CODE_DAY_TO_SECOND
SQL_INTERVAL_HOUR/SQL_C_INTERVAL_HOUR SQL_CODE_HOUR
SQL_INTERVAL_HOUR_TO_MINUTE/SQL_C_INTERVAL_HOUR_TO_MINUTE SQL_CODE_HOUR_TO_MINUTE
SQL_INTERVAL_HOUR_TO_SECOND/SQL_C_INTERVAL_HOUR_TO_SECOND SQL_CODE_HOUR_TO_SECOND
SQL_INTERVAL_MINUTE/SQL_C_INTERVAL_MINUTE SQL_CODE_MINUTE
SQL_INTERVAL_MINUTE_TO_SECOND/SQL_C_INTERVAL_MINUTE_TO_SECOND SQL_CODE_MINUTE_TO_SECOND
SQL_INTERVAL_MONTH/SQL_C_INTERVAL_MONTH SQL_CODE_MONTH
SQL_INTERVAL_SECOND/SQL_C_INTERVAL_SECOND SQL_CODE_SECOND
SQL_INTERVAL_YEAR/SQL_C_INTERVAL_YEAR SQL_CODE_YEAR
SQL_INTERVAL_YEAR_TO_MONTH/SQL_C_INTERVAL_YEAR_TO_MONTH SQL_CODE_YEAR_TO_MONTH

データ間隔とこのフィールドの詳細については、「 データ型識別子と記述子」を参照してください。

SQL_DESC_DATETIME_INTERVAL_PRECISION [すべて]
この SQLINTEGER レコード・フィールドには、SQL_DESC_TYPE・フィールドがSQL_INTERVALされている場合の有効桁数の先頭の間隔が含まれます。 SQL_DESC_DATETIME_INTERVAL_CODE フィールドが間隔データ型に設定されている場合、このフィールドは既定の間隔の先頭の有効桁数に設定されます。

SQL_DESC_DISPLAY_SIZE [IRD]
この読み取り専用 SQLINTEGER レコード・フィールドには、列のデータを表示するために必要な最大文字数が含まれています。

SQL_DESC_FIXED_PREC_SCALE [実装記述子]
この読み取り専用 SQLSMALLINT レコード フィールドは、列が正確な数値列であり、有効桁数が 0 以外の場合はSQL_TRUEに設定され、列が固定有効桁数と小数点以下桁数の正確な数値列でない場合はSQL_FALSEに設定されます。

SQL_DESC_INDICATOR_PTR [アプリケーション記述子]
ARD では、この SQLLEN * レコード・フィールドは標識変数を指します。 この変数には、列の値が NULL の場合のSQL_NULL_DATAが含まれます。 APD の場合、インジケーター変数は null 動的引数を指定するためにSQL_NULL_DATAに設定されます。 それ以外の場合、変数は 0 です (SQL_DESC_INDICATOR_PTRとSQL_DESC_OCTET_LENGTH_PTRの値が同じポインターでない限り)。

ARD のSQL_DESC_INDICATOR_PTR フィールドが null ポインターの場合、ドライバーは列が NULL かどうかに関する情報を返さないようにします。 列が NULL で、SQL_DESC_INDICATOR_PTRが null ポインターの場合、SQLFetch または SQLFetchScroll の呼び出し後にドライバーがバッファーを設定しようとしたときに、SQLSTATE 22002 (インジケーター変数は必須ですが、指定されていません) が返されます。 SQLFetch または SQLFetchScroll の呼び出しでSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOが返されなかった場合、バッファーの内容は未定義です。

SQL_DESC_INDICATOR_PTR フィールドは、SQL_DESC_OCTET_LENGTH_PTRが指すフィールドが設定されているかどうかを決定します。 列のデータ値が NULL の場合、ドライバーはインジケーター変数をSQL_NULL_DATAに設定します。 その後、SQL_DESC_OCTET_LENGTH_PTRが指すフィールドは設定されません。 フェッチ中に NULL 値が見つからない場合、SQL_DESC_INDICATOR_PTRが指すバッファーは 0 に設定され、SQL_DESC_OCTET_LENGTH_PTRが指すバッファーはデータの長さに設定されます。

APD のSQL_DESC_INDICATOR_PTR フィールドが null ポインターの場合、アプリケーションはこの記述子レコードを使用して NULL 引数を指定することはできません。

このフィールドは 遅延フィールドです。設定された時点では使用されませんが、null 許容性 (ARD の場合) または null 許容性 (APD の場合) を判断するために、ドライバーによって後で使用されます。

SQL_DESC_LABEL [IRD]
この読み取り専用 SQLCHAR * レコード・フィールドには、列ラベルまたはタイトルが含まれています。 列にラベルがない場合、この変数には列名が含まれます。 列に名前が付かず、ラベルが付いていない場合、この変数には空の文字列が含まれます。

SQL_DESC_LENGTH [すべて]
この SQLULEN レコード・フィールドは、文字内の文字ストリングの最大長または実際の長さ、またはバイト単位のバイナリ・データ・タイプです。 固定長データ型の最大長、または可変長データ型の実際の長さです。 その値は、文字列を終了する null 終端文字を常に除外します。 型がSQL_TYPE_DATE、SQL_TYPE_TIME、SQL_TYPE_TIMESTAMP、またはSQL間隔データ型の 1 つである値の場合、このフィールドの長さは、datetime または interval 値の文字列表現の文字数です。

このフィールドの値は、ODBC 2*.x* で定義されている "length" の値とは異なる場合があります。 詳細については、「 付録 D: データ型」を参照してください。

SQL_DESC_LITERAL_PREFIX [IRD]
この読み取り専用 SQLCHAR * レコード フィールドには、ドライバーがこのデータ型のリテラルのプレフィックスとして認識する文字または文字が含まれています。 この変数には、リテラル プレフィックスが適用されないデータ型の空の文字列が含まれています。

SQL_DESC_LITERAL_SUFFIX [IRD]
この読み取り専用 SQLCHAR * レコード フィールドには、ドライバーがこのデータ型のリテラルのサフィックスとして認識する文字または文字が含まれています。 この変数には、リテラル サフィックスが適用されないデータ型の空の文字列が含まれています。

SQL_DESC_LOCAL_TYPE_NAME [実装記述子]
この読み取り専用 SQLCHAR * レコード フィールドには、データ型の通常の名前とは異なる可能性がある、データ型のローカライズされた (ネイティブ言語) 名が含まれています。 ローカライズされた名前がない場合は、空の文字列が返されます。 このフィールドは、表示のみを目的としています。

SQL_DESC_NAME [実装記述子]
行記述子のこの SQLCHAR * レコード・フィールドには、列別名が含まれます (該当する場合)。 列の別名が適用されない場合は、列名が返されます。 どちらの場合も、ドライバーは、SQL_DESC_NAME フィールドを設定するときにSQL_NAMED SQL_DESC_UNNAMED フィールドを設定します。 列名または列の別名がない場合、ドライバーはSQL_DESC_NAME フィールドに空の文字列を返し、SQL_DESC_UNNAMED フィールドをSQL_UNNAMEDに設定します。

アプリケーションは、IPD の SQL_DESC_NAME フィールドをパラメーター名または別名に設定して、ストアド プロシージャ パラメーターを名前で指定できます。 (詳細については、「 名前によるバインド パラメーター (名前付きパラメーター)」を参照してください)。 IRD のSQL_DESC_NAME フィールドは読み取り専用フィールドです。アプリケーションが設定しようとすると、SQLSTATE HY091 (無効な記述子フィールド識別子) が返されます。

IPD では、ドライバーが名前付きパラメーターをサポートしていない場合、このフィールドは未定義です。 ドライバーが名前付きパラメーターをサポートし、パラメーターを記述できる場合は、このフィールドにパラメーター名が返されます。

SQL_DESC_NULLABLE [実装記述子]
IRD では、この読み取り専用 SQLSMALLINT レコード フィールドは、列に NULL 値を含めることができる場合、列に NULL 値がない場合はSQL_NO_NULLS、列が NULL 値を受け入れるかどうかが不明な場合はSQL_NULLABLE_UNKNOWN SQL_NULLABLEされます。 このフィールドは、ベース列ではなく、結果セット列に関連します。

IPD では、動的パラメーターは常に null 許容であり、アプリケーションで設定できないため、このフィールドは常にSQL_NULLABLEに設定されます。

SQL_DESC_NUM_PREC_RADIX [すべて]
SQL_DESC_PRECISION フィールドにはビット数が含まれているため、SQL_DESC_TYPE フィールドのデータ型が近似数値データ型の場合、この SQLINTEGER フィールドには 2 の値が含まれます。 SQL_DESC_PRECISION フィールドには 10 進数の桁数が含まれているため、SQL_DESC_TYPE フィールドのデータ型が正確な数値データ型の場合、このフィールドには 10 の値が含まれます。 このフィールドは、数値以外のすべてのデータ型に対して 0 に設定されます。

SQL_DESC_OCTET_LENGTH [すべて]
この SQLLEN レコード フィールドには、文字列またはバイナリ データ型の長さ (バイト単位) が含まれます。 固定長文字型またはバイナリ型の場合、これは実際の長さ (バイト単位) です。 可変長文字型またはバイナリ型の場合、これはバイト単位の最大長です。 この値は、実装記述子の null 終端文字の領域を常に除外し、アプリケーション記述子の null 終端文字の領域を常に含めます。 アプリケーション データの場合、このフィールドにはバッファーのサイズが含まれます。 APD の場合、このフィールドは出力パラメーターまたは入出力パラメーターに対してのみ定義されます。

SQL_DESC_OCTET_LENGTH_PTR [アプリケーション記述子]
この SQLLEN * レコード フィールドは、動的引数 (パラメーター記述子の場合) またはバインドされた列値 (行記述子の場合) の合計長 (バイト単位) を含む変数を指します。

APD の場合、この値は、文字列とバイナリを除くすべての引数で無視されます。このフィールドがSQL_NTSを指す場合、動的引数は null で終わる必要があります。 バインドされたパラメーターが実行時データ パラメーターであることを示すために、アプリケーションは APD の適切なレコード内のこのフィールドを変数に設定します。このフィールドには、実行時にSQL_DATA_AT_EXEC値またはSQL_LEN_DATA_AT_EXEC マクロの結果が含まれます。 このようなフィールドが複数ある場合は、SQL_DESC_DATA_PTRパラメーターを一意に識別する値に設定して、要求されているパラメーターをアプリケーションが判断するのに役立ちます。

ARD のOCTET_LENGTH_PTR フィールドが null ポインターの場合、ドライバーは列の長さ情報を返しません。 APD のSQL_DESC_OCTET_LENGTH_PTR フィールドが null ポインターの場合、ドライバーは文字列とバイナリ値が null で終わると見なします。 (バイナリ値は null で終わる必要はありませんが、切り捨てを避けるために長さを指定する必要があります)。

このフィールドが指すバッファーを埋める SQLFetch または SQLFetchScroll の呼び出しでSQL_SUCCESSまたはSQL_SUCCESS_WITH_INFOが返されなかった場合、バッファーの内容は未定義になります。 このフィールドは 遅延フィールドです。 設定時には使用されませんが、データのオクテットの長さを判断または示すために、ドライバーによって後で使用されます。

SQL_DESC_PARAMETER_TYPE [IPD]
この SQLSMALLINT レコード・フィールドは、入力パラメーターのSQL_PARAM_INPUT、入出力パラメーターのSQL_PARAM_INPUT_OUTPUT、出力パラメーターのSQL_PARAM_OUTPUT、入出力ストリーム・パラメーターのSQL_PARAM_INPUT_OUTPUT_STREAM、または出力ストリーム・パラメーターのSQL_PARAM_OUTPUT_STREAMに設定されます。 既定ではSQL_PARAM_INPUTに設定されています。

IPD の場合、IPD がドライバーによって自動的に設定されない場合 (SQL_ATTR_ENABLE_AUTO_IPD ステートメント属性はSQL_FALSE)、既定でフィールドはSQL_PARAM_INPUTに設定されます。 アプリケーションでは、入力パラメーターではないパラメーターに対して、IPD でこのフィールドを設定する必要があります。

SQL_DESC_PRECISION [すべて]
この SQLSMALLINT レコード フィールドには、正確な数値型の桁数、おおよその数値型の仮数 (2 進精度) のビット数、またはSQL_TYPE_TIME、SQL_TYPE_TIMESTAMP、またはSQL_INTERVAL_SECONDデータ型の秒の小数部の部分の桁数が含まれます。 このフィールドは、他のすべてのデータ型では定義されていません。

このフィールドの値は、ODBC 2*.x* で定義されている "precision" の値とは異なる場合があります。 詳細については、「 付録 D: データ型」を参照してください。

SQL_DESC_ROWVER [実装記述子]
この SQLSMALLINTrecord フィールドは、行の更新時に列が DBMS によって自動的に変更されるかどうかを示します (たとえば、SQL Serverの "timestamp" 型の列)。 このレコード フィールドの値は、列が行のバージョン管理列の場合はSQL_TRUEに、それ以外の場合はSQL_FALSEに設定されます。 この列属性は、SQL_ROWVERの IdentifierType を使用して SQLSpecialColumns を呼び出して、列が自動的に更新されるかどうかを判断するのと似ています。

SQL_DESC_SCALE [すべて]
この SQLSMALLINT レコード フィールドには、10 進データ型と数値データ型に対して定義された小数点以下桁数が含まれます。 フィールドは、他のすべてのデータ型に対して未定義です。

このフィールドの値は、ODBC 2*.x* で定義されている "scale" の値とは異なる場合があります。 詳細については、「 付録 D: データ型」を参照してください。

SQL_DESC_SCHEMA_NAME [IRD]
この読み取り専用 SQLCHAR * レコード フィールドには、列を含むベース テーブルのスキーマ名が含まれています。 列が式の場合、または列がビューの一部である場合、戻り値はドライバーに依存します。 データ ソースがスキーマをサポートしていない場合、またはスキーマ名を特定できない場合、この変数には空の文字列が含まれます。

SQL_DESC_SEARCHABLE [IRD]
この読み取り専用 SQLSMALLINT レコード フィールドは、次のいずれかの値に設定されます。

  • 列を WHERE 句で使用できない場合にSQL_PRED_NONEします。 (これは ODBC 2*.x* のSQL_UNSEARCHABLE値と同じです)。

  • 列を WHERE 句で使用できるが、 LIKE 述語でのみ使用できる場合にSQL_PRED_CHARします。 (これは ODBC 2*.x* のSQL_LIKE_ONLY値と同じです)。

  • 列が LIKE を除くすべての比較演算子と共に WHERE 句で使用できる場合にSQL_PRED_BASICします。 (これは ODBC 2*.x* のSQL_EXCEPT_LIKE値と同じです)。

  • 列を WHERE 句で任意の比較演算子と共に使用できるかどうかをSQL_PRED_SEARCHABLEします。

SQL_DESC_TABLE_NAME [IRD]
この読み取り専用 SQLCHAR * レコード フィールドには、この列を含むベース テーブルの名前が含まれています。 列が式の場合、または列がビューの一部である場合、戻り値はドライバーに依存します。

SQL_DESC_TYPE [すべて]
この SQLSMALLINT レコード フィールドは、datetime データ型と interval データ型を除くすべてのデータ型の簡潔なSQLまたは C データ型を指定します。 datetime データ型と interval データ型の場合、このフィールドは詳細データ型 (SQL_DATETIMEまたはSQL_INTERVAL) を指定します。

このフィールドにSQL_DATETIMEまたはSQL_INTERVALが含まれている場合は常に、SQL_DESC_DATETIME_INTERVAL_CODEフィールドに簡潔な型に適したサブコードが含まれている必要があります。 datetime データ型の場合、SQL_DESC_TYPEにはSQL_DATETIMEが含まれており、SQL_DESC_DATETIME_INTERVAL_CODE フィールドには特定の datetime データ型のサブコードが含まれます。 間隔データ型の場合、SQL_DESC_TYPEにはSQL_INTERVALが含まれており、SQL_DESC_DATETIME_INTERVAL_CODE フィールドには特定の間隔データ型のサブコードが含まれます。

SQL_DESC_TYPEフィールドとSQL_DESC_CONCISE_TYPEフィールドの値は相互に依存しています。 フィールドの 1 つが設定されるたびに、もう 1 つのフィールドも設定する必要があります。 SQL_DESC_TYPEは、 SQLSetDescField または SQLSetDescRec の呼び出しによって設定できます。 SQL_DESC_CONCISE_TYPEは、 SQLBindCol または SQLBindParameter、または SQLSetDescField の呼び出しによって設定できます。

SQL_DESC_TYPEが interval または datetime データ型以外の簡潔なデータ型に設定されている場合、SQL_DESC_CONCISE_TYPE フィールドは同じ値に設定され、SQL_DESC_DATETIME_INTERVAL_CODE フィールドは 0 に設定されます。

SQL_DESC_TYPEが詳細な datetime または interval データ型 (SQL_DATETIMEまたはSQL_INTERVAL) に設定され、SQL_DESC_DATETIME_INTERVAL_CODE フィールドが適切なサブコードに設定されている場合、SQL_DESC_CONCISE TYPE フィールドは対応する簡潔な型に設定されます。 SQL_DESC_TYPEを簡潔な datetime 型または間隔型のいずれかに設定しようとすると、SQLSTATE HY021 (一貫性のない記述子情報) が返されます。

SQL_DESC_TYPE フィールドが SQLBindCol、 SQLBindParameter、または SQLSetDescField の呼び出しによって設定されている場合、次のフィールドは、次の表に示すように、次の既定値に設定されます。 同じレコードの残りのフィールドの値は未定義です。

SQL_DESC_TYPEの値 その他のフィールドが暗黙的に設定される
SQL_CHAR、SQL_VARCHAR、SQL_C_CHAR、SQL_C_VARCHAR SQL_DESC_LENGTHは 1 に設定されます。 SQL_DESC_PRECISIONは 0 に設定されます。
SQL_DATETIME SQL_DESC_DATETIME_INTERVAL_CODEをSQL_CODE_DATEまたはSQL_CODE_TIMEに設定すると、SQL_DESC_PRECISIONは 0 に設定されます。 SQL_DESC_TIMESTAMPに設定すると、SQL_DESC_PRECISIONは 6 に設定されます。
SQL_DECIMAL、SQL_NUMERIC、SQL_C_NUMERIC SQL_DESC_SCALEは 0 に設定されます。 SQL_DESC_PRECISIONは、それぞれのデータ型に対して実装で定義された有効桁数に設定されます。

SQL_C_NUMERIC値を手動でバインドする方法については、「SQLから C: Numeric」を参照してください。
SQL_FLOAT、SQL_C_FLOAT SQL_DESC_PRECISIONは、SQL_FLOATの実装定義の既定の有効桁数に設定されます。
SQL_INTERVAL SQL_DESC_DATETIME_INTERVAL_CODEが間隔データ型に設定されている場合、SQL_DESC_DATETIME_INTERVAL_PRECISIONは 2 (既定の間隔の先頭の有効桁数) に設定されます。 間隔に秒のコンポーネントがある場合、SQL_DESC_PRECISIONは 6 (既定の間隔の秒の有効桁数) に設定されます。

アプリケーションが SQLSetDescField を呼び出して SQLSetDescRec を呼び出すのではなく、記述子のフィールドを設定する場合、アプリケーションは最初にデータ型を宣言する必要があります。 その場合、前の表に示されている他のフィールドが暗黙的に設定されます。 暗黙的に設定された値のいずれかが許容できない場合、アプリケーションは SQLSetDescField または SQLSetDescRec を呼び出して、許容できない値を明示的に設定できます。

SQL_DESC_TYPE_NAME [実装記述子]
この読み取り専用 SQLCHAR * レコード フィールドには、データ ソース依存型名 ("CHAR"、"VARCHAR" など) が含まれます。 データ型名が不明な場合、この変数には空の文字列が含まれます。

SQL_DESC_UNNAMED [実装記述子]
行記述子のこの SQLSMALLINT レコード フィールドは、SQL_DESC_NAME フィールドを設定するときに、ドライバーによってSQL_NAMEDまたはSQL_UNNAMEDに設定されます。 SQL_DESC_NAME フィールドに列のエイリアスが含まれている場合、または列のエイリアスが適用されない場合、ドライバーはSQL_DESC_UNNAMEDフィールドをSQL_NAMEDに設定します。 アプリケーションが IPD のSQL_DESC_NAME フィールドをパラメーター名またはエイリアスに設定する場合、ドライバーは IPD のSQL_DESC_UNNAMED フィールドをSQL_NAMEDに設定します。 列名または列の別名がない場合、ドライバーはSQL_DESC_UNNAMED フィールドをSQL_UNNAMEDに設定します。

アプリケーションは、IPD のSQL_DESC_UNNAMED フィールドをSQL_UNNAMEDに設定できます。 アプリケーションが IPD のSQL_DESC_UNNAMED フィールドを SQL_NAMED に設定しようとすると、ドライバーは SQLSTATE HY091 (無効な記述子フィールド識別子) を返します。 IRD のSQL_DESC_UNNAMED フィールドは読み取り専用です。SQLSTATE HY091 (無効な記述子フィールド識別子) は、アプリケーションが設定を試みると返されます。

SQL_DESC_UNSIGNED [実装記述子]
この読み取り専用 SQLSMALLINT レコード フィールドは、列の型が符号なしまたは数値以外の場合はSQL_TRUEに設定され、列の型が署名されている場合はSQL_FALSEされます。

SQL_DESC_UPDATABLE [IRD]
この読み取り専用 SQLSMALLINT レコード フィールドは、次のいずれかの値に設定されます。

  • 結果セット列が読み取り専用の場合にSQL_ATTR_READ_ONLYします。

  • 結果セット列が読み取り/書き込みである場合にSQL_ATTR_WRITEします。

  • 結果セット列が更新可能かどうかがわからない場合にSQL_ATTR_READWRITE_UNKNOWNします。

SQL_DESC_UPDATABLEでは、ベース テーブルの列ではなく、結果セット内の列の更新可能性について説明します。 この結果セット列の基になるベース テーブルの列の更新可能性は、このフィールドの値と異なる場合があります。 列が更新可能かどうかは、データ型、ユーザー特権、および結果セット自体の定義に基づいて行うことができます。 列が更新可能かどうかが不明な場合は、SQL_ATTR_READWRITE_UNKNOWN返す必要があります。

整合性チェック

整合性チェックは、アプリケーションが ARD、APD、または IPD の SQL_DESC_DATA_PTR フィールドの値を渡すたびに、ドライバーによって自動的に実行されます。 いずれかのフィールドが他のフィールドと矛盾している場合、 SQLSetDescField は SQLSTATE HY021 (一貫性のない記述子情報) を返します。 詳細については、 SQLSetDescRec の「整合性チェック」を参照してください。

対象 解決方法については、
列のバインド SQLBindCol 関数
パラメーターのバインド SQLBindParameter 関数
記述子フィールドの取得 SQLGetDescField 関数
複数の記述子フィールドの取得 SQLGetDescRec 関数
複数の記述子フィールドの設定 SQLSetDescRec 関数

参照

ODBC ヘッダー ファイル
ODBC API リファレンス