155 DBMS_SQLDIAG

DBMS_SQLDIAGパッケージは、SQL診断機能のインタフェースを提供します。

この章のトピックは、次のとおりです:

参照:

診断データの管理の詳細は、『Oracle Database管理者ガイド』を参照してください。

155.1 DBMS_SQLDIAGの概要

ほとんど発生しませんが、SQL文がクリティカル・エラーで失敗した場合は、SQL修復アドバイザを実行して失敗した文を修復できます。

SQL修復アドバイザの概要

SQL修復アドバイザは、重大なエラーが発生してSQL文が失敗した場合に実行します。このアドバイザによって、文が分析され、多くの場合、文を修復するためにパッチの適用が推奨されます。リコメンデーションを実装すると、適用されたSQLパッチによって、問合せオプティマイザで将来実行する場合の代替実行計画が選択され、失敗が回避されます。

SQL修復アドバイザの実行

SQL修復アドバイザを実行するには、CREATE_DIAGNOSIS_TASKを使用して診断タスクを作成し、EXECUTE_DIAGNOSIS_TASKを使用してその診断タスクを実行します。SQL修復アドバイザは、まず重大なエラーを再現し、次にSQLパッチの形式での対処方法の生成を試行します。

  1. 問題が発生したSQL文の特定

    重大なエラーが発生した次のSQL文について考えてみます。

    DELETE FROM t t1 WHERE t1.a = 'a' AND ROWID <> (SELECT MAX(ROWID) FROM t t2 WHERE t1.a= t2.a 
    AND t1.b = t2.b AND t1.d=t2.d)
    

    SQL修復アドバイザを使用して、この重大なエラーを修復します。

  2. 診断タスクの作成

    DBMS_SQLDIAGを呼び出します。CREATE_DIAGNOSIS_TASK。オプションのタスク名、アドバイザ・タスクのオプションの時間制限、および問題のタイプを指定できます。次の例では、SQLテキストを指定し、タスク名をerror_task、問題のタイプをDBMS_SQLDIAG.PROBLEM_TYPE_COMPILATION_ERRORと指定しています。

    DECLARE
        rep_out         CLOB;
        t_id            VARCHAR2(50);
      BEGIN
        t_id := DBMS_SQLDIAG.CREATE_DIAGNOSIS_TASK( 
          sql_text => 'DELETE FROM t t1 WHERE t1.a = ''a'' AND ROWID <> (SELECT MAX(ROWID) FROM t t2 
          WHERE t1.a= t2.a AND t1.b = t2.b AND t1.d=t2.d)',
          task_name => 'error_task',
          problem_type =>DBMS_SQLDIAG.PROBLEM_TYPE_COMPILATION_ERROR);
    
  3. 診断タスクの実行

    SQL修復アドバイザの対処方法生成および分析フェーズを実行するには、CREATE_DIAGNOSIS_TASKで戻されたタスクIDを使用して、DBMS_SQLDIAG.EXECUTE_DIAGNOSIS_TASKをコールします。多少の遅延後に、SQL修復アドバイザに戻ります。SQL修復アドバイザは、その実行の一環として検索結果の記録を残し、この記録には、SQL修復アドバイザのレポート機能を使用してアクセス可能です。

    DBMS_SQLDIAG.EXECUTE_DIAGNOSIS_TASK (t_id);
    
  4. 診断タスクのレポート

    診断タスクの分析には、dbms_sqldiag.report_diagnosis_タスクを使用してアクセスできます。SQL修復アドバイザは、対処方法を検出できた場合、SQLパッチを推奨します。SQLパッチは、SQLプロファイルと類似していますが、SQLプロファイルとは異なり、コンパイル・エラーまたは実行エラーに対処するために使用します。

    rep_out := DBMS_SQLDIAG.REPORT_DIAGNOSIS_TASK (t_id, DBMS_SQLDIAG.TYPE_TEXT);
     
      DBMS_OUTPUT.PUT_LINE ('Report : ' ||  rep_out);
     
      END;
      /
    
  5. パッチの適用

    レポートでパッチが推奨されている場合は、DBMS_SQLDIAG.ACCEPT_SQL_PATCHをコールすることによって、ACCEPT_SQL_PATCHコマンドを実行してパッチを受け入れることができます。このプロシージャは、引数としてtask_nameを使用します。

    EXECUTE DBMS_SQLDIAG.ACCEPT_SQL_PATCH(task_name => 'error_task', task_owner => 'SYS', replace => TRUE);
    
  6. パッチのテスト

    パッチを受け入れたため、SQL文を再実行できます。今回は重大なエラーが発生しなくなります。この文でEXPLAIN PLANを実行すると、計画を生成するためにSQLパッチが使用されたことが表示されます。

    DELETE FROM t t1 WHERE t1.a = 'a' AND ROWID <> (select max(rowid) FROM t t2 WHERE t1.a= t2.a 
    AND t1.b = t2.b AND t1.d=t2.d);
    

SQLパッチの削除

正式なパッチをOracleから取得してエラーを修正した場合、あるいはエラーの修正を含むOracleの次のパッチ・セットまたはパッチ・リリースにアップグレードした場合は、パッチ名を指定してDBMS_SQLDIAG.DROP_SQL_PATCHをコールし、SQLパッチを削除します。パッチ名は、EXPLAIN PLANセクションから取得することも、ビューDBA_SQL_PATCHESを問い合せて取得することもできます。

155.2 DBMS_SQLDIAGのセキュリティ・モデル

DBMS_SQLDIAGパッケージを実行するには、ADVISORロールが必要です。

155.3 DBMS_SQLDIAGの定数

DBMS_SQLDIAGは、パラメータ値の指定時に使用する定数を定義します。

これらの定数を、次の表に示します。

  • 表155-1は、アドバイザのフレームワークに表示されるSQL修復アドバイザの名前について説明しています

  • 表155-2は、SQLDIAGアドバイザのタスク・スコープ・パラメータの値について説明しています。

  • 表155-3は、SQLDIAGアドバイザのtime_limit定数について説明しています。

  • 表155-4は、設定可能なレポートの形式について説明しています

  • 表155-5は、レポートで設定可能な詳細レベルについて説明しています

  • 表155-6は、設定可能なレポート・セクション(カンマ区切り)について説明しています。

  • 表155-7は、「CREATE_DIAGNOSIS_TASKファンクション」problem_typeパラメータに設定可能な値について説明しています。

  • 表155-8は、_sql_findings_modeパラメータに設定可能な値について説明しています。

表155-1 DBMS_SQLDIAGの定数 - SQLDIAGアドバイザの名前

定数 タイプ 説明

ADV_SQL_DIAG_NAME

VARCHAR2(18)

SQL修復アドバイザ

アドバイザのフレームワークに表示されるSQL修復アドバイザの名前

表155-2 DBMS_SQLDIAGの定数: SQLDIAGアドバイザのタスク・スコープ・パラメータの値

定数 タイプ 説明

SCOPE_COMPREHENSIVE

VARCHAR2(13)

COMPREHENSIVE

問題の詳細な分析(実行に時間がかかる場合があります)

SCOPE_LIMITED

VARCHAR2(7)

LIMITED

問題の簡単な分析

表155-3 DBMS_SQLDIAGの定数: SQLDIAGアドバイザのtime_limit定数

定数 タイプ 説明

TIME_LIMIT_DEFAULT

NUMBER

1800

問題の分析に対するデフォルトの時間制限

表155-4 DBMS_SQLDIAGの定数: レポート・タイプ(設定可能な値)の定数

定数 タイプ 説明

TYPE_HTML

VARCHAR2(4)

HTML

REPORT_DIAGNOSIS_TASKファンクションによるレポート(HTML形式)

TYPE_TEXT

VARCHAR2(4)

TEXT

REPORT_DIAGNOSIS_TASKファンクションによるレポート(テキスト形式)

TYPE_XML

VARCHAR2(3)

XML

REPORT_DIAGNOSIS_TASKファンクションによるレポート(XML形式)

表155-5 DBMS_SQLDIAGの定数 - レポート・レベル(設定可能な値)の定数

定数 タイプ 説明

LEVEL_ALL

VARCHAR2(3)

ALL

スキップされた文に関する注釈を含む詳細なレポート。

LEVEL_BASIC

VARCHAR2(5)

BASIC

分析対象の各文に関する情報(実装されていないリコメンデーションなど)を表示します。

LEVEL_TYPICAL

VARCHAR2(7)

TYPICAL

簡単なレポートに、アドバイザによって実行されるアクションに関する情報のみが表示されます。

