SQLSpecialColumns 関数

適合 性
導入されたバージョン:ODBC 1.0 標準準拠:オープングループ

Summary
SQLSpecialColumns は、指定されたテーブル内の列に関する以下の情報を取得します:

• テーブル内の行を一意に識別する最適な列の集合。

• トランザクションによって行内の任意の値が更新されると自動的に更新される列です。

構文

  
SQLRETURN SQLSpecialColumns(  
     SQLHSTMT      StatementHandle,  
     SQLSMALLINT   IdentifierType,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     TableName,  
     SQLSMALLINT   NameLength3,  
     SQLSMALLINT   Scope,  
     SQLSMALLINT   Nullable);  

引数

StatementHandle
[入力]ステートメント ハンドル。

識別子タイプ
[入力]返すべき列の種類。 次のいずれかの値を指定する必要があります。

SQL_BEST_ROWID:指定されたテーブル内の任意の行を一意に識別できる最適な列または列の集合を返します。 カラムは、この目的のために特別に設計された擬似カラム(Oracle ROWIDやIngres TIDのように)か、テーブルの任意の一意インデックスのカラムまたはカラムのいずれかであったりします。

SQL_ROWVER:指定されたテーブル内のカラム(もしあれば)を返します。これらは、行内の任意の値がトランザクションによって更新された際にデータソースによって自動的に更新されます(例:SQLBase ROWIDやSybase TIMESTAMP)。

CatalogName
[入力]テーブルのカタログ名。 ドライバが一部のテーブルにはカタログをサポートしているが、他のテーブルではサポートしない場合(例えば異なるDBMSからデータを取得する場合など)、空文字列(「」)はカタログを持たないテーブルを示します。 CatalogNameは 文字列検索パターンを含めません。

SQL_ATTR_METADATA_ID文属性がSQL_TRUEに設定されている場合、 CatalogName は識別子として扱われ、その大文字は重要ではありません。 もしSQL_FALSEであれば、 カタログ名 は通常の引数となります。文字通りに扱われており、そのケースは重要です。 詳細については、「カタログ関数の引数」を参照してください。

NameLength1
[入力]*カタログ名の文字数。

スキーマ名
[入力]テーブルのスキーマ名。 ドライバが一部のテーブルにはスキーマをサポートし、他のテーブルにはサポートしない場合(例えば異なるDBMSからデータを取得する場合など)、空の文字列(「」)はスキーマを持たないテーブルを示します。 SchemaNameは 文字列検索パターンを含めません。

SQL_ATTR_METADATA_ID文属性がSQL_TRUEに設定されている場合、 SchemaName は識別子として扱われ、その大文字は重要ではありません。 もしSQL_FALSEなら、 SchemaName は通常の引数です。文字通りに扱われており、そのケースは重要です。

NameLength2
[入力]*SchemaNameの文字数。

テーブル名
[入力]テーブル名。 この引数はヌルポインタにはなり得ません。 TableNameは 文字列検索パターンを含めません。

SQL_ATTR_METADATA_ID文属性がSQL_TRUEに設定されている場合、 TableName は識別子として扱われ、その大文字は重要ではありません。 SQL_FALSEの場合、 TableName は通常の引数です。文字通りに扱われており、そのケースは重要です。

NameLength3
[入力]*TableNameの文字数。

Scope
[入力]ロウィドの最低限の必要範囲。 返却されたロイドはより広範な範囲を持つ可能性があります。 次のいずれかである必要があります。

SQL_SCOPE_CURROW:ロイドはその列に位置している間のみ有効であることが保証されます。 後でrowidを使って再選択しても、その行が他のトランザクションによって更新または削除された場合、その行が返ってこない場合があります。

SQL_SCOPE_TRANSACTION:ロイドは現在の取引期間中有効であることが保証されます。

SQL_SCOPE_SESSION:ロイドはセッション期間中(トランザクション境界を越えて)有効であることが保証されます。

ヌラブル
[入力]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。

Diagnostics

SQLSpecialColumnsがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、SQLGetDiagRecを呼び出し、HandleTypeをSQL_HANDLE_STMT、HandleをStatementHandleで呼び出すことで関連するSQLSTATE値を取得できます。 以下の表は 、SQLSpecialColumns が一般的に返すSQLSTATEの値と、それぞれをこの関数の文脈で説明しています。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

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

テーブル内の各行を一意に識別する列がなければ、 SQLSpecialColumns は行のない行セットを返します。その後、 SQLFetch または SQLFetchScroll を呼び出して文を返すとSQL_NO_DATA返されます。

IdentifierType、Scope、またはNullableの引数がデータソースでサポートされていない特性を指定している場合、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列(PSEUDO_COLUMN)以降の追加列はドライバーによって定義できます。 アプリケーションは、明示的な順序位置を指定するのではなく、結果セットの末尾からカウントダウンすることでドライバー固有の列にアクセスするべきです。 詳細については、「 カタログ関数によって返されるデータ」を参照してください。

アプリケーションがSQL_BEST_ROWIDの値を取得した後、その値を用いて定義されたスコープ内でその行を再選択できます。 SELECT文は、行が全くないか、1行だけ返すことが保証されています。

もしアプリケーションが行の列を基に行を再選択しても行が見つからない場合、その行が削除されたか、行が変更されたと仮定できます。 逆は正しくありません。たとえロイドが変わっていなくても、その行の他の列は変わっている可能性があります。

列タイプSQL_BEST_ROWIDで返される列は、結果セット内で前後にスクロールして行から最新のデータを取得するアプリケーションに有用です。 ロウイドの列は、その行上に位置している間は変更されないことが保証されています。

行の列は、カーソルが行上に置かれていなくても有効のままである場合があります。アプリケーションは結果セット内のSCOPE列を確認することでこれを判別できます。

列タイプSQL_ROWVERで返される列は、行を行で再選択した際に特定の行の列が更新されたかどうかを確認する必要があるアプリケーションに役立ちます。 例えば、rowidを使って行を再選択した後、アプリケーションはSQL_ROWVER列の前の値と、取得した値を比較できます。 SQL_ROWVER列の値が前の値と異なる場合、アプリケーションは表示上のデータが変更されたことをユーザーに通知できます。

コード例

類似の関数のコード例については 、SQLColumnsを参照してください。

関連関数

関連するコンテンツ

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