1. データ・カートリッジ開発者ガイド
  2. リファレンス
  3. 拡張可能索引付けインタフェース

20 拡張可能索引付けインタフェース

Oracleデータ・カートリッジ・インタフェース拡張可能索引付けの様々なパラメータについて説明します。

20.1 拡張可能索引付け - システム定義のインタフェース・ルーチン

表20-1に、拡張可能索引付けルーチンを示します。

注意:

この種のルーチンは、エンド・ユーザーが実行するSQL文に基づいて、Oracleにより適切なタイミングで起動されます。索引データが破損する場合があるため、この種のルーチンは直接起動しないでください。

表20-1 システム定義の拡張可能索引付けインタフェース・ルーチンの概要

ルーチン 説明

ODCIGetInterfaces()

INDEXTYPEがCREATE INDEXTYPE...文により作成されるとき、または変更されるときに起動されます。

ODCIIndexAlter()

ドメイン索引、またはドメイン索引パーティションが、ALTER INDEX、ALTER INDEX PARTITION、TRUNCATE TABLE、RENAME TABLE、ALTER TABLE RENAME COLUMNまたはALTER TABLE [ADD|TRUNCATE|SPLIT|MERGE] PARTITION文を使用して変更されるときに起動されます。

ODCIIndexClose()

演算子の処理を終了するために起動されます。

ODCIIndexCreate()

ユーザーが発行したCREATE INDEX...INDEXTYPE IS...PARAMETERS...文によりドメイン索引が作成されるときに起動されます。

ODCIIndexDelete()

1つ以上の列にドメイン索引が定義されている表から1行が削除されるときに起動されます。

ODCIIndexDrop()

ドメイン索引がDROP INDEX文を使用して明示的に削除されるときか、DROP TABLEまたはDROP USER文を介して暗黙的に削除されるときに起動されます。

ODCIIndexExchangePartition()

ローカル定義のドメイン索引を持つパーティション表に対してALTER TABLE EXCHANGE PARTITION...INCLUDING INDEXESが発行されるときに起動されます。

ODCIIndexFetch()

演算子述語を満たす行を取得するために繰り返しコールされます。

ODCIIndexGetMetadata()

索引に関連付けられた非ディクショナリ・メタデータを構成するPL/SQLコードの一連の文字列を戻します。

ODCIIndexInsert()

1つ以上の列にドメイン索引が定義されている表に1行または一連の行が挿入されるときに起動されます。

ODCIIndexStart()

索引付けされた列で演算子の評価を開始するために起動されます。

ODCIIndexUpdate()

表の1行の更新時に、更新される列にドメイン索引が定義されている場合に起動されます。

ODCIIndexUpdPartMetadata()

パーティション・メンテナンス操作時に起動されます。パーティション・メンテナンス操作を正しく反映するために、索引タイプのメタデータ表をパッチします。

ODCIIndexUtilCleanup()

ODCIIndexUtilGetTableNames()により作成された一時状態をクリーン・アップします。

ODCIIndexUtilGetTableNames()

索引データを格納するセカンダリ表のトランスポートが必要かどうかを判別します。

20.1.1 ODCIGetInterfaces()

INDEXTYPEがCREATE INDEXTYPE...文により作成されるとき、または変更されるときに起動されます。

構文

FUNCTION ODCIGetInterfaces(
   ifclist OUT ODCIObjectList)
RETURN NUMBER
パラメータ 説明 
ifclist

サポート対象のインタフェースに関する情報を含みます。

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error。

使用上の注意

このファンクションは、静的な型のメソッドとして実装する必要があります。

索引タイプがODCIIndexインタフェースの2番目のバージョンを使用している場合、このファンクションはODCIObjectListでSYS.ODCIINDEX2を返す必要があります。

20.1.2 ODCIIndexAlter()

ドメイン索引またはドメイン索引パーティションが、次のメソッドのうち1つを使用して変更されたときに起動されます。

  • ALTER INDEX

  • ALTER INDEX PARTITION

  • TRUNCATE TABLE table_name

  • RENAME TABLE

  • ALTER TABLE...[ADD|TRUNCATE|SPLIT|MERGE]...PARTITION

  • ALTER TABLE RENAME

  • ALTER TABLE RENAME COLUMN

ローカル・ドメイン索引が作成されたときに索引パーティションを移入するために、このメソッドは実表の各パーティションごとに起動されます。

構文

STATIC FUNCTION ODCIIndexAlter(
   ia ODCIIndexInfo, 
   parms IN OUT VARCHAR2, 
   alter_option NUMBER, 
   env ODCIEnv) 
RETURN NUMBER
パラメータ 説明 
ia

索引と索引付けされた列に関する情報を含みます。

 
parms (IN)

パラメータ文字列

  • ALTER INDEX PARAMETERSまたはALTER INDEX REBUILDの場合は、ユーザー指定のパラメータ文字列を含みます。

  • ALTER INDEX RENAMEの場合は、ドメイン索引の新規名を含みます。

  • ALTER TABLE RENAME COLUMNの場合は、新規のドメイン索引付けされた列名を含みます。

  • ALTER TABLE RENAMEまたはRENAME TABLEの場合は、新しい表名が含まれます 

parms (OUT)

パラメータ文字列

ALTER INDEX PARAMETERSまたはALTER INDEX REBUILDの場合にのみ有効です。システム・カタログに格納される結果文字列を含みます。 

alter_option