表155-6 DBMS_SQLDIAGの定数: レポート・セクション(設定可能な値)の定数

定数 タイプ 説明

SECTION_ALL

VARCHAR2(3)

ALL

すべての文

SECTION_ERRORS

VARCHAR2(6)

ERRORS

エラーが発生した文

SECTION_FINDINGS

VARCHAR2(8)

FINDINGS

チューニングの結果

SECTION_INFORMATION

VARCHAR2(11)

INFORMATION

一般的な情報

SECTION_PLANS

VARCHAR2(5)

PLANS

EXPLAIN PLAN

SECTION_SUMMARY

VARCHAR2(7)

SUMMARY

サマリー情報

表155-7 DBMS_SQLDIAGの定数: 問題のタイプの定数

定数 タイプ 説明

PROBLEM_TYPE_PERFORMANCE

NUMBER

1

パフォーマンスに問題があるとユーザーが推定しています。

PROBLEM_TYPE_WRONG_RESULTS

NUMBER

2

問合せの結果に一貫性がないとユーザーが推定しています。

PROBLEM_TYPE_COMPILATION_ERROR

NUMBER

3

コンパイル中にクラッシュしたことをユーザーが確認しました。

PROBLEM_TYPE_EXECUTION_ERROR

NUMBER

4

実行中にクラッシュしたことをユーザーが確認しました。

PROBLEM_TYPE_ALT_PLAN_GEN

NUMBER

5

すべての代替計画を検索するユーザー。

表155-8 DBMS_SQLDIAGの定数: 検索結果のフィルタの定数

定数 タイプ 説明

SQLDIAG_FINDINGS_ALL

NUMBER

1

検索可能なすべての結果を表示します。

SQLDIAG_FINDINGS_VALIDATION

NUMBER

2

構造に対する検証ルールのステータスを表示します。

SQLDIAG_FINDINGS_FEATURES

NUMBER

3

問合せで使用される機能のみを表示します。

SQLDIAG_FINDINGS_FILTER_PLANS

NUMBER

4

アドバイザによって生成された代替計画を表示します。

SQLDIAG_FINDINGS_CR_DIFF

NUMBER

5

2つの計画の差異を表示します。

SQLDIAG_FINDINGS_MASK_VARIANT

NUMBER

6

テスト用のマスク情報。

SQLDIAG_FINDINGS_OBJ_FEATURES

NUMBER

7

機能の使用履歴を表示します。

SQLDIAG_FINDINGS_BASIC_INFO

NUMBER

8

アドバイザによって生成された代替計画を表示します。

155.4 DBMS_SQLDIAGの例

パッチは、パッケージ内のサブプログラムで提供されているステージング表を使用して、あるシステムからエクスポートして別のシステムにインポートできます。SQL診断セットの場合と同様に、ステージング表に挿入する操作は「パック」、ステージング表のデータからパッケージを作成する操作は「アンパック」と呼ばれます。

パッチのパック/アンパック

