SQLTablePrivileges() - 表の特権を取得する

SQLTablePrivileges() は、表の一覧および各表ごとの関連特権一覧を戻します。情報は、SQL 結果セットとして戻されます。 この結果セットは、照会で生成される結果セットの処理に使用するものと同じ関数を使用して、 取り出すことができます。

SQLTablePrivileges() の ODBC 仕様

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

構文

SQLRETURN SQLTablePrivileges (SQLHSTMT          hstmt,
                              SQLCHAR     FAR   *szCatalogName,
                              SQLSMALLINT       cbCatalogName,
                              SQLCHAR     FAR   *szSchemaName,
                              SQLSMALLINT       cbSchemaName,
                              SQLCHAR     FAR   *szTableName,
                              SQLSMALLINT       cbTableName);

関数の引数

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

表 2. SQLTablePrivileges() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドル。
SQLCHAR * szTableQualifier 入力 3 部構成の表名のカタログ修飾子。 これは、NULL ポインターまたは長さゼロのストリングでなければなりません。
SQLSMALLINT cbTableQualifier 入力 szCatalogName の長さ (バイト)。 これは、0 に設定する必要があります。
SQLCHAR * szSchemaName 入力 スキーマ名で結果セットを修飾するためのパターン値 を入れることができるバッファー。
SQLSMALLINT cbSchemaName 入力 szSchemaName の長さ (バイト)。
SQLCHAR * szTableName 入力 表名によって結果セットを修飾するパターン値 を入れることができるバッファー。
SQLSMALLINT cbTableName 入力 szTableName の長さ (バイト)。

szSchemaName および szTableName 引数は検索パターンを受け入れます。

使用法

結果は、次の表にリストされている列を含む標準結果セットとして戻されます。 この結果セットは、TABLE_CAT、TABLE_SCHEM、TABLE_NAME、および PRIVILEGE の 順序になっています。ある特定の表に複数の特権が関連して いる場合、各特権は別個の行として戻されます。

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

カタログ関数の結果セットの VARCHAR 列は、128 バイトの最大長属性で宣言されて おり、ANSI/ISO SQL 規格 (1992) の制限との整合性があります。Db2® 名は 128 バイトより短いため、アプリケーションでは 常に 128 バイト (加えて、NUL 終止符) を出力バッファーに取っておくように選択できます。あるいは、引数 InfoType を以下のそれぞれの値に 設定して、SQLGetInfo() を呼び出すこともできます。
  • SQL_MAX_CATALOG_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_CAT 列の長さを判別
  • SQL_MAX_SCHEMA_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_SCHEM 列の長さを判別
  • SQL_MAX_TABLE_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_NAME 列の長さを判別
  • SQL_MAX_COLUMN_NAME_LEN -- 接続されたデータベース管理システムがサポートする COLUMN_NAME 列の長さを判別

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

表 3. SQLTablePrivileges() によって戻される列
列番号 列名 データ・タイプ 説明
1 TABLE_CAT VARCHAR(128) これは常に NULL です。
2 TABLE_SCHEM VARCHAR(128) TABLE_NAME を含むスキーマの名前。
3 TABLE_NAME VARCHAR(128) NOT NULL 表の名前。
4 GRANTOR VARCHAR(128) 特権を付与したユーザーの許可 ID。
5 GRANTEE VARCHAR(128) 特権が付与されたユーザーの許可 ID。
6 PRIVILEGE VARCHAR(128) 表特権。これは、以下のストリングのうちの 1 つです。
  • ALTER
  • CONTROL
  • DELETE
  • INDEX
  • INSERT
  • REFERENCES
  • SELECT
  • UPDATE
7 IS_GRANTABLE VARCHAR(3) 被付与者が他のユーザーに特権を付与できるかどうかを示します。

これは、「YES」、「NO」、または NULL のいずれかです。

Db2 ODBC が使用する列名は、X/Open CLI CAE 仕様のスタイルに準拠しています。列タイプ、内容、および順序は、ODBC の SQLProcedures() 結果セット で定義されているものと同じです。

戻りコード

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

診断

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

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

例

以下の例は、SQLTablePrivileges() を使用して、 表の特権の結果セットを生成するアプリケーションを示しています。
図 1. 表の特権を含む結果セットを生成するアプリケーション
/* ... */
SQLRETURN
list_table_privileges(SQLHDBC hdbc, SQLCHAR *schema,
                       SQLCHAR *tablename )
{
    SQLHSTMT        hstmt;
    SQLRETURN       rc;
    struct { SQLINTEGER ind;   /* Length & Indicator variable */
             SQLCHAR  s[129];  /* String variable */
           } grantor, grantee, privilege;
    struct { SQLINTEGER  ind;
             SQLCHAR     s[4];
            }is_grantable;
    SQLCHAR         cur_name[512] = "";  /* Used when printing the */
    SQLCHAR         pre_name[512] = "";  /* Result set */
    /* Allocate a statement handle to reference the result set */
    rc = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
    /* Create table privileges result set */
    rc = SQLTablePrivileges(hstmt, NULL, 0, schema, SQL_NTS,
                             tablename, SQL_NTS);
    rc = SQLBindCol(hstmt, 4, SQL_C_CHAR, (SQLPOINTER) grantor.s, 129,
                    &grantor.ind);
/* Continue Binding, then fetch and display result set */
/* ... */