次のオプションから1つ指定します。

  • ALTER INDEX [PARTITION] PARAMETERSの場合はAlterIndexNone

  • ALTER INDEX RENAME [PARTITION]の場合はAlterIndexRename。

  • ALTER INDEX REBUILD [PARTITION] [PARAMETERS]の場合はAlterIndexRebuild。

  • ALTER TABLE RENAME COLUMNの場合はAlterIndexRenameCol。

  • ALTER TABLE RENAMEまたはRENAME TABLEの場合はAlterIndexRenameTab

  • ALTER TABLE UPDATE BLOCK REFERENCESの場合はAlterIndexUpdBlockRefs。

  • ドメイン索引はユーザー管理で索引タイプはシステム管理の場合、ALTER INDEX COMPILEの場合はAlterIndexMigrate。 

env

ルーチンに渡される環境ハンドル

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error、それ以外の場合はODCIConst.Warning。ローカル索引パーティションを再作成するために起動される場合、ODCIConst.ErrContinueも戻される場合があります。

使用上の注意

  • このファンクションは、静的な型のメソッドとして実装する必要があります。

  • ドメイン索引に対するALTER INDEX文は、複数の方法で起動できます。 

    ALTER INDEX index_name
PARAMETERS (parms);

    または

    ALTER INDEX index_name
REBUILD PARAMETERS (parms);

    この2つの場合の正確な動作は、実装によって定義されます。1つの方法として、第1の文ではパラメータに基づいて単に索引を再編成し、第2の文では最初から再作成できます。

  • 入力パラメータ文字列の最大長は1000文字です。parms引数のOUT値を、システム・カタログに格納される結果のパラメータ文字列に設定できます。

  • また、ALTER INDEX文を使用するとドメイン索引名を次のように変更できます。 

    ALTER INDEX index_name
RENAME TO new_index_name

  • ドメイン索引が作成された表の名前を変更する場合、alter_option=AlterIndexRenameTabを使用してODCIIndexAlter()が起動され、new_table_nameがparms引数に渡されます。 

    ALTER TABLE table_name 
RENAME new_table_name

    または

    RENAME table_name 
TO new_table_name

  • ドメイン索引が作成された列の名前を変更する場合、alter_option=AlterIndexRenameColを使用してODCIIndexAlter()が起動され、new_column_nameがparms引数に渡されます。 

    ALTER TABLE table_name 
RENAME COLUMN column_name 
TO new_column_name

  • PARALLEL句を省略すると、ドメイン索引またはローカル・ドメイン索引パーティションが逐次再作成されます。

  • PARALLEL句を指定すると、ODCIIndexAlter()の起動時に並列度がODCIIndexInfoのIndexParaDegree属性に渡され、IndexInfoFlags属性のParallelビットが設定されます。並列度は次のように決定されます。

    • PARALLEL DEGREE degを指定すると、degが渡されます。

    • PARALLELのみを指定すると、デフォルトの並列度が指定されたことを示す定数が渡されます。

  • ODCIIndexAlterルーチンがODCIConst.Successを戻す場合、索引は有効であり再利用できます。ODCIIndexAlter()ルーチンがODCIConst.Warningを戻す場合、索引は有効であり再利用できますが、ユーザーに警告メッセージが戻されます。ODCIIndexAlter()エラー(または例外)を戻す場合、ドメイン索引にはFAILEDマークが付けられます。

  • ODCIIndexAlter()ルーチンの実行中は、ドメイン索引にLOADINGマークが付けられます。

  • ODCIIndexAlter()により実行される各SQL文は、独立した操作として処理されます。ODCIIndexCreate()による変更がアトミックであるという保証はありません。

  • AlterIndexUpdBlockRefs変更オプションは、索引構成表のドメイン索引にのみ適用されます。エンド・ユーザーがALTER INDEX domain_index UPDATE BLOCK REFERENCESを実行すると、ODCIIndexAlter()がAlterIndexUpdBlockRefsビットを設定した状態でコールされ、カートリッジ開発者が論理ROWIDに格納された行のブロック場所に関する不確定要素を更新できるようになります。

  • AlterIndexMigrateの変更オプションは、ドメイン索引のユーザー管理からシステム管理への移行にのみ適用されます。ユーザー管理のドメイン索引にINVALIDマークが付けられていて、その索引タイプがシステム管理である場合、ドメイン索引を再検証するために、ALTER INDEX domain_index COMPILEをコールする必要があります。alter_option=AlterIndexMigrateを使用してODCIIndexAlter()メソッドをコールし、ドメイン索引をシステム管理アプローチに移行できます。

関連項目:

20.1.3 ODCIIndexClose()

演算子の処理を終了するために起動されます。

構文

FUNCTION ODCIIndexClose(
   self IN impltype, 
   env ODCIEnv) 
RETURN NUMBER
パラメータ 説明 
self(IN)

ODCIIndexFetch()の前回の起動により戻されたコンテキストの値

 
env

ルーチンに渡される環境ハンドル

戻り値

  • 正常終了した場合はODCIConst.Success。

  • エラーの場合はODCIConst.Error。

使用上の注意

索引実装者は、メモリーや他のリソースの解放など、適切なアクションを実行してドメイン索引スキャンの処理を完了できます。

20.1.4 ODCIIndexCreate()

ユーザーが発行したCREATE INDEX...INDEXTYPE IS...PARAMETERS...文によりドメイン索引が作成されるときに起動されます。ドメイン索引は、非パーティション索引またはローカル・パーティション・ドメイン索引です。ローカル・パーティション・ドメイン索引は、システム管理またはユーザー管理スキーマのいずれかで作成されます。

構文

FUNCTION ODCIIndexCreate(
   ia ODCIIndexInfo, 
   parms VARCHAR2, 
   env ODCIEnv)
RETURN NUMBER
パラメータ 説明 
ia

索引と索引付けされた列に関する情報を含みます。

 
parms

渡されるがOracleにより解析されないPARAMETERS文字列。このパラメータ文字列の最大サイズは1,000文字です。 

env

ルーチンに渡される環境ハンドル