DBAは、パック/アンパックを次のように実行する必要があります。

  1. CREATE_STGTAB_SQLPATCHをコールして、ユーザー'SH'が所有するステージング表を作成します。

    EXEC DBMS_SQLDIAG.CREATE_STGTAB_SQLPATCH(
        table_name          =>  'STAGING_TABLE',
        schema_name         =>  'SH'); 
    
  2. PACK_STGTAB_SQLPATCHを1回以上コールして、ステージング表にSQLパッチのデータを書き込みます。この場合、現行のスキーマ所有者が所有するステージング表に、DEFAULTカテゴリ内のすべてのSQLパッチのデータをコピーします。

    EXEC DBMS_SQLDIAG.PACK_STGTAB_SQLPATCH(
        staging_table_name  =>  'STAGING_TABLE'); 
    
  3. この場合、現行のスキーマ所有者が所有するステージング表には、1つのSQLパッチSP_FIND_EMPLOYEEのみがコピーされます。

    EXEC DBMS_SQLDIAG.PACK_STGTAB_SQLPATCH(
        patch_name          =>  'SP_FIND_EMPLOYEE',
        staging_table_name  =>  'STAGING_TABLE'); 
    

    これによって、データポンプ、インポート・コマンドとエクスポート・コマンドまたはデータベース・リンクのいずれかを使用して、ステージング表を別のシステムに移動できます。

  4. UNPACK_STGTAB_SQLPATCHをコールして、ステージング表のパッチのデータから、新しいシステムにSQLパッチを作成します。この場合、ステージング表に格納されているSP_FIND_EMPLOYEEパッチのデータ内の名前を'SP_FIND_EMP_PROD'に変更します。

    exec dbms_sqldiag.remap_stgtab_sqlpatch(
       old_patch_name      =>  'SP_FIND_EMPLOYEE',
       new_patch_name      =>  'SP_FIND_EMP_PROD', 

155.5 DBMS_SQLDIAGサブプログラムの要約

この表は、DBMS_SQLDIAGサブプログラムを示し、簡単に説明しています。

表155-9 DBMS_SQLDIAGパッケージのサブプログラム

サブプログラム 説明

ACCEPT_SQL_PATCHファンクションおよびプロシージャ

指定したSQL診断タスクで推奨されているとおりに、推奨されたSQLパッチを受け入れます。

ALTER_SQL_PATCHプロシージャ

既存のSQLパッチ・オブジェクトの特定の属性を変更します。

CANCEL_DIAGNOSIS_TASKプロシージャ

診断タスクを取り消します。

CREATE_DIAGNOSIS_TASKファンクション

このファンクションは、1つのSQL文を診断するために診断タスクを作成します。

CREATE_SQL_PATCHファンクション

SQLテキストにより識別された特定の文に対して、一連のユーザー指定のヒントに基づいてSQLパッチを作成します。

CREATE_STGTAB_SQLPATCHプロシージャ

システム間でのSQLパッチの転送に使用するステージング表を作成します。

DROP_DIAGNOSIS_TASKプロシージャ

診断タスクを削除します。

DROP_SQL_PATCHプロシージャ

データベースから名前付きSQLパッチを削除します。

EXECUTE_DIAGNOSIS_TASKプロシージャ

診断タスクを実行します。

EXPLAIN_SQL_TESTCASEファンクション

SQLテスト・ケースについて記述します。

EXPORT_SQL_TESTCASEプロシージャ

SQLテスト・ケースをディレクトリにエクスポートします。

EXPORT_SQL_TESTCASE_DIR_BY_INCファンクション

引数として渡されるインシデントIDに対応するSQLテスト・ケースを生成します。

EXPORT_SQL_TESTCASE_DIR_BY_TXTファンクション

引数として渡されるSQLに対応するSQLテスト・ケースを生成します。

GET_FIX_CONTROLファンクション

指定したバグ番号に対する修正制御の値を戻します。

GET_SQLファンクション

SQLテスト・ケースをインポートします。

IMPORT_SQL_TESTCASEプロシージャ

SQLテスト・ケースをスキーマにインポートします。

INCIDENTID_2_SQLプロシージャ

インシデントIDのsql_setrowを初期化します。

INTERRUPT_DIAGNOSIS_TASKプロシージャ

診断タスクを中断します。

LOAD_SQLSET_FROM_TCBファンクション

テスト・ケース・ビルダー(TCB)・ファイルからSQLSETをロードします。

PACK_STGTAB_SQLPATCHプロシージャ

CREATE_STGTAB_SQLPATCHプロシージャによって作成されたステージング表へのSQLパッチ。

REPLAY_SQL_TESTCASEプロシージャ

診断タスクをレポートします。

REPORT_DIAGNOSIS_TASKファンクション

診断タスクをレポートします。

RESET_DIAGNOSIS_TASKプロシージャ

診断タスクをリセットします。

RESUME_DIAGNOSIS_TASKプロシージャ

診断タスクを再開します。

SET_DIAGNOSIS_TASK_PARAMETERプロシージャ

診断タスク・パラメータを設定します。

UNPACK_STGTAB_SQLPATCHプロシージャ

PACK_STGTAB_SQLPATCHプロシージャをコールして移入されたステージング表からアンパックし、ステージング表に格納されているパッチのデータを使用して、システムにパッチを作成します。

155.5.1 ACCEPT_SQL_PATCHファンクションおよびプロシージャ

このプロシージャは、指定したSQL診断タスクで推奨されているとおりに、推奨されたSQLパッチを受け入れます。

構文

DBMS_SQLDIAG.ACCEPT_SQL_PATCH (
   task_name      IN  VARCHAR2,
   object_id      IN  NUMBER := NULL,
   name           IN  VARCHAR2 := NULL,
   description    IN  VARCHAR2 := NULL,
   category       IN  VARCHAR2 := NULL,
   task_owner     IN  VARCHAR2 := NULL,
   replace        IN  BOOLEAN := FALSE,
   force_match    IN  BOOLEAN := FALSE)
 RETURN VARCHAR2;
DBMS_SQLDIAG.ACCEPT_SQL_PATCH (
   task_name      IN  VARCHAR2,
   object_id      IN  NUMBER := NULL,
   name           IN  VARCHAR2 := NULL,
   description    IN  VARCHAR2 := NULL,
   category       IN  VARCHAR2 := NULL,
   task_owner     IN  VARCHAR2 := NULL,
   replace        IN  BOOLEAN := FALSE,
   force_match    IN  BOOLEAN := FALSE);

パラメータ

表155-10 ACCEPT_SQL_PATCHファンクションおよびプロシージャのパラメータ

パラメータ 説明

taskname

SQL診断タスクの名前。

object_id

診断タスクに関連付けられているSQL文を示すアドバイザ・フレームワーク・オブジェクトの識別子。

name

パッチの名前。二重引用符を含むことはできません。この名前は大文字と小文字を区別します。指定しない場合は、システムによってSQLパッチに一意の名前が生成されます。

description

SQLパッチの目的を記述したユーザー指定の文字列。記述の最大サイズは500です。

category

カテゴリ名であり、このパッチを使用するセッションに対するセッションのSQLDIAGNOSE_CATEGORYパラメータの値と一致する必要があります。デフォルトの値はDEFAULTになります。この値は、SQLDIAGNOSE_CATEGORYパラメータのデフォルトでもあります。カテゴリには、有効なOracle識別子を指定してください。指定したカテゴリ名は、常に大文字に変換されます。正規化されたSQLテキストとカテゴリ名の組合せによって、パッチの一意のキーが作成されます。この組合せが重複した場合、受入れは失敗します。

task_owner

診断タスクの所有者。これはオプションのパラメータで、他のユーザーが所有する診断タスクに関連付けられているSQLパッチを受け入れるためには指定する必要があります。現行のユーザーがデフォルト値です。

replace

パッチがすでに存在する場合にこの引数をTRUEにすると、そのパッチは置き換えられます。TRUEに設定した置換の場合でも、別のシグネチャ/カテゴリの組合せで使用されている名前を渡すとエラーが発生します。

force_match

TRUEに設定すると、すべてのリテラル値をバインド変数に正規化した後に同じテキストが含まれているSQL文がSQLパッチの対象になります。(SQL文でリテラル値とバインド変数の組合せが使用されている場合、バインド変換は行われません。)これは、CURSOR_SHARINGパラメータのFORCEオプションで使用される一致アルゴリズムと似ています。FALSEに設定すると、リテラルは変換されません。これは、CURSOR_SHARINGパラメータのEXACTオプションで使用される一致アルゴリズムと似ています。

戻り値

SQLパッチの名前。

使用上の注意

CREATE ANY SQL PROFILE権限が必要です。

155.5.2 ALTER_SQL_PATCHプロシージャ

このプロシージャは、既存のSQLパッチ・オブジェクトの特定の属性を変更します。

構文

DBMS_SQLDIAG.ALTER_SQL_PATCH (
   name            IN  VARCHAR2,
   attribute_name  IN  VARCHAR2,
   value           IN  VARCHAR2);

パラメータ

表155-11 ALTER_SQL_PATCHプロシージャのパラメータ

パラメータ 説明

name

変更するSQLパッチの名前。

attribute_name

変更するSQLパッチの名前。有効な値は、次のとおりです。

  • STATUS: ENABLEDまたはDISABLEDに設定できます。

  • NAME: 有効な名前にリセットできます(この名前は、有効なOracle識別子であり一意である必要があります)。

  • DESCRIPTION: 500以下の文字列に設定できます。

  • CATEGORY: 有効なカテゴリ名にリセットできます(この名前は有効なOracle識別子であり、正規化されたSQLテキストと組み合せた場合は一意である必要があります)。

このパラメータは必須で、大/小文字が区別されます。

value

属性の新しい値。有効な属性値については、attribute_nameを参照してください。このパラメータは必須です。

使用上の注意

ALTER ANY SQL PATCH権限が必要です。

155.5.3 CANCEL_DIAGNOSIS_TASKプロシージャ

このプロシージャは、診断タスクを取り消します。

構文

DBMS_SQLDIAG.CANCEL_DIAGNOSIS_TASK (
    taskname        IN   VARCHAR2); 

パラメータ

表155-12 CANCEL_DIAGNOSIS_TASKプロシージャのパラメータ

パラメータ 説明

taskname

タスクの名前

155.5.4 CREATE_DIAGNOSIS_TASKファンクション

このファンクションは、1つのSQL文を診断するために診断タスクを作成します。これは、SQL診断タスクの一意の名前を戻します。

構文

テキストを指定して、単一の文の診断を準備します。

DBMS_SQLDIAG.CREATE_DIAGNOSIS_TASK (
    sql_text           IN   CLOB,
    bind_list          IN   sql_binds := NULL,
    user_name          IN   VARCHAR2  := NULL,
    scope              IN   VARCHAR2  := SCOPE_COMPREHENSIVE,
    time_limit         IN   NUMBER    := TIME_LIMIT_DEFAULT,
    task_name          IN   VARCHAR2  := NULL,
    description        IN   VARCHAR2  := NULL,
    problem_type       IN   NUMBER    := PROBLEM_TYPE_PERFORMANCE)
  RETURN VARCHAR2;

識別子を指定して、カーソル・キャッシュ内の単一の文の診断を準備します。

DBMS_SQLDIAG.CREATE_DIAGNOSIS_TASK (
    sql_id             IN   VARCHAR2,
    plan_hash_value    IN   NUMBER    := NULL,
    scope              IN   VARCHAR2  := SCOPE_COMPREHENSIVE,
    time_limit         IN   NUMBER    := TIME_LIMIT_DEFAULT,
    task_name          IN   VARCHAR2  := NULL,
    description        IN   VARCHAR2  := NULL,
    problem_type       IN   NUMBER    := PROBLEM_TYPE_PERFORMANCE)
  RETURN VARCHAR2;

sqlsetの診断を準備します。

DBMS_SQLDIAG.CREATE_DIAGNOSIS_TASK (
    sqlset_name       IN VARCHAR2,
    basic_filter      IN VARCHAR2 :=  NULL,
    object_filter     IN VARCHAR2 :=  NULL,
    rank1             IN VARCHAR2 :=  NULL,
    rank2             IN VARCHAR2 :=  NULL,
    rank3             IN VARCHAR2 :=  NULL,
    result_percentage IN NUMBER   :=  NULL,
    result_limit      IN NUMBER   :=  NULL,
    scope             IN VARCHAR2 :=  SCOPE_COMPREHENSIVE,
    time_limit        IN NUMBER   :=  TIME_LIMIT_DEFAULT,
    task_name         IN VARCHAR2 :=  NULL,
    description       IN VARCHAR2 :=  NULL,
    plan_filter       IN VARCHAR2 :=  'MAX_ELAPSED_TIME',
    sqlset_owner      IN VARCHAR2 :=  NULL,
    problem_type      IN NUMBER   :=  PROBLEM_TYPE_PERFORMANCE)  RETURN VARCHAR2;

パラメータ

表155-13 CREATE_DIAGNOSIS_TASKファンクションのパラメータ

パラメータ 説明

sql_text

SQL文のテキスト。

bind_list

バインド値のセット。

user_name

診断対象の文またはsqlsetがあるユーザーの名前。

scope

診断スコープ(制限付き/包括的)。

time_limit

診断セッションの最大継続時間(秒)。

task_name

診断タスク名(オプション)。

description

最大256文字のSQL診断セッションの記述。

problem_type

タスクの目標を決定します。使用可能な値は次のとおりです。

  • PROBLEM_TYPE_WRONG_RESULTS

  • PROBLEM_TYPE_COMPILATION_ERROR

  • PROBLEM_TYPE_EXECUTION_ERROR

sql_id

文の識別子。

plan_hash_value

SQL実行計画のハッシュ値。

sqlset_name

sqlset名

basic_filter

SQLチューニング・セット(STS)からSQLをフィルタするためのSQL述語。

object_filter

オブジェクト・フィルタ

rank(i)

選択したSQLのorder-by句。

result_percentage

ランキング・メジャーの合計のパーセント。

result_limit

フィルタ処理またはランク付けが済んでいるSQLの先頭から数件取得されるSQL文。

plan_filter

計画フィルタ。計画(plan_hash_value)が複数ある場合に適用できます。このフィルタには、1つの計画(plan_hash_value)のみを選択できます。使用可能な値は次のとおりです。

  • LAST_GENERATED: タイムスタンプが最も新しい計画。

  • FIRST_GENERATED: LAST_GENERATEDの反対です。

  • LAST_LOADED: first_load_time統計情報が最も新しい計画。

  • FIRST_LOADED: LAST_LOADEDの反対です。

  • MAX_ELAPSED_TIME: 経過時間が最も長い計画。

  • MAX_BUFFER_GETS: バッファ取得回数が最も多い計画。

  • MAX_DISK_READS: ディスク読取り回数が最も多い計画。

  • MAX_DIRECT_WRITES: 直接書込み回数が最も多い計画。

  • MAX_OPTIMIZER_COST: オプティマイザ・コストが最も大きい計画。

sqlset_owner

sqlsetの所有者。現行のスキーマ所有者の場合はNULL。

155.5.5 CREATE_SQL_PATCHファンクション

このファンクションは、SQLテキストにより識別された特定の文に対して、一連のユーザー指定のヒントに基づいてSQLパッチを作成します。

SQLパッチは、通常、SQL文のコンパイル中または実行中のエラーを回避するためにSQL修復アドバイザによって自動的に作成されます。このファンクションは、エラーを解決する一連のヒントに基づいてSQLパッチを手動で作成する方法を提供します。

構文

DBMS_SQLDIAG.CREATE_SQL_PATCH (
    sql_text        IN   CLOB,
    hint_text       IN   CLOB,
    name            IN   VARCHAR2   := NULL,
    description     IN   VARCHAR2   := NULL,
    category        IN   VARCHAR2   := NULL,
    validate        IN   BOOLEAN    := TRUE)
RETURN VARCHAR2; 
DBMS_SQLDIAG.CREATE_SQL_PATCH (
    sql_id          IN   VARCHAR2,
    hint_text       IN   CLOB,
    name            IN   VARCHAR2   := NULL,
    description     IN   VARCHAR2   := NULL,
    category        IN   VARCHAR2   := NULL,
    validate        IN   BOOLEAN    := TRUE)
RETURN VARCHAR2; 

パラメータ

表155-14 CREATE_SQL_PATCHファンクションのパラメータ

パラメータ 説明

sql_text

SQL文のテキスト

sql_id

SQL文のSQL識別子

hint_text

SQLパッチに含めるヒント

name

SQLパッチ名(オプション)

description

SQLパッチの説明

category

カテゴリ名

validate

提供されたヒントを検証するかどうか

戻り値

両方のファンクションがSQLパッチ名を戻します。

155.5.6 CREATE_STGTAB_SQLPATCHプロシージャ

このプロシージャは、システム間でのSQLパッチの転送に使用するステージング表を作成します。

構文

DBMS_SQLDIAG.CREATE_STGTAB_SQLPATCH (
   table_name       IN  VARCHAR2,
   schema_name      IN  VARCHAR2 := NULL,
   tablespace_name  IN  VARCHAR2 := NULL);

パラメータ

表155-15 CREATE_STGTAB_SQLPATCHプロシージャのパラメータ

パラメータ 説明

table_name

(必須)作成する表の名前(大/小文字区別)。

schema_name

作成する表を格納するスキーマ(大/小文字区別)。現行のスキーマの場合はNULL

tablespace_name

ステージング表を格納する表領域(大/小文字区別)。現行のユーザーのデフォルト表領域の場合はNULL

155.5.7 DROP_DIAGNOSIS_TASKプロシージャ

このプロシージャは、診断タスクを削除します。

構文

DBMS_SQLDIAG.DROP_DIAGNOSIS_TASK (
    taskname        IN   VARCHAR2); 

パラメータ

表155-16 DROP_DIAGNOSIS_TASKプロシージャのパラメータ

パラメータ 説明

taskname

タスクの名前

155.5.8 DROP_SQL_PATCHプロシージャ

このプロシージャは、データベースから名前付きSQLパッチを削除します。

構文

DBMS_SQLDIAG.DROP_SQL_PATCH (
   name     IN  VARCHAR2,   ignore   IN  BOOLEAN := FALSE);

パラメータ

表155-17 DROP_SQL_PATCHファンクションのパラメータ

パラメータ 説明

name

削除するパッチの名前。この名前は大文字と小文字を区別します。

ignore

オブジェクトが存在しないために起こるエラーは無視されます。

使用上の注意

DROP ANY SQL PATCH権限が必要です。

155.5.9 EXECUTE_DIAGNOSIS_TASKプロシージャ

このプロシージャは、診断タスクを実行します。

構文

DBMS_SQLDIAG.EXECUTE_DIAGNOSIS_TASK (
    taskname        IN   VARCHAR2); 

パラメータ

表155-18 EXECUTE_DIAGNOSIS_TASKプロシージャのパラメータ

パラメータ 説明

taskname

タスクの名前

155.5.10 EXPLAIN_SQL_TESTCASEファンクション

このプロシージャは、SQLテスト・ケースについて記述します。

構文

DBMS_SQLDIAG.EXPLAIN_SQL_TESTCASE (
    sqlTestCase        IN   CLOB)
  RETURN CLOB; 

パラメータ

表155-19 EXPLAIN_SQL_TESTCASEファンクションのパラメータ

パラメータ 説明

sqlTestCase

SQLテスト・ケースについて記述したXML文書。

155.5.11 EXPORT_SQL_TESTCASEプロシージャ

このプロシージャは、SQLテスト・ケースをディレクトリにエクスポートします。

構文

この変数は、SQL情報とともに指定する必要があります。

DBMS_SQLDIAG.EXPORT_SQL_TESTCASE (
    directory                IN              VARCHAR2,
    sql_text                 IN              CLOB,
    user_name                IN              VARCHAR2  :=  NULL,
    bind_list                IN              sql_binds :=  NULL,
    exportEnvironment        IN              BOOLEAN   :=  TRUE,
    exportMetadata           IN              BOOLEAN   :=  TRUE,
    exportData               IN              BOOLEAN   :=  FALSE,
    exportPkgbody            IN              BOOLEAN   :=  FALSE,
    samplingPercent          IN              NUMBER    :=  100,
    ctrlOptions              IN              VARCHAR2  :=  NULL,
    timeLimit                IN              NUMBER    :=  0,
    testcase_name            IN              VARCHAR2  :=  NULL,
    testcase                 IN OUT NOCOPY   CLOB,
    preserveSchemaMapping    IN              BOOLEAN   :=  FALSE,
    version                  IN              VARCHAR2  :=  'COMPATIBLE'); 

この変数は、インシデント・ファイルからSQL情報を抽出します。

DBMS_SQLDIAG.EXPORT_SQL_TESTCASE (
    directory                IN              VARCHAR2,
    incident_id              IN              VARCHAR2,
    exportEnvironment        IN              BOOLEAN   :=  TRUE,
    exportMetadata           IN              BOOLEAN   :=  TRUE,
    exportData               IN              BOOLEAN   :=  FALSE,
    exportPkgbody            IN              BOOLEAN   :=  FALSE,
    samplingPercent          IN              NUMBER    :=  100,
    ctrlOptions              IN              VARCHAR2  :=  NULL,
    timeLimit                IN              NUMBER    :=  
                                                DBMS_SQLDIAG.TIME_LIMIT_DEFAULT,
    testcase_name            IN              VARCHAR2  :=  NULL,
    testcase                 IN OUT NOCOPY   CLOB,
    preserveSchemaMapping    IN              BOOLEAN   :=  FALSE)
    version                  IN              VARCHAR2  :=  'COMPATIBLE'); 

