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。

Comments

IdentifierType 引数がSQL_BEST_ROWIDされると、SQLSpecialColumns はテーブル内の各行を一意に識別する列を返します。 これらの列は、常に select-list 句または WHERE 句で使用できます。 SQLColumns は、テーブルの列に関するさまざまな情報を返すために使用され、各行を一意に識別する列や、行の値がトランザクションによって更新されたときに自動的に更新される列を必ずしも返すわけではありません。 たとえば、 SQLColumns は Oracle 擬似列 ROWID を返さない場合があります。 これが、SQLSpecialColumns を使用してこれらの列を返す理由です。 詳細については、「データ カタログの参照」を参照してください。

テーブル内の各行を一意に識別する列がない場合、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 では、次の列の名前が変更されました。 列名の変更は、アプリケーションが列番号でバインドされるため、下位互換性には影響しません。

COLUMN_NAME列の実際の長さを判断するために、アプリケーションは SQL_MAX_COLUMN_NAME_LEN オプションを使用して SQLGetInfo を呼び出すことができます。

次の表に、結果セットの列を示します。 列 8 (P Standard EditionUDO_COLUMN) を超える追加の列は、ドライバーによって定義できます。 アプリケーションは、明示的な序数位置を指定するのではなく、結果セットの末尾からカウントダウンすることで、ドライバー固有の列にアクセスできるようにする必要があります。 詳細については、「カタログ関数によって返されるデータ」を参照してください。

アプリケーションが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 に関するページを参照してください。

関連する関数

参照

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