戻り値

ODCIConst.Success、ODCIConst.Error、ODCIConst.Warning、ODCIConst.ErrContinue(メソッドがローカル・パーティション索引を作成するためにパーティション・レベルで呼び出され、エラーが発生した場合でも次のパーティションに進む場合)、またはODCIConst.Fatal(索引のすべてのディクショナリ・エントリがクリーン・アップされ、CREATE INDEX操作がロールバックされることを示す場合)。このステータス・コードが返される場合は、カートリッジ・コードによってオブジェクトが作成されていないこと(または作成されたオブジェクトがクリーン・アップされていること)が前提となっています。

使用上の注意

  • このファンクションは、STATIC型のメソッドとして実装する必要があります。

  • 索引データを格納するオブジェクト(表など)を作成し、索引データを生成し、そのデータを索引データ表に格納する必要があります。

  • 空の表と空でない表の両方について索引の作成を処理する必要があります。実表が空でなければ、表全体をスキャンして索引データを生成できます。

  • ODCIIndexCreate()ルーチンの実行中は、ドメイン索引にLOADINGマークが付けられます。

  • ODCIIndexCreate()により実行される各SQL文は、独立した操作として処理されます。ODCIIndexCreate()による変更がアトミックであるという保証はありません。

  • 非パーティション・ドメイン索引を作成する場合は、ODCIIndexCreate()メソッドが呼び出されます。有効なリターン・コードは、ODCIConst.Success、ODCIConst.Warning ODCIConst.ErrorまたはODCIConst.Fatalのみです。操作によってODCIConst.Fatalが戻された場合、CREATE INDEX文はサーバーによってロールバックされます。

  • 非パーティション・ドメイン索引では、IndexPartition、TablePartition名およびcallPropertyはNULLです。

  • 非パーティション・ドメイン索引の場合は、ODCIIndexCreate()の起動時に並列度がODCIIndexInfoのIndexParaDegree属性に渡され、IndexInfoFlagsのParallelビットが設定されます。並列度は次のように決定されます。

    • PARALLEL DEGREE degを指定すると、degが渡されます。

    • PARALLELのみを指定すると、デフォルトの並列度が指定されたことを示す定数が渡されます。

    • PARALLEL句を完全に省略した場合、操作は順番に実行されます。

  • ODCIIndexCreate()ルーチンがODCIConst.Successを戻す場合、索引は有効であり再利用できます。ODCIIndexAlter()ルーチンがODCIConst.Warningを戻す場合、索引は有効であり再利用できますが、ユーザーに警告メッセージが戻されます。ODCIIndexCreate()ルーチンがODCIConst.Error (または例外)を戻す場合、ドメイン索引にはFAILEDマークが付けられます。

  • FAILEDのドメイン索引に対して許可される操作は、DROP INDEX、TRUNCATE TABLEまたはALTER INDEX REBUILDのみです。

  • REF属性を含むオブジェクト型の列にドメイン索引を作成する場合は、索引の作成中にREFを間接参照しないでください。REFを間接参照すると、別の表インスタンスからデータがフェッチされます。他の表のデータが変更されると、ドメイン索引は正しくなくなります。このことはユーザーに通知されません。

  • システム管理のローカル・ドメイン索引を作成するために、ODCIIndexCreate()メソッドは2度コールされ、有効なリターン・コードは、ODCIConst.Success、ODCIConst.WarningまたはODCIConst.Errorのみです。ODCIConst.Fatalは最初のコールで戻され、CREATE INDEX文がサーバーによってロールバックされます。パーティションの数は、ODCIIndexInfo.IndexPartitionTotal引数として渡されます。最初のコールですべての索引記憶域表が作成されます。すべての索引記憶域表は、ローカル・ドメイン索引のメリットを得るためにシステム・パーティションである必要があります。また、次の点にも注意が必要です。

    • これらの表は実表と同じパーティション数である必要があります。実表がコンポジット・パーティション化されている場合、ドメイン索引記憶表のサブパーティション数は実表と同じである必要があります。

    • ユーザーは、オブジェクト・レベル属性およびパーティション・レベル属性でCREATE TABLE文を生成する必要があります。

  • オブジェクト・レベルの作成ルーチンは、オブジェクト・レベルのパラメータ文字列のみ渡します。ただし、すべてのパーティションに対して記憶域属性を構成するには、パーティション・レベルのパラメータ文字列が必要です。カートリッジの索引付けコードは、ディクショナリ表で*_ind_partitionsビューを問い合せてそれらを取得する必要があります。システム・パーティション表は、この段階では移入する必要はありません。ユーザーはODCIIndexAlter()以降のコールを待って、パーティションを移入する必要があります。また、記憶域表の名前を導出し、索引名および索引パーティション名からパーティションを導出することをお薦めします。この場合、*_ind_partitionsビューから索引パーティション名を取得し、記憶域表に対してパーティション名を構成する必要があります。

  • 第2コールODCIIndexCreate()で、ユーザーは、索引、制約およびトリガーなどのオブジェクトに依存するドメイン索引記憶域表を作成できます。SQLコールバックを直接使用する前に、作成できます。ただし、システム・パーティション記憶域表に対しては、次の索引タイプは禁止されています。

    • 非パーティション索引

    • グローバル・パーティション索引

  • 順序番号およびシノニムは、コールバックを使用して作成でき、パーティションからは独立しているとみなされます。非パーティション・ドメイン索引に作成されるオブジェクトのセットは、ローカル・パーティション索引のそれと同一で、これらのオブジェクトは、表またはパーティションのメンテナンス操作が実行されても影響を受けません。索引が削除される際にこれらのオブジェクトを削除するのは、ユーザーの役目です。

  • 一時使用に必要な他のオブジェクトは、コールバックを使用して作成されます。create callの終了時にそれらを削除するのは、ユーザー指定のコードの役目です。

  • 一時表は、中間データの保持用に作成できます。サーバーは、これらの表に対してメンテナンス操作を実行しません。

  • ファイルなどの外部オブジェクトは一時使用に作成できます。

  • ODCIIndexCreate()またはODCIIndexAlter()の起動後に残されたすべての表はシステム管理と想定され、サーバーは、削除、切り捨てまたはパーティション・メンテナンス操作時に、これらの表に対して適切なアクションを実行します。

  • このルーチンでは複数の処理(非パーティション索引の作成、ローカル索引の作成など)が実行されるため、適切にコーディングするよう特に注意する必要があります。