この変数を使用すると、カーソル・キャッシュに存在するカーソルからSQLテスト・ケースを生成できます。SQL識別子およびSQLハッシュ値を取得するには、V$SQLを使用します。

DBMS_SQLDIAG.EXPORT_SQL_TESTCASE (
    directory                IN              VARCHAR2,
    sql_id                   IN              VARCHAR2,
    plan_hash_value          IN              NUMBER    := NULL,
    exportEnvironment        IN              BOOLEAN   :=  TRUE,
    exportMetadata           IN              BOOLEAN   :=  TRUE,
    exportData               IN              BOOLEAN   :=  FALSE,
    exportPkgbody            IN              BOOLEAN   :=  FALSE,
    samplingPercent          IN              NUMBER    :=  100,
    ctrlOptions              IN              VARCHAR2  :=  NULL,
    timeLimit                IN              NUMBER    := 
                                                DBMS_SQLDIAG.TIME_LIMIT_DEFAULT,
    testcase_name            IN              VARCHAR2  :=  NULL,
    testcase                 IN OUT NOCOPY   CLOB,
    preserveSchemaMapping    IN              BOOLEAN   :=  FALSE)
    version                  IN              VARCHAR2  :=  'COMPATIBLE'); 

パラメータ

表155-20 EXPORT_SQL_TESTCASEプロシージャのパラメータ

