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 がバイナリ バッファーへのポインターである場合、アプリケーションは 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のいずれかになります。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLSetDescField がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられた SQLSTATE 値を取得するには、HandleType が SQL_HANDLE_DESC で、Handle of DescriptorHandle を使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLSetDescField によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 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 で定義されたフィールドではなく、実装定義の値ではありません。

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

引数 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 つのフィールドが設定されます。 フィールドを設定できる場合は、この関数を呼び出して、任意の記述子型の任意のフィールドを設定できます。 (このセクションの後半の表を参照してください)。

Note

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 の場合、ブックマーク フィールドを設定します。

Note

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 で設定できるフィールドを次の表に示します。

ヘッダー フィールドの初期化については、次の表で説明します。

ヘッダー フィールド名 Type R/W Default
SQL_DESC_ALLOC_TYPE SQLSMALLINT ARD: R APD: R IRD: R IPD: R ARD: 暗黙的な場合はSQL_DESC_ALLOC_AUTO、明示的にはSQL_DESC_ALLOC_USER

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 (無効な記述子フィールド識別子) が返されます。

レコード フィールドの初期化は、次の表に示すように行われます。

レコード フィールド名 Type 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: Unused[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 に設定されます。 sqlFreeStmt が SQL_RESET_PARAMS オプションを使用して呼び出された場合、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 つ以上のレコードが含まれます。 各レコードは、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_TRUEが含まれます。また、列が照合順序と比較で大文字と小文字が区別されない場合、または非文字型列である場合はSQL_FALSEが含まれます。

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 つが設定されるたびに、もう一方のフィールドも設定する必要があります。 SQL_DESC_CONCISE_TYPEは、 SQLBindCol または SQLBindParameter、または SQLSetDescField の呼び出しによって設定できます。 SQL_DESC_TYPEは、 SQLSetDescField または SQLSetDescRec の呼び出しによって設定できます。

SQL_DESC_CONCISE_TYPEが interval または 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されている場合に、特定の datetime または interval データ型のサブコードが含まれます。 これは、SQL と C の両方のデータ型に当てはまります。 このコードは、"TYPE" または "C_TYPE" に置き換えた "CODE" (datetime 型の場合) または "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 間隔データ型のいずれかである値の場合、このフィールドの長さは、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 値を持つ場合はSQL_NULLABLE、列に NULL 値がない場合はSQL_NO_NULLS、列が NULL 値を受け入れるかどうかがわからない場合はSQL_NULLABLE_UNKNOWNします。 このフィールドは、ベース列ではなく、結果セット列に関連します。

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

SQL_DESC_NUM_PREC_RADIX [すべて]
この SQLINTEGER フィールドには、SQL_DESC_TYPE フィールドのデータ型がおおよその数値データ型である場合、SQL_DESC_PRECISION フィールドにはビット数が含まれているため、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 つが設定されるたびに、もう一方のフィールドも設定する必要があります。 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 to 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 リファレンス