CLI の手引きおよび解説書

SQLSpecialColumns - 特殊な (行識別子) 列の入手

目的


仕様: 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 */

関数引き数


表 172. SQLSpecialColumns 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル
SQLUSMALLINT IdentifierType 入力 戻される固有行識別子のタイプ。次のタイプのみがサポートされます。
  • SQL_BEST_ROWID

    指定した表のすべての行を固有に識別できる最適な列の集まりを戻します。

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

SQLCHAR * CatalogName 入力 3 つの部分から成る表名のカタログ修飾子。これは、ヌル・ポインターまたは長さゼロのストリングでなければなりません。
SQLSMALLINT NameLength1 入力 CatalogName の長さ。これは、0 に設定する必要があります。
SQLCHAR * SchemaName 入力 指定した表のスキーマ修飾子。
SQLSMALLINT NameLength2 入力 SchemaName の長さ。
SQLCHAR * TableName 入力 表名。
SQLSMALLINT NameLength3 入力 NameLength3 の長さ。
SQLUSMALLINT 効力範囲 入力 固有行識別子が有効になる最大所要時間。

Scope は、次のうちの 1 つでなければなりません。

  • SQL_SCOPE_CURROW: 行識別子は、その行にある間だけ有効であることが保証されます。同じ行識別子の値を使用して後で再選択をすると、行が更新されていたり他のトランザクションによって削除されていた場合に、行を戻さないことがあります。
  • SQL_SCOPE_TRANSACTION: 行識別子は、現行トランザクションの持続期間だけ有効であることが保証されます。
  • SQL_SCOPE_SESSION: 行識別子は、接続の持続期間だけ有効であることが保証されます。

行識別子値が有効であることが保証される期間は、現行のトランザクション分離レベルにより異なります。分離レベルに関連する情報とシナリオについては、IBM DB2 SQL 解説書を参照してください。

SQLUSMALLINT Nullable 入力 NULL 値を入れることのできる特殊な列を戻すかどうかを判別します。

次のうちの 1 つでなければなりません。

  • SQL_NO_NULLS - 戻される行識別子の列の集まりに、NULL 値を入れることができません。
  • SQL_NULLABLE - 戻される行識別子の列の集まりに、NULL 値を入れられる列を含めることができます。

使用法

表の任意の行を固有に識別する方法が複数ある場合 (つまり、指定した表に複数の固有な索引がある場合)、 DB2 CLI は内部の基準に基づいて最良 の行識別子列の集まりを戻します。

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

固有な行識別子情報が戻される際の結果セットの形式は、行識別子の各列が結果セット内の 1 行で表されるという形式です。 『SQLSpecialColumns で戻される列』 は、SQLSpecialColumns() で戻され、 SCOPE がソートする結果セット内の列の順序を示します。

ほとんどの場合、SQLSpecialColumns() への呼び出しはシステム・カタログに対して複雑で、それゆえに費用のかかる照会へとマップされるので、使用を節約する必要があります。それで、呼び出しを繰り返すよりも、結果を保管しておく方が良いでしょう。

カタログ関数の結果セットの VARCHAR 列は、SQL92 の制限に従うように、 128 の最大長属性で宣言されています。 DB2 名は 128 文字未満なので、アプリケーションは出力バッファー用に 128 文字 (およびヌル終止符) を常にとっておくか、あるいは、接続している DBMS がサポートしている COLUMN_NAME 列の実際の長さを判別するために、 SQL_MAX_COLUMN_NAME_LEN を使用して選択的に SQLGetInfo() を呼び出すようにすることができます。

新規の列が追加され、列の名前が将来のリリースで変更される場合でも、現行の列の位置は変更になりません。

SQLSpecialColumns で戻される列

列 1 SCOPE (SMALLINT)
COLUMN_NAME における名前が、同じ行を指すことが保証されている期間。有効な値は、Scope 引き数のものと同じです (行識別子の実際のスコープ)。次の値のうちの 1 つが含まれています。

それぞれの値の説明は、表 172 にある Scope を参照してください。

列 2 COLUMN_NAME (VARCHAR(128) 非 NULL)
表の基本キーである (またはその一部である) 列の名前。

列 3 DATA_TYPE (SMALLINT 非 NULL)
列 の SQL データ・タイプ。 表 2 にある記号 SQL データ・タイプ列の値の 1 つ。

列 4 TYPE_NAME (VARCHAR(128) 非 NULL)
DATA_TYPE 列の値に関連した名前で表される DBMS 文字ストリング。

列 5 COLUMN_SIZE (INTEGER)
DATA_TYPE 列の値が文字または 2 進ストリングであることを示す場合、この列にはバイトの最大長が含まれます。それがグラフィック (DBCS) ストリングであれば、これはパラメーターの 2 バイト文字の個数です。

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

数値データ・タイプの場合、これは結果表の NUM_PREC_RADIX 列の値に基づいて、列に許可されている合計桁数または合計ビット数のいずれかです。

表 194 も参照してください。

列 6 BUFFER_LENGTH (INTEGER)
SQL_C_DEFAULT が SQLBindCol()、 SQLGetData() および SQLBindParameter() 呼び出しで指定された場合に、この列からのデータを保管するための関連 C バッファーの最大バイト。この長さには、ヌル終止符は含まれていません。正確な数値データ・タイプを出すには、長さとして小数部や符号も考慮されます。

表 196 も参照してください。

列 7 DECIMAL_DIGITS (SMALLINT)
列のスケール。位取りが適用できないデータ・タイプの場合は NULL が戻されます。 表 195 も参照してください。

列 8 PSEUDO_COLUMN (SMALLINT)
列が DB2 コール・レベル・インターフェースだけで戻される疑似列であるかどうかを示します。

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 属性を使用して設定することができます。

制約

なし。

CLI サンプル tbconstr.c

(ここで完全サンプル 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);
 
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]