パラメータ 説明

directory

生成された様々なファイルを保存するディレクトリ。

sql_text

エクスポートするSQL文のテキスト。

incident_id

違反SQLが含まれているインシデントID。

sql_id

カーソル・キャッシュ内の文の識別子。

username

SQLの解析に使用されるユーザー・スキーマの名前。デフォルトはSYSです。

bind_list

文に関連付けられているバインド値のリスト。

exportEnvironment

コンパイル環境をエクスポートする必要がある場合は、TRUEを指定します。

exportMetadata

SQLで参照されているオブジェクトの定義をエクスポートする必要がある場合は、TRUEを指定します。

exportData

SQLで参照されているオブジェクトのデータをエクスポートする必要がある場合は、TRUEを指定します。

exportPkgbody

SQLで参照されているパッケージの本体をエクスポートする場合は、TRUEを指定します。

samplingPercent

TRUEの場合は、ダンプ・ファイルの作成に使用するサンプリングのパーセントを指定します。

ctrlOptions

不透明な制御パラメータ。たとえば、3回実行するには、文字列'<parameter name="mexec_count">3</parameter>'ctrlOptionsを設定します。

  • name="capture" - BASIC (デフォルト)またはWITH_RUNTIME_INFOです。このパラメータでTCB取得のモードを定義します。

    BASIC: Oracleリリース11gのTCBとして実行され、そのリリースで取得したすべての情報の他、AWRレポート、SQL監視レポートおよびパラメータ情報が取得されます。

    WITH_RUNTIME_INFO: BASICモード下で取得された情報とともに、動的サンプリング・データ、バインドのリスト、動的計画の情報など、SQLのランタイム情報がTCBで取得されます。

    これは、「IMPORT_SQL_TESTCASEプロシージャ」で使用される値と同じである必要があります。

  • name="mexec_count" - 値はすべて正の数(N)です。このパラメータにより、TCBで文をN回実行し、各実行の終了時にランタイム情報を取得するように命令します。

  • name="stat_history_since" - 値は日付です。このパラメータを使用してオブジェクトの統計履歴がエクスポートされます。指定された日付から統計履歴がエクスポートされます。

timeLimit

SQLテスト・ケースのエクスポートにかける時間。

testcaseName

SQLテスト・ケースの名前(オプション)。この名前は、生成されたすべてのスクリプトの接頭辞に使用されます。

testcase

結果として得られるテスト・ケース。

preserveSchemaMapping

スキーマ(単数または複数)が元の環境からテスト環境に再マップされない場合は、TRUEを指定します。

version

抽出されるデータベース・オブジェクトのバージョン。このオプションは、EXPORTでのみ有効です。このバージョンと互換性のないデータベース・オブジェクトまたは属性は抽出されません。

  • COMPATIBLE : (デフォルト)データベース互換性レベルおよび機能の互換性リリース・レベルに対応するメタデータのバージョン(V$COMPATIBILITYビューで表示されます)。データベース互換性は9.2以上に設定する必要があります。

  • LATEST: 現在のデータベース・バージョンを指定するメタデータのバージョン。

  • 特定のデータベース・バージョン。たとえば、'10.0.0'の場合、Oracle Databaseリリース10.0.0未満にはできません。

使用上の注意

  • SQLテスト・ケースは、別のマシンでSQLの失敗を再現するために必要なファイルのセットを生成します。次のものが含まれます。

    • スキーマ・オブジェクトおよび統計情報を含むダンプ・ファイル(.dmp)

    • 文のEXPLAIN PLAN(拡張モード)

    • 問題となる文で収集した診断情報

    • オブジェクトを再ロードするために実行する重要なスクリプト

    • ソースのシステム統計情報をリプレイするSQLスクリプト

    • SQLテスト・ケースについて記述したコンテンツ・ファイルの表

    • メタデータ(xxxxmain.xml)

    • TCBの使用方法を説明するREADME.txtファイル

    • 文(ol.xml)で使用されるアウトライン

    • エクスポートするdb/env(prmimp.sql)内のパラメータ・セットのリスト

    • SQL監視レポート(smrpt.html)(存在する場合)

    • AWRレポート(awrrpt.html)(存在する場合)

    • 当該の文で使用されるバインドのリスト(bndlst.xml)

  • ユーザーSYSでテスト・ケース・ビルダー(TCB)を実行することはできません。かわりに、DBAロールを付与できる別のユーザーを使用してください。

  • TCBのデフォルト設定では、データはエクスポートされません。ただし、最適ではない結果を診断するためなどにデータが必要な場合があります。データをエクスポートするには、exportData=>TRUEに設定してEXPORT_SQL_TESTCASEをコールします(importData=>FALSEOFFに設定しないかぎり、データはデフォルトでインポートされます)。

  • TCBはデフォルトでPL/SQLパッケージ仕様部を含みますが、PL/SQLパッケージ本体は含みません。しかし、PL/SQLファンクションを起動するため、またはパッケージでVirtual Private Database(VPD)機能が定義されているためパッケージ本体が必要になる場合もあります。PL/SQLパッケージ本体をエクスポートするには、exportPkgbody=>TRUEに設定して、EXPORT_SQL_TESTCASEをコールします。PL/SQLパッケージ本体をインポートするには、importPkgbody=>TRUEに設定して、IMPORT_SQL_TESTCASEプロシージャをコールします。

  • オブジェクトの統計履歴をエクスポートするには、データベース互換性を12.0以上に設定する必要があります。

  • このプロシージャでは、グローバル一時表(GTT)のデータおよび統計はエクスポートされません。

<parameters>親タグを使用するか、またはその親タグを使用しないでカプセル化されたctrlOptionsで、ユーザーは複数のパラメータを指定できます。

<parameters>タグを使用する場合

<parameters>
<parameter name="capture">with_runtime_info</parameter>
<parameter name="mexec_count">1</parameter>
</parameters>

<parameters>タグを使用しない場合

<parameter name="capture">with_runtime_info</parameter>
<parameter name="mexec_count">1</parameter>'

155.5.12 EXPORT_SQL_TESTCASE_DIR_BY_INCファンクション

このファンクションは、引数として渡されるインシデントIDに対応するSQLテスト・ケースを生成します。引数として渡されるディレクトリ内に、スクリプトおよびダンプ・ファイルのセットを作成します。

構文

DBMS_SQLDIAG.EXPORT_SQL_TESTCASE_DIR_BY_INC (
    incident_id        IN   NUMBER,
    directory          IN   VARCHAR2,
    exportEnvironment  IN   VARCHAR2 := 'TRUE',
    exportMetadata     IN   VARCHAR2 := 'TRUE',
    exportData         IN   VARCHAR2 := 'FALSE',
    samplingPercent    IN   VARCHAR2 := '100', 
    ctrlOptions        IN   VARCHAR2 := NULL
    version            IN   VARCHAR2 := 'COMPATIBLE')
 RETURN BOOLEAN;

パラメータ

表155-21 EXPORT_SQL_TESTCASE_DIR_BY_INCファンクションのパラメータ

パラメータ 説明

incident_id

違反SQLが含まれているインシデントID。インシデントの詳細は、『Oracle Databaseパフォーマンス・チューニング・ガイド』を参照してください。

directory

生成されたファイルのディレクトリ・パス

exportEnvironment

コンパイル環境をエクスポートする必要がある場合は、TRUEを指定します。

exportMetadata

SQLで参照されているオブジェクトの定義をエクスポートする必要がある場合は、TRUEを指定します。

exportData

SQLで参照されているオブジェクトのデータをエクスポートする必要がある場合は、TRUEを指定します。

samplingPercent

TRUEの場合は、ダンプ・ファイルの作成に使用するサンプリングのパーセントを指定します。

ctrlOptions

