SQLSpecialColumns() - 特別な (行 ID) 列を取得する

SQLSpecialColumns() は、表の固有な行 ID 情報 (主キーまたはユニーク索引) を戻します。情報は、SQL 結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。

SQLSpecialColumns() の ODBC 仕様

表 1. SQLSpecialColumns() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり なし

構文

SQLRETURN   SQLSpecialColumns(SQLHSTMT          hstmt,
                              SQLUSMALLINT      fColType,
                              SQLCHAR     FAR   *szCatalogName,
                              SQLSMALLINT       cbCatalogName,
                              SQLCHAR     FAR   *szSchemaName,
                              SQLSMALLINT       cbSchemaName,
                              SQLCHAR     FAR   *szTableName,
                              SQLSMALLINT       cbTableName,
                              SQLUSMALLINT      fScope,
                              SQLUSMALLINT      fNullable);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLSpecialColumns() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル。
SQLUSMALLINT fColType 入力 戻される固有な行 ID のタイプ。以下のタイプのみがサポートされます。
  • SQL_BEST_ROWID -- 指定された表のどの行でも、一意的に識別できる最適な列セットを戻します。

例外: ODBC アプリケーションとの互換性を保つために、SQL_ROWVER も 認識されますが、サポートされません。したがって、SQL_ROWVER を指定すると、空の結果が戻されます。

SQLCHAR * szCatalogName 入力 3 部構成の表名のカタログ修飾子。 これは、NULL ポインターまたは長さゼロの ストリングでなければなりません。
SQLSMALLINT cbCatalogName 入力 szCatalogName の長さ (バイト)。 これは、0 に設定する必要があります。
SQLCHAR * szSchemaName 入力 指定した表のスキーマ修飾子。
SQLSMALLINT cbSchemaName 入力 szSchemaName の長さ (バイト)。
SQLCHAR * szTableName 入力 表名。
SQLSMALLINT cbTableName 入力 cbTableName の長さ (バイト)。
SQLUSMALLINT fScope 入力 固有な行 ID が有効状態にあるのに必要な最小限の期間。
fScope は、以下のいずれかでなければなりません。
  • SQL_SCOPE_CURROW: 行 ID は、その行に位置付けられている間のみ、有効であることが 保証されます。後で、同じ行 ID の値を使用して再度選択しても、 他のトランザクションによって行が更新または削除された場合には、行を戻さない場合があります。
  • SQL_SCOPE_TRANSACTION: 行 ID は、現行トランザクションの持続期間のみ、 有効であることが保証されます。 この属性は、SQL_TXN_SERIALIZABLE および SQL_TXN_REPEATABLE_READ 分離属性が 設定されている場合のみ有効です。
  • SQL_SCOPE_SESSION: 行 ID は、接続の持続期間のみ、有効であることが保証されます。

    重要: この属性は、Db2® for z/OS® ではサポートされません。

行 ID の値が有効であることが保証される期間は、現行のトランザクションの 分離レベルにより異なります。
SQLUSMALLINT fNullable 入力 NULL 値を持つことのできる特別な列を戻すかどうかを判別します。
次のいずれかでなければなりません。
  • SQL_NO_NULLS - 戻される行 ID 列セットは、NULL 値を持つことはできません。
  • SQL_NULLABLE - 戻される行 ID 列セットは、NULL 値が許される列を 含むことができます。

使用法

表の任意の行を一意的に識別する方法が複数ある場合 (すなわち、 指定した表が複数のユニーク索引によって索引付けされている場合)、Db2 ODBC は内部基準に 基づいて最良の行 ID 列セットの集合を戻します。

表の任意の行を一意的に識別できる列セットがない場合、空の結果セットが戻されます。

固有な行 ID 情報が戻される結果セットの形式は、行 ID のそれぞれの列が結果セットの 1 行で 表されるという形式です。表 3 は、SQLSpecialColumns() で戻される結果セットの列の順序を 示しており、SCOPE 別にソートされています。

多くの場合、SQLSpecialColumns() への呼び出しは、システム・カタログに対する複雑な (したがって、 コストのかかる) 照会にマップされることになるため、慎重に使用し、呼び出しを繰り返さずに、 結果を保管するようにしてください。

カタログ関数の結果セットの VARCHAR 列は、128 バイトの最大長属性で宣言されて おり、ANSI/ISO SQL 規格 (1992) の制限との整合性があります。Db2 名は 128 バイトより小さいため、 アプリケーションは、出力バッファー用に 常に 128 バイト (加えて、NUL 終止符) を取っておくか、 または別の方法として、SQL_MAX_COLUMN_NAME_LEN を用いて SQLGetInfo() を 呼び出し、接続しているデータベース管理システムでサポートされる COLUMN_NAME 列の実際の長さを判別することができます。

将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更されることはありま せん。次の表は、これらの列を示しています。