関連項目:

20.1.5 ODCIIndexDelete()

1つ以上の列にドメイン索引が定義されている表から1行が削除されるときに起動されます。

構文

FUNCTION ODCIIndexDelete(
   ia ODCIIndexInfo, 
   rid VARCHAR2, 
   oldval icoltype, 
   env ODCIEnv) 
RETURN NUMBER
パラメータ 説明 
ia

索引と索引付けされた列に関する情報を含みます。

 
rid

削除される行のROWID。

 
oldval

削除される行の索引付けされた列の値。データ型は索引付けされた列のデータ型と同じです。

 
env

ルーチンに渡される環境ハンドル

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error。

使用上の注意

  • このファンクションは、STATIC型のメソッドとして実装する必要があります。

  • このメソッドでは、索引データが格納される適切な表またはファイルから、削除された行に対応する索引データを削除する必要があります。

  • 索引パーティション・オブジェクト識別子ODCIIndexInfo.IndexPartitionIdenおよび実表パーティション物理識別子ODCIIndexInfo.IndexCols(1).TablePartitionIdenは、ローカル・ドメイン索引に渡されます。索引タイプには、パーティション番号を使用して新規DML構文を使用し、提供されたDATAOBJ_TO_MAT_PARTITIONファンクションを使用して、記憶域システム・パーティション表からデータを削除する必要があります。 

    DELETE FROM SP PARTITION (
   DATAOBJ_TO_MAT_PARTITION(
       base_table_name,
      :tab_physical_partid))
   VALUES(…) 
   WHERE rowid = :rowid;

20.1.6 ODCIIndexDrop()

ODCIIndexDrop()プロシージャは、ドメイン索引がDROP INDEX文を使用して明示的に削除されるときか、DROP TABLEまたはDROP USER文を介して暗黙的に削除されるときに起動されます。

構文

FUNCTION ODCIIndexDrop(
   ia ODCIIndexInfo, 
   env ODCIEnv) 
RETURN NUMBER
パラメータ 説明 
ia

索引と索引付けされた列に関する情報を含みます。

 
env

ルーチンに渡される環境ハンドル

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error、それ以外の場合はODCIConst.Warning。

使用上の注意

  • このメソッドは、静的な型のメソッドとして実装する必要があります。

  • このメソッドでは、ドメイン索引データを格納する表を削除する必要があります。

  • 非パーティション・ドメイン索引およびシステム管理ローカル・ドメイン索引の両方に対して、ODCIIndexDrop()メソッドは一度のみ起動されます。システム管理アプローチが使用されている場合、ユーザーは索引記憶域表を削除する必要はありません。コール完了後にカーネルによって自動的に実行されます。

  • ドメイン索引に(一部のDDLルーチンの異常終了が原因で)FAILEDマークが付いている場合があるため、ODCIIndexDrop()ルーチンでは部分的に作成されたドメイン索引をクリーン・アップできる必要があります。ODCIIndexDrop()ルーチンの実行中は、ドメイン索引にLOADINGマークが付けられます。

  • ODCIIndexDrop()ルーチンがODCIConst.Errorまたは例外を戻すと、DROP INDEX文が失敗し、索引にFAILEDマークが付けられることに注意してください。その場合、ドメイン索引を削除するにはFORCEオプションを使用する必要があります。明示的なDROP INDEX文の場合にODCIIndexDrop()ルーチンがODCIConst.Warningを戻すと、操作は成功しますがユーザーに警告メッセージが戻されます。

  • ODCIIndexDrop()により実行される各SQL文は、独立した操作として処理されます。ODCIIndexDrop()による変更がアトミックであるという保証はありません。

  • 非パーティション・ドメイン索引およびシステム管理ローカル・ドメイン索引の両方に対して、ODCIIndexDrop()メソッドは一度のみ起動されます。システム管理アプローチの場合、索引記憶域表は削除する必要はありません。コール完了後にカーネルによって自動的に実行されます。

関連項目:

ODCIIndexDrop()

20.1.7 ODCIIndexExchangePartition()

このメソッドは、ローカル・ドメイン索引が定義されているパーティション表に対してALTER TABLE EXCHANGE PARTITION...INCLUDING INDEXESが発行されるときに起動されます。

構文

FUNCTION ODCIIndexExchangePartition( 
   ia ODCIIndexInfo, 
   ia1 ODCIIndexInfo, 
   env ODCIEnv) 
RETURN NUMBER
パラメータ 説明

ia

交換するドメイン索引パーティションに関する情報を含みます。

ia1

非パーティション・ドメイン索引に関する情報を含みます。

env

ルーチンに渡される環境ハンドル

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error、それ以外の場合はODCIConst.Warning。

使用上の注意

  • このファンクションは、STATIC型のメソッドとして実装する必要があります。

  • このメソッドでは、ドメイン索引のパーティションから非パーティション・ドメイン索引への変換と、非パーティション索引からパーティション・ドメイン索引のパーティションへの変換を、両方とも処理する必要があります。

  • コンポジット・パーティション表のコンポジット・パーティションを交換する場合は、交換するパーティションの各サブパーティションに対してODCIIndexExchangePartitionがコールされます。