不透明な制御パラメータ。たとえば、3回実行するには、文字列'<parameter name="mexec_count">3</parameter>'ctrlOptionsを設定します。

  • capture - BASIC(デフォルト)またはWITH_RUNTIME_INFOです。このパラメータでTCB取得のモードを定義します。

    BASIC: Oracleリリース11gのTCBとして実行され、そのリリースで取得したすべての情報の他、AWRレポート、SQL監視レポートおよびパラメータ情報が取得されます。

    WITH_RUNTIME_INFO: BASICモード下で取得された情報とともに、動的サンプリング・データ、バインドのリスト、動的計画の情報など、SQLのランタイム情報がTCBで取得されます。

  • name=mexec_count - 値はすべて正の数(N)です。このパラメータにより、TCBで文をN回実行し、各実行の終了時にランタイム情報を取得するように命令します。

  • name=stat_history_since - 値は日付です。このパラメータを使用してオブジェクトの統計履歴がエクスポートされます。指定された日付から統計履歴がエクスポートされます。

version

抽出されるデータベース・オブジェクトのバージョン。このオプションは、EXPORTでのみ有効です。このバージョンと互換性のないデータベース・オブジェクトまたは属性は抽出されません。

  • COMPATIBLE : (デフォルト)データベース互換性レベルおよび機能の互換性リリース・レベルに対応するメタデータのバージョン(V$COMPATIBILITYビューで表示されます)。データベース互換性は9.2以上に設定する必要があります。

  • LATEST: 現在のデータベース・バージョンを指定するメタデータのバージョン。

  • 特定のデータベース・バージョン。たとえば、'10.0.0'の場合、Oracle Databaseリリース10.0.0未満にはできません。

155.5.13 EXPORT_SQL_TESTCASE_DIR_BY_TXTファンクション

このファンクションは、引数として渡されるSQLに対応するSQLテスト・ケースを生成します。引数として渡されるディレクトリ内に、スクリプトおよびダンプ・ファイルのセットを作成します。

構文

DBMS_SQLDIAG.EXPORT_SQL_TESTCASE_DIR_BY_TXT (
    incident_id        IN   NUMBER,
    directory          IN   VARCHAR2,
    sql_text           IN   CLOB,
    user_name          IN   VARCHAR2 := 'SYS',
    exportEnvironment  IN   VARCHAR2 := 'TRUE',
    exportMetadata     IN   VARCHAR2 := 'TRUE',
    exportData         IN   VARCHAR2 := 'FALSE',
    samplingPercent    IN   VARCHAR2 := '100', 
    ctrlOptions        IN   VARCHAR2 := NULL
    version            IN   VARCHAR2 := 'COMPATIBLE')
  RETURN BOOLEAN;

パラメータ

表155-22 EXPORT_SQL_TESTCASE_DIR_BY_TXTファンクションのパラメータ

パラメータ 説明

incident_id

違反SQLが含まれているインシデントID。

directory

生成された様々なファイルを保存するディレクトリ。

sql_text

記述するSQL文のテキスト。

username

SQLの解析に使用されるユーザー・スキーマの名前。デフォルトはSYSです。

exportEnvironment

コンパイル環境をエクスポートする必要がある場合は、TRUEを指定します。

exportMetadata

SQLで参照されているオブジェクトの定義をエクスポートする必要がある場合は、TRUEを指定します。

exportData

SQLで参照されているオブジェクトのデータをエクスポートする必要がある場合は、TRUEを指定します。

samplingPercent

TRUEの場合は、ダンプ・ファイルの作成に使用するサンプリングのパーセントを指定します。

ctrlOptions

不透明な制御パラメータ。たとえば、3回実行するには、文字列'<parameter name="mexec_count">3</parameter>'ctrlOptionsを設定します。

  • capture - BASIC(デフォルト)またはWITH_RUNTIME_INFOです。このパラメータでTCB取得のモードを定義します。

    BASIC: Oracle Release 11gのTCBとして実行され、そのリリースで取得したすべての情報のほか、AWRレポート、SQL監視レポートおよびパラメータ情報が取得されます。

    WITH_RUNTIME_INFO: BASICモード下で取得された情報とともに、動的サンプリング・データ、バインドのリスト、動的計画の情報など、SQLのランタイム情報がTCBで取得されます。

  • name=mexec_count - 値はすべて正の数(N)です。このパラメータにより、TCBで文をN回実行し、各実行の終了時にランタイム情報を取得するように命令します。

  • name=stat_history_since - 値は日付です。このパラメータを使用してオブジェクトの統計履歴がエクスポートされます。指定された日付から統計履歴がエクスポートされます。

version

抽出されるデータベース・オブジェクトのバージョン。このオプションは、EXPORTでのみ有効です。このバージョンと互換性のないデータベース・オブジェクトまたは属性は抽出されません。

  • COMPATIBLE : (デフォルト)データベース互換性レベルおよび機能の互換性リリース・レベルに対応するメタデータのバージョン(V$COMPATIBILITYビューで表示されます)。データベース互換性は9.2以上に設定する必要があります。

  • LATEST: 現在のデータベース・バージョンを指定するメタデータのバージョン。

  • 特定のデータベース・バージョン。たとえば、'10.0.0'の場合、Oracle Databaseリリース10.0.0未満にはできません。

155.5.14 GET_FIX_CONTROLファンクション

このファンクションは、指定したバグ番号に対する固定制御の値を戻します。

構文

DBMS_SQLDIAG.GET_FIX_CONTROL (
    bug_number   IN    NUMBER)
  RETURN NUMBER;

パラメータ

表155-23 GET_FIX_CONTROLファンクションのパラメータ

パラメータ 説明

bug_number

バグ番号

155.5.15 GET_SQLファンクション

このファンクションは、指定したインシデントIDに関連付けられているトレース・ファイルからsql_setrowをロードします。

構文

DBMS_SQLDIAG.GET_SQL (
    incident_id  IN     VARCHAR2)
  RETURN SQLSET_ROW;

パラメータ

表155-24 GET_SQLファンクションのパラメータ

パラメータ 説明

incident_id

インシデントの識別子。

155.5.16 IMPORT_SQL_TESTCASEプロシージャ

このプロシージャは、SQLテスト・ケースをスキーマにインポートします。

構文

この変数には、ソース・ディレクトリとSQLテスト・ケース・メタデータ・オブジェクト(XML形式)が必要です。

DBMS_SQLDIAG.IMPORT_SQL_TESTCASE (
    directory                IN   VARCHAR2,
    sqlTestCase              IN   CLOB,
    importEnvironment        IN   BOOLEAN   :=  TRUE,
    importMetadata           IN   BOOLEAN   :=  TRUE,
    importData               IN   BOOLEAN   :=  TRUE,
    importPkgbody            IN   BOOLEAN   :=  FALSE,
    importDiagnosis          IN   BOOLEAN   :=  TRUE,
    ignoreStorage            IN   BOOLEAN   :=  TRUE,
    ctrlOptions              IN   VARCHAR2  :=  NULL,
    preserveSchemaMapping    IN   BOOLEAN   :=  FALSE);

この変数には、SQLテスト・ケース・メタデータ・ファイルのソース・ディレクトリ名が必要です。

DBMS_SQLDIAG.IMPORT_SQL_TESTCASE (
    directory                IN   VARCHAR2,
    filename                 IN   VARCHAR2,
    importEnvironment        IN   BOOLEAN   :=  TRUE,
    importMetadata           IN   BOOLEAN   :=  TRUE,
    importData               IN   BOOLEAN   :=  TRUE,
    importPkgbody            IN   BOOLEAN   :=  FALSE,
    importDiagnosis          IN   BOOLEAN   :=  TRUE,
    ignoreStorage            IN   BOOLEAN   :=  TRUE,
    ctrlOptions              IN   VARCHAR2  :=  NULL,
    preserveSchemaMapping    IN   BOOLEAN   :=  FALSE);

パラメータ

表155-25 IMPORT_SQL_TESTCASEプロシージャのパラメータ

パラメータ 説明

directory

テスト・ケース・ファイルがあるディレクトリ。

filename

SQLテスト・ケースについて記述したXML文書を含むファイルの名前。

importEnvironment

コンパイル環境をインポートする必要がある場合は、TRUEを指定します。

importMetadata

SQLで参照されているオブジェクトの定義をインポートする必要がある場合は、TRUEを指定します。

importData

SQLで参照されているオブジェクトのデータをインポートする必要がある場合は、TRUEを指定します。

importPkgbody

SQLで参照されているパッケージの本体をインポートする場合は、TRUEを指定します。

importDiagnosis