表 3. SQLSpecialColumns() によって戻される列
列番号 列名 データ・タイプ 説明
1 SCOPE SMALLINT COLUMN_NAME の名前が同じ行を指すことを保証される期間。 有効な値は、以下のように引数 fScope のものと 同じです。つまり、行 ID の実際の有効範囲です。以下のいずれかの値が含まれています。
  • SQL_SCOPE_CURROW
  • SQL_SCOPE_TRANSACTION
  • SQL_SCOPE_SESSION
それぞれの値の説明について は 表 2 の fScope を参照してください。
2 COLUMN_NAME VARCHAR(128) NOT NULL 表の主キーである (またはその一部である) 列の名前。
3 DATA_TYPE SMALLINT NOT NULL 列の SQL データ・タイプ。
4 TYPE_NAME VARCHAR(128) NOT NULL データベース管理システムの文字ストリングによって表現される、DATA_TYPE 列の値に関連した名前。
5 COLUMN_SIZE INTEGER DATA_TYPE 列の値が文字ストリングまたはバイナリー・ストリングであることを示す場合、 この列にはバイト単位の最大長が入っています。 グラフィック (DBCS) ストリングの場合は、パラメーターの 2 バイト文字の数です。

日付、時刻、タイム・スタンプのデータ・タイプの場合、これは 文字に変換されるときの値を表示するのに必要なバイトの総数です。

数値データ・タイプの場合、これは、結果セットの NUM_PREC_RADIX 列の値によって異なり、 列で可能な桁の総数またはビットの総数のいずれかです。

6 BUFFER_LENGTH INTEGER SQL_C_DEFAULT が SQLBindCol()、 SQLGetData()、および SQLBindParameter() 呼び出しで指定された場合、この列からのデータを保管するための関連する C バッファーの最大バイト数。 この長さには、NUL 終止符は含まれていません。 正確な数値データ・タイプの場合、小数点と符号も長さに数えられます。
7 DECIMAL_DIGITS SMALLINT 列の位取り。位取りが適用できないデータ・タイプの場合は NULL が戻されます。
8 PSEUDO_COLUMN SMALLINT 列が疑似列であるかどうかを示します。 Db2 ODBC は、次の値のみ戻します。
  • SQL_PC_NOT_PSEUDO
Db2 データベース管理システムは、疑似列をサポートしていません。ODBC アプリケーションは、他の IBM® 以外 のリレーショナル・データベース管理システムのサーバーから、以下の値を受け取ることができます。
  • SQL_PC_UNKNOWN
  • SQL_PC_PSEUDO

戻りコード

SQLSpecialColumns() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 4. SQLSpecialColumns() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
24000 カーソル状態が無効です。 カーソルはステートメント・ハンドルでオープンしています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。 この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY014 これ以上ハンドルがありません。 Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。
HY090 ストリングまたはバッファーの長さが無効です。 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
  • 長さ引数のうちの 1 つの値は 0 より小さい値です が、SQL_NTS と等しくありません。
  • 長さ引数のうちの 1 つの値が、その修飾子または名前についてデータベース管理システムが サポートする最大長を超えています。
HY097 列のタイプが範囲外です。 無効な fColType 値が指定されています。
HY098 スコープのタイプが範囲外です。 無効な fScope 値が指定されています。
HY099 NULL 可能タイプが範囲外です。 無効な fNullable 値が指定されています。
HYC00 ドライバーは使用できません。 Db2 ODBC は、表名の修飾子として catalog はサポートしていません。

例

以下の例は、ある表の行を一意的に定義する列のリストを 印刷するアプリケーションを示しています。このアプリケーションは、SQLSpecialColumns() を使用して、このような列を検出します。
図 1. 表のユニーク索引の列セットを印刷するアプリケーション
/* ... */
SQLRETURN
list_index_columns(SQLHDBC hdbc, SQLCHAR *schema, SQLCHAR *tablename )
{
/* ... */
    rc = SQLSpecialColumns(hstmt, SQL_BEST_ROWID, NULL, 0, schema, SQL_NTS,
                    tablename, SQL_NTS, SQL_SCOPE_CURROW, SQL_NULLABLE);
    rc = SQLBindCol(hstmt, 2, SQL_C_CHAR, (SQLPOINTER) column_name.s, 129,
                    &column_name.ind);
    rc = SQLBindCol(hstmt, 4, SQL_C_CHAR, (SQLPOINTER) type_name.s, 129,
                    &type_name.ind);
    rc = SQLBindCol(hstmt, 5, SQL_C_LONG, (SQLPOINTER) & precision,
                    sizeof(precision), &precision_ind);
    rc = SQLBindCol(hstmt, 7, SQL_C_SHORT, (SQLPOINTER) & scale,
                    sizeof(scale), &scale_ind);
    printf("Primary key or unique index for 
    /* Fetch each row, and display */
    while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) {
        printf("   name.s, type_name.s);
        if (precision_ind != SQL_NULL_DATA) {
            printf(" (
        } else {
            printf("(¥n");
        }
        if (scale_ind != SQL_NULL_DATA) {
            printf(", 
        } else {
            printf(")¥n");
        }
    }
/* ... */