20.1.8 ODCIIndexFetch()

このプロシージャは、演算子述語を満たす行を取得するために繰り返しコールされます。

構文

FUNCTION ODCIIndexFetch(
   self IN [OUT] impltype, 
   nrows IN NUMBER, 
   rids OUT ODCIRidList, 
   env ODCIEnv) 
RETURN NUMBER
パラメータ 説明 
self(IN)

直前のコール(ODCIIndexFetchへのコール、またはこの演算子のインスタンスに対してフェッチを初めてコールする場合はODCIIndexStart()へのコール)により戻されたコンテキスト値。 

self(OUT)

次の問合せ時のコールに渡されるコンテキスト。このルーチンで値が変更されない場合は、このパラメータをOUTとして定義する必要がないことに注意してください。 

nrows

このコールでOracleに戻すことのできる結果の最大行数。

 
rids

このコールから戻される結果行のROWIDの配列。

 
env

ルーチンに渡される環境ハンドル

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error。

使用上の注意

  • ODCIIndexFetch()は、演算子述語を満たす行を戻します。つまり、演算子の戻り値が指定の範囲内に含まれるすべての行のROWIDが戻されます。

  • ODCIIndexFetch()をコールするたびに、最大nrows行を戻すことができます。渡されるnrowsの値は、いくつかの内部ファクタに基づいてOracleにより決定されます。ただし、ODCIIndexFetch()ルーチンでは、nrowsより少ない数の行を戻すことができます。ROWIDは出力のrids配列を介して戻されます。NULL ROWID(rids配列の要素)は、述語を満たす行がすべて戻されたことを示します。

    演算子述語を満たす行が3000行あり、nrowsの値が= 2000であるとします。初のODCIIndexFetch()のコールでは、最初の2000行を戻すことができます。第2のコールでは、残りの1000行と後続のNULL要素で構成されるridリストを戻すことができます。ridリスト内のNULL値は、条件を満たす行がすべて戻されたことを示します。

  • このコール中にコンテキスト値が変更されると、以降の問合せ時のコールには新規の値が渡されます。

関連項目:

20.1.9 ODCIIndexGetMetadata()

iaの索引に関連付けられた非ディクショナリ・メタデータを構成するPL/SQLコードの一連の文字列を戻します。このルーチンでは、インポート時に必要な情報を渡すことができます。たとえば、ポリシー、バージョン、作業環境などです。このメソッドは、実装固有のメタデータが必要でないかぎりオプションです。

構文

FUNCTION ODCIIndexGetMetadata(
   ia IN ODCIIndexInfo, 
   version IN VARCHAR2, 
   new_block OUT PLS_INTEGER,
   env ODCIEnv) 
RETURN VARCHAR2;
パラメータ 説明 
ia

現在エクスポート処理中の索引を指定します

 
version

11.2.0.1.00形式でコールを行っているエクスポートのバージョン

 
new_block

ゼロ以外(TRUE): 戻された文字列により新規のPL/SQLブロックが開始されます。エクスポートにより、現在のブロック(存在する場合)がENDで終了し、BEGINで新規のブロックがオープンされてから、文字列がダンプ・ファイルに書き込まれます。ルーチンが再びコールされます。

0(FALSE): 戻された文字列により現在のブロックが継続します。エクスポートでは、戻された文字列のみがダンプ・ファイルに書き込まれた後、ルーチンが再びコールされます。 

env

ルーチンに渡される環境ハンドル

戻り値

  • PL/SQLコードの不透明ブロックのピースを含むNULL終了文字列。

  • 長さ0(ゼロ)の文字列はそれ以上データがないことを示し、エクスポートはルーチンのコールを停止します。