タスクに関連付けられた診断情報をインポートする必要がある場合は、TRUEを指定します。

ignoreStorage

記憶域の属性を無視する必要がある場合は、TRUEを指定します。

ctrlOptions

不透明な制御パラメータであり、このcaptureのみが当該のサブプログラムに有効です。

  • capture - BASIC(デフォルト)またはWITH_RUNTIME_INFOです。このパラメータでTCB取得のモードを定義します。

    BASIC: Oracle Release 11gのTCBとして実行され、そのリリースで取得したすべての情報のほか、AWRレポート、SQL監視レポートおよびパラメータ情報が取得されます。

    WITH_RUNTIME_INFO: BASICモード下で取得された情報とともに、動的サンプリング・データ、バインドのリスト、動的計画の情報など、SQLのランタイム情報がTCBで取得されます。

preserveSchemaMapping

スキーマ(単数または複数)が元の環境からテスト環境に再マップされない場合は、TRUEを指定します(対象のデータベースでマップされているスキーマはソース・データベースと同一です)。preservesSchemaMappingTRUEに設定された状態でインポートが実行されたときに、スキーマ内にオブジェクトが存在する場合は、そのインポートで既存のオブジェクトが上書きされることに注意してください。

使用上の注意

  • SQLテスト・ケースは、別のマシンでSQLの失敗を再現するために必要なファイルのセットを生成します。次のものが含まれます。

    • スキーマ・オブジェクトおよび統計情報を含むダンプ・ファイル(.dmp)

    • 文のEXPLAIN PLAN(拡張モード)

    • 問題となる文で収集した診断情報

    • オブジェクトを再ロードするために実行する重要なスクリプト

    • ソースのシステム統計情報をリプレイするSQLスクリプト

    • SQLテスト・ケースについて記述したコンテンツ・ファイルの表

    • メタデータ(xxxxmain.xml)

    • TCBの使用方法を説明するREADME.txtファイル

    • 文(ol.xml)で使用されるアウトライン

    • エクスポートするdb/env(prmimp.sql)内のパラメータ・セットのリスト

    • SQL監視レポート(smrpt.html)(存在する場合)

    • AWRレポート(awrrpt.html)(存在する場合)

    • 当該の文で使用されるバインドのリスト(bndlst.xml)

  • ユーザーSYSでテスト・ケース・ビルダー(TCB)を実行することはできません。かわりに、SYSDBA権限を付与できる別のユーザーを使用してください。

  • TCBのデフォルト設定では、データはエクスポートされません。ただし、最適ではない結果を診断するためなどにデータが必要な場合があります。データをエクスポートするには、exportData=>TRUEに設定してEXPORT_SQL_TESTCASEプロシージャをコールします(importData=>FALSEOFFに設定しないかぎり、データはデフォルトでインポートされます)。

  • TCBはデフォルトでPL/SQLパッケージ仕様部を含みますが、PL/SQLパッケージ本体は含みません。しかし、PL/SQLファンクションを起動するため、またはパッケージでVirtual Private Database(VPD)機能が定義されているためパッケージ本体が必要になる場合もあります。PL/SQLパッケージ本体をエクスポートするには、exportPkgbody=>TRUEに設定して、EXPORT_SQL_TESTCASEプロシージャをコールします。PL/SQLパッケージ本体をインポートするには、importPkgbody=>TRUEに設定して、IMPORT_SQL_TESTCASEプロシージャをコールします。

  • EXPORT_SQL_TESTCASEプロシージャの起動時に使用されるcapture値は、このプロシージャをコールする際に使用する必要があります。

155.5.17 INCIDENTID_2_SQLプロシージャ

このプロシージャは、インシデントIDのsql_setrowを初期化します。

構文

DBMS_SQLDIAG.INCIDENTID_2_SQL (
    incident_id   IN     VARCHAR2,
    sql_stmt      OUT    SQLSET_ROW,
    problem_type  OUT    NUMBER, 
    err_code      OUT    BINARY_INTEGER,
    err_mesg      OUT    VARCHAR2);

パラメータ

表155-26 INCIDENTID_2_SQLプロシージャのパラメータ

パラメータ 説明

incident_id

インシデントの識別子。

sql_stmt

結果として得られるSQL

problem_type

SQL問題の暫定タイプ(現時点では、PROBLEM_TYPE_COMPILATION_ERRORおよびPROBLEM_TYPE_EXECUTION_ERROR)。

err_code

エラー・コード。存在しない場合はNULLに設定されます。

err_msg

エラー・メッセージ。存在しない場合はNULLに設定されます。

155.5.18 INTERRUPT_DIAGNOSIS_TASKプロシージャ

このプロシージャは、診断タスクを中断します。

構文

DBMS_SQLDIAG.INTERRUPT_DIAGNOSIS_TASK (
    taskname        IN   VARCHAR2); 

パラメータ

表155-27 INTERRUPT_DIAGNOSIS_TASKプロシージャのパラメータ

パラメータ 説明

taskname

タスクの名前

155.5.19 LOAD_SQLSET_FROM_TCBファンクション

このファンクションは、テスト・ケース・ビルダー・ファイルからSQLSETをロードします。

構文

DBMS_SQLDIAG.LOAD_SQLSET_FROM_TCB (
    directory        IN     VARCHAR2,
    filename         IN     VARCHAR2,
    sqlset_name      IN     VARCHAR2 DEFAULT NULL)
  RETURN VARCHAR2;

パラメータ

表155-28 LOAD_SQLSET_FROM_TCBファンクションのパラメータ

パラメータ 説明

directory

ディレクトリの名前

filename

ファイルの名前

sqlset_name

SQLSETの名前。

155.5.20 PACK_STGTAB_SQLPATCHプロシージャ

このプロシージャは、CREATE_STGTAB_SQLPATCHプロシージャをコールして作成されたステージング表にSQLパッチをパックします。

構文

DBMS_SQLDIAG.UPPACK_STGTAB_SQLPATCH (
   patch_name            IN  VARCHAR2 := '%',
   patch_category        IN  VARCHAR2 := 'DEFAULT',
   staging_table_name    IN  VARCHAR2,
   staging_schema_owner  IN  VARCHAR2 := NULL);

パラメータ

表155-29 UPPACK_STGTAB_SQLPATCHプロシージャのパラメータ

パラメータ 説明

patch_name

パックするパッチの名前(%ワイルドカードを使用可、大/小文字区別)。

patch_category

パックするパッチのカテゴリ(%ワイルドカードを使用可、大/小文字区別)。

staging_table_name

(必須)使用する表の名前(大/小文字区別)。

staging_schema_owner

表が存在するスキーマ(大/小文字区別)。現行のスキーマの場合はNULL

使用上の注意

  • ステージング表に対するADMINISTER SQL PLAN MANAGEMENT OBJECT権限およびINSERT権限が必要です。

  • デフォルトでは、カテゴリDEFAULT内のすべてのSQLパッチを移動します。詳細は、「例」を参照してください。このサブプログラムは各SQLパッチをパックした後にCOMMITを発行するため、実行中にエラーが発生した場合、ステージング表にいくつかのパッチが残る可能性があります。

155.5.21 REPLAY_SQL_TESTCASEファンクション

このファンクションは、SQLテスト・ケースの再生成を自動化します。

構文

DBMS_SQLDIAG.REPLAY_SQL_TESTCASE (
   directory       IN   VARCHAR2,
   filename        IN   VARCHAR2,
   ctrlOptions     IN   VARCHAR2  := NULL,
   format          IN   VARCHAR2  := 'TEXT')
   RETURN CLOB;

DBMS_SQLDIAG.REPLAY_SQL_TESTCASE (
   directory       IN   VARCHAR2,
   sqlTestCase     IN   CLOB,
   ctrlOptions     IN   VARCHAR2  := NULL,
   format          IN   VARCHAR2  := 'TEXT')
   RETURN CLOB;

パラメータ

表155-30 REPLAY_SQL_TESTCASEファンクションのパラメータ

パラメータ 説明

directory

テスト・ケース・ファイルがあるディレクトリ。

filename

SQLテスト・ケースについて記述したXML文書を含むファイルの名前。

ctrlOptions

