SQLSpecialColumns() - 特別な (行 ID) 列を取得する
SQLSpecialColumns() は、表の固有な行 ID 情報 (主キーまたはユニーク索引) を戻します。情報は、SQL 結果セットとして戻されます。 この結果セットは、 照会で生成される結果セットを処理するのと同じ関数を使用して、取り出すことができます。
SQLSpecialColumns() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | ステートメント・ハンドル。 |
| SQLUSMALLINT | fColType | 入力 | 戻される固有な行 ID のタイプ。以下のタイプのみがサポートされます。
例外: 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 は、以下のいずれかでなければなりません。
|
| SQLUSMALLINT | fNullable | 入力 | 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 列の実際の長さを判別することができます。
将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更されることはありま せん。次の表は、これらの列を示しています。
| 列番号 | 列名 | データ・タイプ | 説明 |
|---|---|---|---|
| 1 | SCOPE | SMALLINT | COLUMN_NAME の名前が同じ行を指すことを保証される期間。
有効な値は、以下のように引数 fScope のものと
同じです。つまり、行 ID の実際の有効範囲です。以下のいずれかの値が含まれています。
|
| 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
は、次の値のみ戻します。
Db2 データベース管理システムは、疑似列をサポートしていません。ODBC アプリケーションは、他の IBM® 以外
のリレーショナル・データベース管理システムのサーバーから、以下の値を受け取ることができます。
|
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 24000 | カーソル状態が無効です。 | カーソルはステートメント・ハンドルでオープンしています。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。) |
| HY014 | これ以上ハンドルがありません。 | Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY097 | 列のタイプが範囲外です。 | 無効な fColType 値が指定されています。 |
| HY098 | スコープのタイプが範囲外です。 | 無効な fScope 値が指定されています。 |
| HY099 | NULL 可能タイプが範囲外です。 | 無効な fNullable 値が指定されています。 |
| HYC00 | ドライバーは使用できません。 | Db2 ODBC は、表名の修飾子として catalog はサポートしていません。 |
例
/* ... */
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");
}
}
/* ... */