使用上の注意

  • このファンクションは、静的な型のメソッドとして実装する必要があります。

  • このルーチンは、戻される文字列の長さが0(ゼロ)になるまで繰り返しコールされます。索引にPL/SQLを使用してエクスポートするメタデータがない場合は、最初のコールで空の文字列を戻す必要があります。

  • このルーチンを使用すると、インポートで実行できるように無名PL/SQLコード・ブロックを1つ以上作成できます。戻される各ブロックは、インポートによって個別に起動されます。つまり、インポート時になんらかの原因でブロックが失敗しても、以降のブロックは起動されます。したがって、依存コードは1つのブロックに取り込んでおく必要があります。各PL/SQLコード・ブロックのサイズは、BUFFERパラメータにより制御されるインポートの読取りバッファのサイズでのみ制限されます。

  • このようなPL/SQLブロックのインポート時の実行は、関連ドメイン索引の作成の一部とみなされます。したがって、これらの実行は、索引の作成と同様に、索引の基礎となる実表が正常にインポートされるかどうかと、インポートのINDEXES=Y/Nパラメータのユーザーによる設定に依存します。

  • ルーチンでは、個別のPL/SQLコード・ブロックをオープンおよびクローズするBEGIN/END文字列を渡さないようにする必要があります。これらの文字列はエクスポートにより追加され、個別の実行単位にマークが付けられます。

  • パラメータversionは、現在実行中のエクスポート・クライアントのバージョン番号です。エクスポートおよびインポートは、データベースを前の機能点リリースにダウングレードするために使用できるため、これはインポート時に検出されると予想される最小サーバー・バージョンも表します。サーバー・バージョンは、これより高くなることはあっても、低くなることはありません。

  • カートリッジ開発者はこの情報を使用して、ダンプ・ファイルに書き込む必要のある情報のバージョンを判断できます。たとえば、現行のサーバーのリリースは11.2.0.1.0であるが、処理されるエクスポートのリリースが11.1.0.1.0であるとします。カートリッジのメタデータでフォーマットがこれらのバージョン間で変更された場合、データのダンプ・ファイルへの書込みは11.1形式で行うが、データのインポート先は11.2システムとなることが認識されます。

  • エクスポートに渡された文字列に含まれるデータは、プラットフォームから完全に独立している必要があります。つまり、エクスポート・プラットフォームのエンディアンがインポート・プラットフォームとは異なる場合があるため、エンディアンを反映するバイナリ情報を含まないようにします。バイナリ情報は、16進文字列として渡し、RAWTOHEXおよびHEXTORAWを介して変換できます。

  • これらの文字列は、エクスポート・サーバーからエクスポート・クライアントのキャラクタ・セットに変換され、その形式でダンプ・ファイルに書き込まれます。インポート時には、エクスポート・クライアントのキャラクタ・セットからインポート・クライアントのキャラクタ・セットに変換され、UPIインタフェースに渡されるときには、インポート・クライアントのキャラクタ・セットからインポート・サーバーのキャラクタ・セットに変換されます。

  • インポートのFROMUSER -> TOUSERのスキーマ複製機能を使用する場合にエラーになる可能性が高いため、PL/SQLブロックの実行時にはターゲット・スキーマを指定しないでください。たとえば、次のようなプロシージャ・プロトタイプがあるとします。 

    PROCEDURE AQ_CREATE ( schema IN VARCHAR2, que_name IN VARCHAR2) ...

    インポート時にスキーマAをスキーマBに再マップした場合、これはエラーになるため使用しないでください。インポート時には、ターゲット・スキーマに接続しているものと想定できます。

  • 特定のリリースからのエクスポート・ダンプ・ファイルは、将来の全リリースでインポート可能にする必要があります。つまり、ダンプ・ファイルに書き込まれた無名PL/SQLブロック内で起動されるPL/SQLルーチンは、常にすべてがサポートされる必要があります。変換が必要な場合を検出する際に役立つように、なんらかのリリース情報をエンコーディングできます。

  • パラメータCONSISTENT=Yの場合、エクスポートは読取り専用トランザクションで動作します。この場合、エクスポート・セッションからの書込みは許可されません。したがって、このメソッドではデータベースの状態を書き込まないでください。

  • 特にインポートのIGNORE=Yパラメータを使用すると、同じダンプ・ファイルを2回以上インポートできます。したがって、このメソッドが2回以上実行される場合は、べき乗であるか少なくとも確定的なPL/SQLコードを生成する必要があります。

  • データベース・オブジェクト名の大/小文字の区別は保持する必要があります。つまり、「Foo」いう名前のオブジェクトと「FOO」という名前のオブジェクトは別のオブジェクトです。データベース・オブジェクト名は、大/小文字の区別を保持するために二重引用符("")で囲む必要があります。

エラー処理

リカバリ不能なエラーが発生すると例外が生成され、get_domain_index_metadataに伝播させた後でエクスポートに伝播させることができます。これにより、エクスポートでは現在の索引のDDLをダンプ・ファイルに作成する操作が終了し、次の索引に進みます。

インポート時には、メタデータのPL/SQLブロックの実行に失敗すると、そのメタデータの作成が索引作成の重要部分とみなされ、関連索引は作成されません。

20.1.10 ODCIIndexInsert()

1つ以上の列にドメイン索引が定義されている表に1行または一連の行が挿入されるときに起動されます。

構文 説明 
FUNCTION ODCIIndexInsert(
   ia ODCIIndexInfo, 
   rid VARCHAR2, 
   newval icoltype, 
   env ODCIEnv) 
RETURN NUMBER

1行を挿入

 
FUNCTION ODCIIndexInsert(
   ia ODCIIndexInfo,
   ridlist ODCIRidList,
   newvallist varray_of_column_type,
   env ODCIEnv) 
RETURN NUMBER

一連の行を挿入
パラメータ 説明 
ia

索引と索引付けされた列に関する情報を含みます。

 
rid

表の新規行のROWID。

 
newval

挿入される行の索引付けされた列の値。

 
ridlist

実表に挿入される行のROWIDリストを含むVARRAY(最大サイズは32767)。 

newvallist

実表の索引付けされた列に挿入される値のリストを含むVARRAY(最大サイズは32767)。これらのエントリには、ridlistのエントリとの1対1の対応関係があります。

 
env

ルーチンに渡される環境ハンドル

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error。

使用上の注意

  • このファンクションは、STATIC型のメソッドとして実装する必要があります。

  • このメソッドでは、索引データが格納される適切な表またはファイルに、渡された行または行セットに対応する索引データを挿入する必要があります。ridlist内のNULL値は、VARRAYの終わりを示します。

  • 索引タイプが定義済のWITH ARRAY DMLの場合は、行のバッチを表に挿入できます。この場合、ODCIIndexInsert()は第2の構文を使用して起動されます。それ以外の場合は、1行の構文が使用されます。

  • 索引パーティション・オブジェクト識別子ODCIIndexInfo.IndexPartitionIdenおよび実表パーティション物理識別子ODCIIndexInfo.IndexCols(1).TablePartitionIdenは、ローカル・ドメイン索引に渡されます。索引タイプには、パーティション番号を使用して新規DML構文を使用し、提供されたDATAOBJ_TO_MAT_PARTITIONファンクションを使用して、記憶域システム・パーティション表にデータを挿入する必要があります。 

    INSERT INTO SP PARTITION (
   DATAOBJ_TO_MAT_PARTITION(
      base_table_name, 
      :tab_physical_partid))
VALUES(…);

20.1.11 ODCIIndexStart()

索引付けされた列で演算子の評価を開始するために起動されます。

構文