不透明な制御パラメータ。たとえば、3回実行するには、文字列'<parameter name="mexec_count">3</parameter>'ctrlOptionsを設定します。

  • replay - EXPLAIN(デフォルト)、OUTLINEEXECUTIONまたはOUTLINE EXECUTIONです。このパラメータでTCBリプレイ機能を定義します。

    EXPLAIN: リプレイにより、アウトラインを使用せずに文を説明します。

    OUTLINE: リプレイでアウトライン・モードを使用し、アウトラインを使用して文を説明します。

    EXECUTION: リプレイにより、アウトラインを使用せずに文を実行します。

    OUTLINE EXECUTION: リプレイにより、アウトラインを使用して文を実行します。

    ユーザーが不適切なパラメータ値を指定した場合は、replayがデフォルト・モードで実行され、エラーがスローされないことに注意してください。

  • name=mexec_count - 値はすべて正の数(N)です。このパラメータにより、TCBで文をN回実行し、各実行の終了時にランタイム情報を取得するように命令します。

sqlTestCase

SQLテスト・ケース

format

リプレイ・レポートの形式。使用可能な形式は、TEXTXMLおよびHTMLです。

TCB Replay Mode: Execute
 SELECT /* tcbdynpl_1 */ /*+ gather_plan_statistics */ * FROM (SELECT * FROM emp where emp.sal > 100) emp, dept WHERE emp.deptno = dept.deptno And emp.sal > 1000 /* tcbdynpl_1 */
 
Explain Plan
 Plan Hash Value  : 2219294842
 
-----------------------------------------------------------------
| Id  | Operation                       | Name           | Rows |
-----------------------------------------------------------------
|   0 | SELECT STATEMENT                |                |   13 |
| * 1 |   HASH JOIN                     |                |   13 |
|   2 |    NESTED LOOPS                 |                |      |
|   3 |     NESTED LOOPS                |                |   13 |
|   4 |      STATISTICS COLLECTOR       |                |      |
|   5 |       TABLE ACCESS FULL         | DEPT           |    4 |
| * 6 |      INDEX RANGE SCAN           | EMP_IDX_DEPTNO |      |
| * 7 |     TABLE ACCESS BY INDEX ROWID | EMP            |    3 |
| * 8 |    TABLE ACCESS FULL            | EMP            |   13 |
-----------------------------------------------------------------
 
Predicate Information (identified by operation id):
------------------------------------------
* 1 - access("EMP"."DEPTNO"="DEPT"."DEPTNO")
* 6 - access("EMP"."DEPTNO"="DEPT"."DEPTNO")
* 7 - filter("EMP"."SAL">1000)
* 8 - filter("EMP"."SAL">1000)

Runtime Plan
 Plan Hash Value  : 2219294842
 
-------------------------------------------------------
| Id  | Operation            | Name | E-Card | A-Card |
-------------------------------------------------------
|   0 | SELECT STATEMENT     |      |        |      0 |
| * 1 |   HASH JOIN          |      |     13 |      0 |
|   2 |    TABLE ACCESS FULL | DEPT |      4 |      0 |
| * 3 |    TABLE ACCESS FULL | EMP  |     13 |      0 |
-------------------------------------------------------
 
Predicate Information (identified by operation id):
------------------------------------------
* 1 - access("EMP"."DEPTNO"="DEPT"."DEPTNO")
* 3 - filter("EMP"."SAL">1000)
 
REPLAY Note:
-----------
- Replay used dynamic sampling
- Replay forced Dynamic plan

155.5.22 REPORT_DIAGNOSIS_TASKファンクション

このファンクションは、診断タスクをレポートします。これは、必要なレポートが含まれているCLOBを戻します。

構文

DBMS_SQLDIAG.REPORT_DIAGNOSIS_TASK (
    taskname           IN   VARCHAR2,
    type               IN   VARCHAR2  := TYPE_TEXT,
    level              IN   VARCHAR2  := LEVEL_TYPICAL,
    section            IN   VARCHAR2  := SECTION_ALL,
    object_id          IN   NUMBER    := NULL,
    result_limit       IN   NUMBER    := NULL,
    owner_name         IN   VARCHAR2  := NULL)
  RETURN CLOB;

パラメータ

表155-31 REPORT_DIAGNOSIS_TASKファンクションのパラメータ

パラメータ 説明

taskname

レポートするタスクの名前。

type

レポートのタイプ。設定可能な値は、TEXT、HTML、XMLです(表155-4を参照)。

level

リコメンデーションの形式。設定可能な値は、TYPICAL、BASIC、ALLです(表155-5を参照)。

section

レポート内の特定のセクション。設定可能な値は、SUMMARY、FINDINGS、PLAN、INFORMATION、ERROR、ALLです(表155-6を参照)。

object_id

SQLチューニング・セット(STS)の特定の文を表すアドバイザ・フレームワーク・オブジェクトの識別子。

result_limit

レポート生成の対象となる、STS内の文の数。

owner_name

使用するタスク実行の名前。NULLの場合は、最後のタスク実行に関するレポートが生成されます。

155.5.23 RESET_DIAGNOSIS_TASKプロシージャ

このプロシージャは、診断タスクをリセットします。

構文

DBMS_SQLDIAG.RESET_DIAGNOSIS_TASK (
    taskname        IN   VARCHAR2); 

パラメータ

表155-32 RESET_DIAGNOSIS_TASKプロシージャのパラメータ

パラメータ 説明

taskname

タスクの名前

155.5.24 RESUME_DIAGNOSIS_TASKプロシージャ

このプロシージャは、診断パスを再開します。

構文

DBMS_SQLDIAG.RESUME_DIAGNOSIS_TASK (
    taskname        IN   VARCHAR2); 

パラメータ

表155-33 RESUME_DIAGNOSIS_TASKプロシージャのパラメータ

パラメータ 説明

taskname

タスクの名前

155.5.25 SET_DIAGNOSIS_TASK_PARAMETERプロシージャ

このプロシージャは、VARCHAR2タイプのSQL診断パラメータの値を更新するためにコールします。

このプロシージャをコールする前に、タスクを初期状態に設定する必要があります。このプロシージャによって設定可能な診断パラメータは、次のとおりです。

  • MODE: 診断スコープ(制限付き/包括的)。

  • _SQLDIAG_FINDING_MODE: レポート内の検索結果(設定可能な値については表155-8を参照)。

構文

DBMS_SQLDIAG.SET_DIAGNOSIS_TASK_PARAMETER (
    taskname           IN   VARCHAR2,
    parameter          IN   VARCHAR2,    value              IN   NUMBER);

パラメータ

表155-34 SET_DIAGNOSIS_TASK_PARAMETERプロシージャのパラメータ

パラメータ 説明

taskname

実行するタスクの識別子。

parameter

設定するパラメータの名前。

value

指定したパラメータの新しい値。

155.5.26 UNPACK_STGTAB_SQLPATCHプロシージャ

このプロシージャは、PACK_STGTAB_SQLPATCHプロシージャをコールして移入されたステージング表からアンパックします。これは、ステージング表に保存されているパッチ・データを使用して、システム上にパッチを作成します。パッチがすでに存在する場合、ユーザーは既存のパッチをパッチ・データに置き換えることも選択できます。この場合、同じ文を参照するパッチについては、名前が同じ場合にのみ置き換えることができます(「ACCEPT_SQL_PATCHファンクションおよびプロシージャ」を参照)。

構文

DBMS_SQLDIAG.UPPACK_STGTAB_SQLPATCH (
   patch_name            IN  VARCHAR2 := '%',
   patch_category        IN  VARCHAR2 := '%',
   replace               IN  BOOLEAN,
   staging_table_name    IN  VARCHAR2,
   staging_schema_owner  IN  VARCHAR2 := NULL);

パラメータ

表155-35 UPPACK_STGTAB_SQLPATCHプロシージャのパラメータ

パラメータ 説明

patch_name

アンパックするパッチの名前(%ワイルドカードを使用可、大/小文字区別)。

patch_category

アンパックするパッチのカテゴリ(%ワイルドカードを使用可、大/小文字区別)。

replace

すでに存在するパッチを置換します。ステージング表のパッチの名前と、別のSQLのアクティブなパッチの名前が同じ場合、パッチは置換できません。すでに存在するパッチを作成しようとすると、エラーが発生します。

staging_table_name

(必須)使用する表の名前(大/小文字区別)。

staging_schema_owner

表が存在するスキーマ(大/小文字区別)。現行のスキーマの場合はNULL

使用上の注意

  • ステージング表に対するADMINISTER SQL MANAGEMENT OBJECT権限およびSELECTまたはREAD権限が必要です。

  • デフォルトでは、ステージング表内のすべてのSQLパッチが移動されます。このファンクションは、各パッチを正常にロードした後でコミットします。個々のパッチの作成に失敗すると、エラーが発生し、ステージング表に残っているパッチには進みません。