SQLSpecialColumns 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: Open Group
まとめ
SQLSpecialColumns は 、指定されたテーブル内の列に関する次の情報を取得します。
テーブル内の行を一意に識別する列の最適なセット。
行の値がトランザクションによって更新されたときに自動的に更新される列。
構文
SQLRETURN SQLSpecialColumns(
SQLHSTMT StatementHandle,
SQLSMALLINT IdentifierType,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLSMALLINT Scope,
SQLSMALLINT Nullable);
引数
StatementHandle
[入力]ステートメント ハンドル。
IdentifierType
[入力]返される列の型。 次のいずれかの値を指定する必要があります。
SQL_BEST_ROWID: 列または列から値を取得することで、指定したテーブル内の任意の行を一意に識別できるようにする最適な列または列のセットを返します。 列には、この目的のために特別に設計された擬似列 (Oracle ROWID または Ingres TID など) またはテーブルの一意のインデックスの列を指定できます。
SQL_ROWVER: 指定したテーブル内の列 (存在する場合) を返します。この列は、行内の値がトランザクションによって更新されたときにデータ ソースによって自動的に更新されます (SQLBase ROWID または Sybase TIMESTAMP など)。
CatalogName
[入力]テーブルのカタログ名。 ドライバーが一部のテーブルのカタログをサポートしているが、他のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はカタログを持たないテーブルを表します。 CatalogName に文字列検索パターンを含めることはできません。
SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、CatalogName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALStandard Editionの場合、CatalogName は通常の引数であり、文字どおり扱われ、大文字と小文字が区別されます。 詳細については、「カタログ関数の引数」を参照してください。
NameLength1
[入力]*CatalogName の文字数。
Schemaname
[入力]テーブルのスキーマ名。 ドライバーが一部のテーブルのスキーマをサポートしているが、別のテーブルではサポートされていない場合 (ドライバーが異なる DBMS からデータを取得する場合など)、空の文字列 ("") はスキーマを持たないテーブルを示します。 SchemaName に文字列検索パターンを含めることはできません。
SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 SchemaName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALStandard Editionの場合、SchemaName は通常の引数です。リテラルとして扱われ、その大文字と小文字は重要です。
NameLength2
[入力]*SchemaName の文字数。
TableName
[入力]テーブル名。 この引数を null ポインターにすることはできません。 TableName に文字列検索パターンを含めることはできません。
SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 TableName は識別子として扱われ、大文字と小文字は区別されません。 SQL_FALStandard Editionの場合、TableName は通常の引数であり、文字どおり扱われ、大文字と小文字が区別されます。
NameLength3
[入力]*TableName の文字数。
スコープ
[入力]rowid の最低限必要なスコープ。 返される rowid は、より大きなスコープである可能性があります。 次のいずれかである必要があります。
SQL_SCOPE_CURROW: rowid は、その行に配置されている間のみ有効であることが保証されます。 行が別のトランザクションによって更新または削除された場合、rowid を使用して後で再選択しても行が返されない場合があります。
SQL_SCOPE_TRANSACTION: rowid は、現在のトランザクションの期間中有効であることが保証されます。
SQL_SCOPE_Standard Edition SSION: rowid はセッションの間 (トランザクション境界を越えて) 有効であることが保証されます。
NULL 値の使用
[入力]NULL 値を持つ特殊な列を返すかどうかを決定します。 次のいずれかである必要があります。
SQL_NO_NULLS: NULL 値を持つ特殊な列を除外します。 一部のドライバーはSQL_NO_NULLSをサポートできず、SQL_NO_NULLSが指定されている場合、これらのドライバーは空の結果セットを返します。 この場合はアプリケーションを準備し、絶対に必要な場合にのみSQL_NO_NULLSを要求する必要があります。
SQL_NULLABLE: NULL 値を持つ場合でも、特殊な列を返します。
返品
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR、またはSQL_INVALID_HANDLE。
診断
SQLSpecialColumns がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleType と StatementHandle のハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、SQLSpecialColumns によって一般的に返される SQLSTATE 値を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 08S01 | 通信リンクエラー | ドライバーとドライバーが接続されたデータ ソース間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 24000 | カーソル状態が無効 | StatementHandle でカーソルが開き、SQLFetch または SQLFetchScroll が呼び出されました。 このエラーは、SQLFetch または SQLFetchScroll がSQL_NO_DATAを返していない場合にドライバー マネージャーによって返され、SQLFetch または SQLFetchScroll がSQL_NO_DATAを返した場合にドライバーによって返されます。 StatementHandle でカーソルが開かれていましたが、SQLFetch または SQLFetchScroll が呼び出されませんでした。 |
| 40001 | シリアル化エラー | 別のトランザクションでリソースのデッドロックが発生したため、トランザクションがロールバックされました。 |
| 40003 | ステートメントの入力候補が不明です | この関数の実行中に関連付けられた接続が失敗し、トランザクションの状態を特定できません。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージには、エラーとその原因が記述されています。 |
| HY001 | メモリ割り当てエラー | ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。 |
| HY008 | 操作が取り消されました | StatementHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、StatementHandle で SQLCancel または SQLCancelHandle が呼び出されました。 その後、StatementHandle で関数が再度呼び出されました。 関数が呼び出され、実行が完了する前に、SQLCancel または SQLCancelHandle がマルチスレッド アプリケーション内の別のスレッドから StatementHandle で呼び出されました。 |
| HY009 | null ポインターの使用が無効です | TableName 引数は null ポインターでした。 SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定され、 CatalogName 引数が null ポインターであり、SQL_CATALOG_NAME InfoType はカタログ名がサポートされていることを返します。 (DM) SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定され 、SchemaName 引数が null ポインターでした。 |
| HY010 | 関数シーケンス エラー | (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この関数は、SQLSpecialColumns が呼び出されたときにまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 (DM) 非同期実行関数 (この関数ではない) が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEnterprise EditionD_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 |
| HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) 長さ引数の 1 つの値が 0 未満でしたが、SQL_NTSと等しくありません。 長さ引数の 1 つの値が、対応する名前の最大長値を超えました。 各名前の最大長は、InfoType 値 (SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、またはSQL_MAX_TABLE_NAME_LEN) を使用して SQLGetInfo を呼び出すことによって取得できます。 |
| HY097 | 列の種類が範囲外 | (DM) 無効な IdentifierType 値が指定されました。 |
| HY098 | スコープの種類が範囲外 | (DM) 無効な スコープ 値が指定されました。 |
| HY099 | Null 許容型が範囲外 | (DM) 無効な Null 許容 値が指定されました。 |
| HY117 | 不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 | (DM) 中断状態の詳細については、「SQLEndTran 関数」を参照してください。 |
| HYC00 | 省略可能な機能が実装されていません | カタログが指定されており、ドライバーまたはデータ ソースがカタログをサポートしていません。 スキーマが指定されており、ドライバーまたはデータ ソースがスキーマをサポートしていません。 SQL_ATTR_CONCURRENCY属性とSQL_ATTR_CURSOR_TYPE ステートメント属性の現在の設定の組み合わせは、ドライバーまたはデータ ソースではサポートされていませんでした。 SQL_ATTR_UStandard Edition_BOOKMARKS ステートメント属性は SQL_UB_VARIABLE に設定され、SQL_ATTR_CURSOR_TYPE ステートメント属性は、ドライバーがブックマークをサポートしていないカーソルの種類に設定されました。 |
| HYT00 | タイムアウトの期限が切れました | データ ソースが要求された結果セットを返す前に、クエリのタイムアウト期間の有効期限が切れています。 タイムアウト期間は、sqlSetStmtAttr (SQL_ATTR_QUERY_TIMEOUT) によって設定されます。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を使用して設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。 |
| IM017 | 非同期通知モードでポーリングが無効になっている | 通知モデルが使用されるたびに、ポーリングは無効になります。 |
| IM018 | SQLCompleteAsync は、このハンドルに対する前の非同期操作を完了するために呼び出されていません。 | ハンドルに対する前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、 後処理を実行して操作を完了するために、ハンドルで SQLCompleteAsync を呼び出す必要があります。 |
Comments
IdentifierType 引数がSQL_BEST_ROWIDされると、SQLSpecialColumns はテーブル内の各行を一意に識別する列を返します。 これらの列は、常に select-list 句または WHERE 句で使用できます。 SQLColumns は、テーブルの列に関するさまざまな情報を返すために使用され、各行を一意に識別する列や、行の値がトランザクションによって更新されたときに自動的に更新される列を必ずしも返すわけではありません。 たとえば、 SQLColumns は Oracle 擬似列 ROWID を返さない場合があります。 これが、SQLSpecialColumns を使用してこれらの列を返す理由です。 詳細については、「データ カタログの参照」を参照してください。
Note
ODBC カタログ関数の一般的な使用方法、引数、および返されるデータの詳細については、「カタログ関数」を参照してください。
テーブル内の各行を一意に識別する列がない場合、SQLSpecialColumns は行のない行セットを返します。その後、ステートメントで SQLFetch または SQLFetchScroll を呼び出すと、SQL_NO_DATAが返されます。
IdentifierType、Scope、または Null 許容引数がデータ ソースでサポートされていない特性を指定した場合、SQLSpecialColumns は空の結果セットを返します。
SQL_ATTR_METADATA_ID ステートメント属性が SQL_TRUE に設定されている場合、 CatalogName、 SchemaName、および TableName 引数は識別子として扱われるので、特定の状況では null ポインターに設定できません。 (詳細については、 カタログ関数の引数。
SQLSpecialColumns は、SCOPE で並べ替えられた標準の結果セットとして結果を返します。
ODBC 3.x では、次の列の名前が変更されました。 列名の変更は、アプリケーションが列番号でバインドされるため、下位互換性には影響しません。
| ODBC 2.0 列 | ODBC 3.x 列 |
|---|---|
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
COLUMN_NAME列の実際の長さを判断するために、アプリケーションは SQL_MAX_COLUMN_NAME_LEN オプションを使用して SQLGetInfo を呼び出すことができます。
次の表に、結果セットの列を示します。 列 8 (P Standard EditionUDO_COLUMN) を超える追加の列は、ドライバーによって定義できます。 アプリケーションは、明示的な序数位置を指定するのではなく、結果セットの末尾からカウントダウンすることで、ドライバー固有の列にアクセスできるようにする必要があります。 詳細については、「カタログ関数によって返されるデータ」を参照してください。
| 列名 | Column number | データ型 | コメント |
|---|---|---|---|
| SCOPE (ODBC 1.0) | 1 | Smallint | rowid の実際のスコープ。 次のいずれかの値が含まれます。 SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_Standard Edition SSION IdentifierType がSQL_ROWVERされると NULL が返されます。 各値の説明については、このセクションの 「構文」のスコープ の説明を参照してください。 |
| COLUMN_NAME (ODBC 1.0) | 2 | Varchar not NULL | 列名。 ドライバーは、名前のない列の空の文字列を返します。 |
| DATA_TYPE (ODBC 1.0) | 3 | Smallint (NULL 以外) | SQL データ型。 ODBC SQL データ型またはドライバー固有の SQL データ型を指定できます。 有効な ODBC SQL データ型の一覧については、「SQL データ型」を参照してください。 ドライバー固有の SQL データ型の詳細については、ドライバーのドキュメントを参照してください。 |
| TYPE_NAME (ODBC 1.0) | 4 | Varchar not NULL | データ ソースに依存するデータ型名。たとえば、"CHAR"、"VARCHAR"、"MONEY"、"LONG VARBINARY"、または "CHAR ( ) FOR BIT DATA" などです。 |
| COLUMN_SIZE (ODBC 1.0) | 5 | 整数型 | データ ソースの列のサイズ。 列サイズの詳細については、「列サイズ、 10 進数、転送オクテットの長さ、および表示サイズ」を参照してください。 |
| BUFFER_LENGTH (ODBC 1.0) | 6 | 整数型 | SQL_C_DEFAULTが指定されている場合に SQLGetData または SQLFetch 操作で転送されるデータの長さ (バイト単位)。 数値データの場合、このサイズはデータ ソースに格納されているデータのサイズとは異なる場合があります。 この値は、文字データCOLUMN_SIZE列とは異なる場合があります。 詳細については、「列サイズ、 10 進数、転送オクテット長、および表示サイズ」を参照してください。 |
| DECIMAL_DIGITS (ODBC 1.0) | 7 | Smallint | データ ソースの列の 10 進数。 10 進数が適用されないデータ型の場合は NULL が返されます。 10 進数の詳細については、「列サイズ、 10 進数、転送オクテットの長さ、および表示サイズ」を参照してください。 |
| P Standard EditionUDO_COLUMN (ODBC 2.0) | 8 | Smallint | 列が Oracle ROWID などの擬似列であるかどうかを示します。 SQL_PC_UNKNOWN SQL_PC_NOT_PStandard Edition UDO SQL_PC_PStandard Edition UDO 注: 相互運用性を最大限に高める場合、SQLGetInfo によって返される識別子引用符文字を使用して擬似列を引用符で囲む必要はありません。 |
アプリケーションがSQL_BEST_ROWIDの値を取得した後、アプリケーションはこれらの値を使用して、定義されたスコープ内でその行を再選択できます。 Standard Edition LECT ステートメントは、行も 1 行も返さないと保証されます。
アプリケーションが rowid 列または列に基づいて行を再選択し、その行が見つからない場合、アプリケーションは行が削除されたか、rowid 列が変更されたと見なすことができます。 その逆は正しくありません。rowid が変更されていない場合でも、行内の他の列が変更されている可能性があります。
列の種類SQL_BEST_ROWIDに返される列は、結果セット内で前後にスクロールして、一連の行から最新のデータを取得する必要があるアプリケーションに役立ちます。 rowid の列は、その行に配置されている間は変更されないことが保証されます。
rowid の列はメインカーソルが行に配置されていない場合でも有効です。アプリケーションは、結果セット内の SCOPE 列をチェックすることによってこれを判断できます。
列の種類SQL_ROWVERに対して返される列は、rowid を使用して行が再選択されている間に特定の行の列が更新されたかどうかをチェックする必要があるアプリケーションに役立ちます。 たとえば、rowid を使用して行を再選択した後、アプリケーションは、SQL_ROWVER列の前の値を、フェッチした列と比較できます。 SQL_ROWVER列の値が前の値と異なる場合、アプリケーションはディスプレイ上のデータが変更されたことをユーザーに警告できます。
コード例
同様の関数のコード例については、SQLColumns に関するページを参照してください。
関連する関数
| 対象 | 参照トピック |
|---|---|
| 結果セット内の列へのバッファーのバインド | SQLBindCol 関数 |
| ステートメント処理の取り消し | SQLCancel 関数 |
| テーブルまたはテーブル内の列を返す | SQLColumns 関数 |
| 1 つの行またはデータ ブロックを順方向にフェッチする | SQLFetch 関数 |
| データブロックのフェッチまたは結果セットのスクロール | SQLFetchScroll 関数 |
| 主キーの列を返す | SQLPrimaryKeys 関数 |