FUNCTION ODCIIndexStart(
   sctx IN OUT <impltype>, 
   ia ODCIIndexInfo, 
   pi ODCIPredInfo, 
   qi ODCIQueryInfo, 
   strt <opbndtype>, 
   stop <opbndtype>, 
   <valargs>, 
   env ODCIEnv)
RETURN NUMBER
パラメータ 説明 
sctx(IN)

前の関連する問合せ時のコール(主演算子の前に起動される場合、対応する補助演算子など)から戻されたスキャン・コンテキストの値。それ以外の場合はNULLです。 

sctx(OUT)

次の問合せ時のコールに渡されるコンテキスト。次の問合せ時のコールはODCIIndexFetch()に対するコールです。

 
ia

索引と索引付けされた列に関する情報を含みます。

 
pi

演算子述語に関する情報を含みます。

 
qi

問合せ情報(ヒントと参照される補助演算子のリスト)を含みます。

 
strt

演算子の戻り値の範囲の開始値。データ型は演算子の戻り値と同じです。

 
stop

演算子の戻り値の範囲の終了値。データ型は演算子の戻り値と同じです。

 
valargs

演算子の起動の値引数。これらの引数の数とデータ型は、演算子の値引数と同じです。

 
env

ルーチンに渡される環境ハンドル

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error。

使用上の注意

  • ファンクションは、静的なメソッドとして実装する必要があります。

  • ODCIIndexStart()は、索引付けされた列で演算子の評価を開始するために起動されます。特に、次の条件があります。

    • 演算子の第1引数は、ドメイン索引が定義されている列です。

    • ドメイン索引(ODCIIndexInfoのパラメータで指定)の索引タイプは、現行の演算子をサポートします。

    • 演算子の他の引数はすべて、<valargs>パラメータを介して渡される値引数(リテラル)です。

  • ODCIIndexStart()メソッドでは、必要に応じて(pi引数の演算子関連情報を使用して)索引スキャンを初期化し、ODCIIndexFetch()の以降の起動準備を行う必要があります。

  • strtおよびstopパラメータとODCIPredInfoパラメータのbndflg値は、演算子の戻り値が含まれる値の範囲を指定します。

  • 演算子の戻り値の範囲は、次のように指定されます。

    • 評価される条件がop LIKE val形式の場合は、ODCIIndexPrefixMatchフラグが設定されます。この場合、開始キーには値<val>が含まれ、終了キー値は無関係です。

    • 評価される条件がop = val形式の場合は、ODCIIndexExactMatchフラグが設定されます。この場合、開始キーには値<val>が含まれ、終了キー値は無関係です。

    • 評価される条件がop > val形式の場合、startkeyには値<val>が含まれ、終了キー値はNULLに設定されます。評価される条件がop >= <val>形式の場合は、フラグODCIIndexIncludeStartも設定されます。

    • 評価される条件がop < val形式の場合、終了キーには値<val>が含まれ、開始キー値はNULLに設定されます。評価される条件がop <= val形式の場合は、フラグODCIIndexIncludeStopも設定されます。

  • コンテキスト値はOracleに(SELF引数を介して)戻すことができ、その後、次の問合せ時のコールに渡すことができます。次のコールは、評価を続行する場合はODCIIndexFetch()、評価を再起動する場合はODCIIndexStart()に対して行われます。コンテキスト値は、評価全体の状態を格納するために使用することも、状態を含むメモリーへのハンドルのみを格納するために使用することもできます。

  • 同じ索引タイプでシグネチャの異なる複数の演算子がサポートされている場合は、値引数のデータ型の組合せごとに1つずつ、複数のODCIIndexStart()メソッドを実装する必要があります。たとえば、索引タイプで次の3つの演算子がサポートされているとします。

    1. op1(number, number)

    2. op1(varchar2, varchar2)

    3. op2(number, number)

    この場合は、次の2つのODCIIndexStartルーチンを実装する必要があります。

    • ODCIIndexStart(...., NUMBER): NUMBERの値引数を持つケース1および3を処理します。

    • ODCIIndexStart(...., VARCHAR2): VARCHAR2の値引数を持つケース2を処理します。

  • qiパラメータの問合せ情報を使用すると、可能な場合はドメイン索引スキャンを最適化できます。問合せ情報には、問合せに指定されているヒントと、問合せブロックで参照される関連補助演算子のリストが含まれます。

  • 索引パーティション・オブジェクト識別子ODCIIndexInfo.IndexPartitionIdenおよび実表パーティション物理識別子ODCIIndexInfo.IndexCols(1).TablePartitionIdenは、ローカル・ドメイン索引に渡されます。索引タイプには、パーティション番号を使用して新規SQL構文を使用し、提供されたDATAOBJ_TO_MAT_PARTITION機能を使用して、記憶域システム・パーティション表の対応するパーティションの問合せを実行する必要があります。 

    SELECT FROM SP PARTITION(
   DATAOBJ_TO_MAT_PARTITION(
   base_table_name, 
   :tab_physical_partid)) 
WHERE ...;

関連項目:

20.1.12 ODCIIndexUpdate()

1つ以上の列にドメイン索引が定義されている表で1行が更新されるときに起動されます。

構文

FUNCTION ODCIIndexUpdate( 
   ia ODCIIndexInfo, 
   rid VARCHAR2, 
   oldval icoltype, 
   newval icoltype, 
   env ODCIEnv)
RETURN NUMBER
パラメータ 説明 
ia

索引と索引付けされた列に関する情報を含みます。

 
rid

更新される行のROWID。

 
oldval

索引付けされた列の更新前の値。データ型は索引付けされた列のデータ型と同じです。

 
newval

索引付けされた列の更新後の値。データ型は索引付けされた列のデータ型と同じです。

 
env

