仕様: | DB2 CLI 2.1 | ODBC 1.0 |
SQLSpecialColumns() は、表の固有行の識別子情報 (基本キーまたは固有索引) を戻します。情報は SQL 結果セット内に戻されますが、照会により作成された結果セットを処理するのに使用される関数と同じ関数を使用して情報を取り出すことができます。
構文
SQLRETURN SQLSpecialColumns( SQLHSTMT StatementHandle, /* hstmt */ SQLUSMALLINT IdentifierType, /* fColType */ SQLCHAR FAR *CatalogName, /* szCatalogName */ SQLSMALLINT NameLength1, /* cbCatalogName */ SQLCHAR FAR *SchemaName, /* szSchemaName */ SQLSMALLINT NameLength2, /* cbSchemaName */ SQLCHAR FAR *TableName, /* szTableName */ SQLSMALLINT NameLength3, /* cbTableName */ SQLUSMALLINT Scope, /* fScope */ SQLUSMALLINT Nullable); /* fNullable */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 | ||
---|---|---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル | ||
SQLUSMALLINT | IdentifierType | 入力 | 戻される固有行識別子のタイプ。次のタイプのみがサポートされます。
| ||
SQLCHAR * | CatalogName | 入力 | 3 つの部分から成る表名のカタログ修飾子。これは、ヌル・ポインターまたは長さゼロのストリングでなければなりません。 | ||
SQLSMALLINT | NameLength1 | 入力 | CatalogName の長さ。これは、0 に設定する必要があります。 | ||
SQLCHAR * | SchemaName | 入力 | 指定した表のスキーマ修飾子。 | ||
SQLSMALLINT | NameLength2 | 入力 | SchemaName の長さ。 | ||
SQLCHAR * | TableName | 入力 | 表名。 | ||
SQLSMALLINT | NameLength3 | 入力 | NameLength3 の長さ。 | ||
SQLUSMALLINT | 効力範囲 | 入力 | 固有行識別子が有効になる最大所要時間。
Scope は、次のうちの 1 つでなければなりません。
行識別子値が有効であることが保証される期間は、現行のトランザクション分離レベルにより異なります。分離レベルに関連する情報とシナリオについては、IBM DB2 SQL 解説書を参照してください。 | ||
SQLUSMALLINT | Nullable | 入力 | NULL 値を入れることのできる特殊な列を戻すかどうかを判別します。
次のうちの 1 つでなければなりません。
|
使用法
表の任意の行を固有に識別する方法が複数ある場合 (つまり、指定した表に複数の固有な索引がある場合)、 DB2 CLI は内部の基準に基づいて最良 の行識別子列の集まりを戻します。
表の任意の行を固有に識別できる列の集まりがない場合、空の結果セットが戻されます。
固有な行識別子情報が戻される際の結果セットの形式は、行識別子の各列が結果セット内の 1 行で表されるという形式です。 『SQLSpecialColumns で戻される列』 は、SQLSpecialColumns() で戻され、 SCOPE がソートする結果セット内の列の順序を示します。
ほとんどの場合、SQLSpecialColumns() への呼び出しはシステム・カタログに対して複雑で、それゆえに費用のかかる照会へとマップされるので、使用を節約する必要があります。それで、呼び出しを繰り返すよりも、結果を保管しておく方が良いでしょう。
カタログ関数の結果セットの VARCHAR 列は、SQL92 の制限に従うように、 128 の最大長属性で宣言されています。 DB2 名は 128 文字未満なので、アプリケーションは出力バッファー用に 128 文字 (およびヌル終止符) を常にとっておくか、あるいは、接続している DBMS がサポートしている COLUMN_NAME 列の実際の長さを判別するために、 SQL_MAX_COLUMN_NAME_LEN を使用して選択的に SQLGetInfo() を呼び出すようにすることができます。
新規の列が追加され、列の名前が将来のリリースで変更される場合でも、現行の列の位置は変更になりません。
それぞれの値の説明は、表 172 にある Scope を参照してください。
データ、時間、タイム・スタンプ・データ・タイプであれば、これは文字に変換されるときの値を表示するのに必要なバイトの総数です。
数値データ・タイプの場合、これは結果表の NUM_PREC_RADIX 列の値に基づいて、列に許可されている合計桁数または合計ビット数のいずれかです。
表 194 も参照してください。
表 196 も参照してください。
DB2 DBMS は、疑似列をサポートしません。 ODBC アプリケーションは、他の非 IBM RDBMS サーバーから次の値を受け取ることができます。
戻りコード
診断
表 173. SQLSpecialColumns SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
24000 | カーソル状態が無効です。 | カーソルはすでに、ステートメント・ハンドル上にオープンされています。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY008 | 操作が取り消しになりました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
|
HY009 | 引き数値が無効です。 | TableName はヌルです。 |
HY010 | 関数の順序エラーです。 |
実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。 BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。
|
HY014 | もはやハンドルはありません。 | DB2 CLI は、内部資源が原因でハンドルを割り当てることができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 長さ引き数のうちの 1 つの値は 0 より小さい値でしたが、
SQL_NTS と等しくありませんでした。
長さ引き数のうちの 1 つの値は、その修飾子または名前について DBMS でサポートされる最大長を超えています。 |
HY097 | 列タイプが範囲外です。 | 無効な IdentifierType 値を指定しました。 |
HY098 | スコープ・タイプが範囲外です。 | 無効な Scope 値を指定しました。 |
HY099 | Nullable タイプが範囲外です。 | 無効な Nullable 値を指定しました。 |
HYC00 | ドライバーが機能していません。 | DB2 CLI は、表名の修飾子としてカタログ をサポートしません。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
なし。
(ここで完全サンプル tbconstr.c を使用することもできます 。)
/* From the CLI sample tbconstr.c */ /* ... */ /* call SQLSpecialColumns */ printf("\n Call SQLSpecialColumns for the table %s.%s\n", tbSchema, tbName); sqlrc = SQLSpecialColumns(hstmt, SQL_BEST_ROWID, NULL, 0, tbSchema, SQL_NTS, tbName, SQL_NTS, SQL_SCOPE_CURROW, SQL_NULLABLE);
参照