ルーチンに渡される環境ハンドル

戻り値

正常終了した場合はODCIConst.Success、エラーの場合はODCIConst.Error。

使用上の注意

  • このファンクションは、static型のメソッドとして実装する必要があります。

  • このメソッドでは、更新された行の索引データを格納する表またはファイルを更新する必要があります。

  • SQLのUPDATE文の他にも、様々なWRITEインタフェースを介してLOB値を更新できます(『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照)。ドメイン索引がLOB列またはLOB属性を含むオブジェクト型に対して定義されている場合は、1回以上の書込み操作の後でLOBロケータが暗黙的または明示的にクローズされるときに、ODCIIndexUpdateルーチンがコールされます。

  • 索引パーティション・オブジェクト識別子ODCIIndexInfo.IndexPartitionIdenおよび実表パーティション物理識別子ODCIIndexInfo.IndexCols(1).TablePartitionIdenは、ローカル・ドメイン索引に渡されます。索引タイプには、パーティション番号を使用して新規DML構文を使用し、提供されたDATAOBJ_TO_MAT_PARTITION()ファンクションを使用して、記憶域システム・パーティション表のデータを更新する必要があります。 

    UPDATE SP PARTITION 
   (DATAOBJ_TO_MAT_PARTITION(
      base_table_name, :tab_physical_partid)) 
   VALUES(…) SET val = :newval WHERE rowid + :rowid;

20.1.13 ODCIIndexUpdPartMetadata()

パーティション・メンテナンス操作時に起動されます。パーティション・メンテナンス操作を正しく反映するために、索引タイプのメタデータ表をパッチします。

構文

FUNCTION ODCIIndexUpdPartMetadata(
   ia ODCIIndexInfo,
   palist ODCIPartInfoList,
   env ODCIEnv)
パラメータ 説明
ia

ドメイン索引に関する情報(パーティション固有の情報には含まれません)
palist

削除または追加されたパーティションに関する情報
env

環境ハンドル

使用上の注意

  • このメソッドは、STATIC型のメソッドとして実装する必要があります。

  • 索引タイプがSYSTEM MANAGEDアプローチで指定されている場合、このメソッドは、パーティション管理操作時にこの索引タイプのローカル・ドメイン索引で起動されます。

  • SQL DDLsはこのメソッドでは使用できません。

  • 索引タイプは、必要に応じてパーティションにマッピングされたメタデータを更新する必要があります。

  • palist引数には、削除または追加が必要なパーティションのリストが含まれます。たとえば、実表操作がALTER TABLE SPLIT PARTITTION P1 INTO P11 AND P12である場合、palistには3つのパーティションに関する情報(P1(削除)、P11(追加)およびP12(追加))と、それらの索引パーティション名および索引パーティション・オブジェクト識別子が含まれます。

  • ODCIIndexUpdPartMetadata()コールはエラーを発生または戻す場合、実表でのパーティション管理操作はロールバックされます。

20.1.14 ODCIIndexUtilCleanup()

ODCIIndexUtilGetTableNames()により作成された一時状態をクリーン・アップします。

構文

FUNCTION ODCIIndexUtilCleanup (
   context  PLS_INTEGER)
パラメータ 説明 
context

特定の索引の状態情報を一意に識別するために、ODCIIndexUtilGetTableNames() により作成される数値。

使用上の注意

  • プロシージャは、静的な型のメソッドとして実装する必要があります。

  • ODCIIndexUtilCleanup()は、パラメータcontextに関連付けられている一時状態を削除します。

  • ODCIIndexUtilCleanup()により発生した例外は、コール元では無視されます。

関連項目:

20.1.15 ODCIIndexUtilGetTableNames()

ドメイン索引のセカンダリ表のエクスポート/インポートが必要かどうかを判別します。デフォルトでは、ドメインのセカンダリ・オブジェクトはインポートまたはエクスポートされません。ただし、このインタフェースおよびODCIIndexUtilCleanup()が存在する場合、これらが起動されます。

このインタフェースが実装されている場合、アプリケーションでこれを起動して、トランスポータブル表領域を操作することもできます。

構文

FUNCTION ODCIIndexUtilGetTableNames(
   ia sys.odciindexinfo, 
   read_only PLS_INTEGER, 
   version varchar2, 
   context OUT PLS_INTEGER)
RETURN BOOLEAN
パラメータ 説明 
ia

索引と索引付けされた列に関する情報を含みます。

 
read_only

このメソッドを含むトランザクションが読取り専用の場合は、書込み禁止を意味する1を指定します。それ以外の場合は0(ゼロ)を指定します。

 
version

コールを行うエクスポートのバージョン。

 
context

ODCIIndexUtilGetTableNames()とODCIIndexUtilCleanup()の間にオープン状態で保持される状態のクリーン・アップを容易にするために、ODCIIndexUtilCleanup()で使用される一意の番号。

戻り値

ドメイン索引のセカンダリ表をエクスポート/インポートする必要がある場合はTRUE。それ以外の場合はFALSEが戻されます。

使用上の注意

  • このファンクションは、静的な型のメソッドとして実装する必要があります。

  • このファンクションでは、セカンダリ表のエクスポート/インポートが必要かどうかに基づいてTRUEまたはFALSEを戻す必要があります。

  • このファンクションでは、セカンダリ表のトランスポートが必要かどうかに基づいてTRUEまたはFALSEを戻す必要があります。表以外のセカンダリ・オブジェクトは、トランスポータブル表領域に関係しません。ODCIIndexInfo.IndexInfoFlagsでODCI_INDEX_TRANS_TBLSPCビットが設定されている状態でODCIIndexCreate()メソッドが起動される場合は、インポート側で再作成する必要があります。

関連項目: