1. Oracle GoldenGate Microservicesドキュメント
  2. 管理
  3. Oracle GoldenGateマクロによる作業の簡略化および自動化

Oracle GoldenGateマクロによる作業の簡略化および自動化

パラメータ・ファイルでOracle GoldenGateマクロを使用すると、パラメータ、コマンドおよび変換関数を構成して再利用できるため、一般的なタスクを実行する際に入力する必要のあるテキストの量を減らすことができます。マクロとは、格納されている処理ステップのセットをOracle GoldenGateパラメータ・ファイルから呼び出すことを可能にする組込みの自動化ツールです。マクロには、頻繁に使用するパラメータ文の単純なセットを含めることも、パラメータ置換、計算または変換が連続する複雑な組合せを含めることもできます。1つのマクロから他のマクロを呼び出すことができます。よく使用するマクロをライブラリに格納すると、個別にマクロを呼び出さずにそのライブラリを呼び出すことができます。

Oracle GoldenGateマクロは、次のパラメータ・ファイルと連携して動作します。

  • DEFGEN

  • Extract

  • Replicat

マクロの使用は、次の2つのステップで行います。

マクロの定義

マクロの呼出し

トピック:

親トピック: 管理

マクロの定義

Oracle GoldenGateマクロを定義するには、パラメータ・ファイルでMACROパラメータを使用します。MACROでは、必要な入力パラメータを定義し、マクロにより実行する処理を定義します。

構文 

MACRO #macro_name
PARAMS (#p1, #p2 [, ...])
BEGIN
macro_body
END;

表11-3 マクロ定義の引数

引数 説明 
MACRO

必須。Oracle GoldenGateマクロ定義の開始を指定します。

 
#macro_name

マクロ名。マクロおよびパラメータ名は、マクロ文字で開始する必要があります。デフォルトのマクロ文字は、番号記号(#)です(#macro1や#param1など)。

マクロまたはパラメータ名は、文字や数字(あるいはその両方)を含む1語にできます。アンダースコア文字(_)やハイフン(-)などの特殊文字を使用できます。マクロ名の例として、#mymacro、#macro1、#macro_1、#macro-1、#macro$などがあります。パラメータ名の例として、#sourcecol、#s、#col1、#col_1などがあります。

解析エラーを回避するため、マクロ名の最初の文字としてマクロ文字を使用することはできません。たとえば、##macroは無効です。必要な場合、MACROCHARパラメータを使用してマクロ文字を変更できます。Oracle GoldenGateリファレンスfor Windows and UNIXを参照してください。

マクロ名とパラメータ名では、大/小文字は区別されません。引用符内のマクロ名またはパラメータ名は、無視されます。

 
PARAMS (#p1, #p2)

入力パラメータのオプション定義。パラメータ名のカンマ区切りリストを指定して、カッコで囲みます。入力値を置換するマクロ本体で、各パラメータを参照する必要があります。各パラメータを個別の行にリストすると読みやすくなります(必ず開きカッコと閉じカッコを使用してパラメータ・リストを囲んでください)。詳細は、「パラメータを含むマクロの呼出し」を参照してください。 

BEGIN

マクロ本文を開始します。マクロ本文の前に指定する必要があります。

 
macro_body

マクロ本体。本体は、マクロにより実行される関数を定義する構文の文です。マクロ本体には、次のタイプの文を含めることができます。

  • 次のような単純なパラメータ文:

    COL1 = COL2

  • 次のようなパラメータ置換を含む複雑なパラメータ文:

    MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS);

  • 次のような他のマクロの呼出し:

    #colmap (COL1, #sourcecol)
 
END;

マクロ定義を終了します。定義の末尾にはセミコロンが必要です。

パラメータを含むマクロ定義の例を次に示します。この場合、マクロでは、所有者、表およびKEYCOLS列の名前に解決される入力パラメータを含むMAP文のベース構文を提供することによって、オブジェクトおよび列のマッピングのタスクを簡略化します。 

MACRO #macro1  
PARAMS ( #o, #t, #k )  
BEGIN  
MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS); 
END;

パラメータを定義していないマクロの例を次に示します。頻繁に使用するパラメータのセットを実行します。

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

親トピック: Oracle GoldenGateマクロによる作業の簡略化および自動化

マクロの呼出し

マクロを呼び出すには、パラメータ・ファイル内のマクロの実行場所に次の構文を使用します。

構文 

[target =] macro_name (val[, ...])
[target =] macro_name (val | {val, val, ...}[, ...])

表11-4 マクロを呼び出すための構文要素

引数 説明

target =

オプション。マクロ処理の結果の割当て先またはマップ先のターゲットを指定します。たとえば、targetを使用して、COLMAP文でターゲット列を指定できます。次に示す#make_dateマクロの呼出しでは、列DATECOL1がターゲットであり、マクロ結果にマップされます。 

DATECOL1 = #make_date (YR1, MO1, DAY1)

ターゲットがない場合、#make_dateを呼び出すための構文は次のとおりです。 

#make_date (YR1, MO1, DAY1)

macro_name

呼び出されるマクロの名前(たとえば: #make_date)。

( val[, ...])

パラメータ入力値。このコンポーネントは、マクロがパラメータを定義しているかどうかにかかわらず必須です。マクロがパラメータを定義している場合、MACROパラメータ内のパラメータ定義に対応する順序で入力値のカンマ区切りリストを指定し、リストをカッコで囲みます。マクロがパラメータを定義していない場合、中に何もない開きカッコと閉じカッコを指定します。

( val | {val, val, ...} )[, ...]

パラメータ入力値。このコンポーネントは、マクロがパラメータを定義しているかどうかにかかわらず必須です。マクロがパラメータを定義している場合、MACROパラメータ内のパラメータ定義に対応する順序で入力値のカンマ区切りリストを指定し、リストをカッコで囲みます。複数の値を1つのパラメータに渡すには、それらをカンマで区切り、リストを中カッコで囲みます。マクロがパラメータを定義していない場合、中に何もない開きカッコと閉じカッコを指定します。

マクロを呼び出す構文の詳細は、次のトピックを参照してください。

親トピック: Oracle GoldenGateマクロによる作業の簡略化および自動化

パラメータを含むマクロの呼出し

パラメータを含むマクロを呼び出すには、call文で、マクロの実行時にこれらのパラメータを置換する入力値を指定する必要があります。

マクロ・パラメータの有効な入力は、マクロ文字(デフォルトは#)で始まる次のいずれかです。

  • プレーン・テキストまたは引用テキストの単一値(#macro (#name, #address, #phone)、#macro (#"name", #"address", #"phone")など)。

  • 中カッコで囲まれたカンマ区切りの値リスト(#macro1 (SCOTT, DEPT, {DEPTNO1, DEPTNO2, DEPTNO3})など)。指定されたパラメータの値のブロックを置換できるようにすると、マクロ定義とOracle GoldenGate構成のユーザビリティの柔軟性が向上します。

  • 他のマクロの呼出し(#macro (#mycalc (col2, 100), #total)など)。この例では、入力値がcol2および100で#mycalcマクロが呼び出されます。

Oracle GoldenGateでは、次のルールに従ってマクロ本体のパラメータ値が置換されます。

  1. マクロ・プロセッサは、マクロ本体を読み取って、PARAMS文に指定されたパラメータ名のインスタンスを検索します。

  2. パラメータ名が出現するたびに、呼出し時に指定された対応するパラメータ値が置換されます。

  3. パラメータ名がPARAMS文に出現しない場合、マクロ・プロセッサは、その項目が別のマクロの呼出しになっているかどうかを評価します。(「マクロからの他のマクロの呼出し」を参照)。呼出しが成功した場合、ネストされたマクロが実行されます。失敗した場合、マクロ全体が失敗します。

例11-6 パラメータを使用したMAP文の移入

次のマクロ定義は、解決が必要な3つのパラメータを指定しています。これらのパラメータは、MAP文の表所有者名(パラメータ#o)、表名(パラメータ#t)およびKEYCOLS列名(パラメータ#k)を置換します。 

MACRO #macro1  PARAMS ( #o, #t, #k )  BEGIN  MAP #o.#t, TARGET #o.#t, KEYCOLS (#k), COLMAP (USEDEFAULTS); END;

MAP文の表にKEYCOLS列が1つのみ必要である場合、次の構文を使用して#macro1を呼び出すことができます。この構文では、1つのみの値で#kパラメータを解決できます。 

#macro1 (SCOTT, DEPT, DEPTNO1)

2つのKEYCOLS列が必要な表のマクロを呼び出すには、次のように中括弧を使用して、列名に必要な両方の値を囲みます。 

#macro1 (SCOTT, DEPT, {DEPTNO1, DEPTNO2})

DEPTNO1値およびDEPTNO2値は、#tパラメータを解決するための1つの引数として渡されます。この方法で、中括弧の内側に追加の値を使用して、3つ以上のKEYCOLSのある表を処理できます。

例11-7 マクロを使用した変換の実行

この例では、マクロで#year、#monthおよび#dayの各パラメータを定義して、独自仕様の日付書式を変換します。 

MACRO #make_date
PARAMS (#year, #month, #day)
BEGIN
@DATE ('YYYY-MM-DD', 'CC', @IF (#year < 50, 20, 19), 'YY', #year, 'MM', #month, 'DD', #day)
END;

マクロはCOLMAP句で呼び出されます。 

MAP sales.acct_tab, TARGET sales.account,
COLMAP
(
targcol1 = sourcecol1,
datecol1 = #make_date(YR1, MO1, DAY1),
datecol2 = #make_date(YR2, MO2, DAY2)
);

マクロは次のように展開されます。

MAP sales.acct_tab, TARGET sales.account,
COLMAP
(
targcol1 = sourcecol1,
datecol1 = @DATE ('YYYY-MM-DD', 'CC', @IF (YR1 < 50, 20, 19),'YY', YR1, 'MM', MO1, 'DD', DAY1),
datecol2 = @DATE ('YYYY-MM-DD', 'CC', @IF (YR2 < 50, 20, 19),'YY', YR2, 'MM', MO2, 'DD', DAY2)
);

親トピック: マクロの呼出し

入力パラメータのないマクロの呼出し

入力パラメータのないマクロを呼び出すには、call文で入力値のない開きカッコと閉じカッコ(#macro ())を指定します。

次のマクロは、入力パラメータなしで定義されています。本体には頻繁に使用するパラメータが含まれています。

MACRO #option_defaults
BEGIN
GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
END;

このマクロは次のように呼び出されます。

#option_defaults ()
IGNOREUPDATES
MAP owner.srctab, TARGET owner.targtab;

#option_defaults ()
MAP owner.srctab2, TARGET owner.targtab2;

マクロは次のように展開されます。

GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
IGNOREUPDATES
MAP owner.srctab, TARGET owner.targtab;

GETINSERTS
GETUPDATES
GETDELETES
INSERTDELETES
MAP owner.srctab2, TARGET owner.targtab2;

親トピック: マクロの呼出し

マクロからの他のマクロの呼出し

マクロから他のマクロを呼び出すには、次のようなマクロ定義を作成します。この例では、#make_dateマクロが#assign_dateマクロ内にネストされ、#assign_dateの実行時に呼び出されます。

ネストされたマクロは、ベース・マクロに定義された同じパラメータの全部またはサブセットを定義している必要があります。つまり、ベース・マクロの呼出し時の入力値が両方のマクロのパラメータに解決される必要があります。

次では、#assign_dateを定義しています。 

MACRO #assign_date
PARAMS (#target_col, #year, #month, #day)
BEGIN
#target_col = #make_date (#year, #month, #day)
END;

次では、#make_dateを定義しています。このマクロでは、2桁の入力日付の前に世紀値(19または20)を付ける必要があるかどうかを最初に判別した後、4桁の年を含む日付書式を作成します。#make_dateのPARAMS文には、#assign_dateマクロ内のパラメータのサブセットが含まれています。 

MACRO #make_date
PARAMS (#year, #month, #day)
BEGIN
@DATE ('YYYY-MM-DD', 'CC', @IF (#year < 50, 20, 19), 'YY', #year, 'MM', #month, 'DD', #day)
END;

次の構文は#assign_dateを呼び出します。 

#assign_date (COL1, YEAR, MONTH, DAY)

前の入力値および埋込み#make_dateマクロを想定すると、マクロは次のように展開されます。 

COL1 = @DATE ('YYYY-MM-DD', 'CC', @IF (YEAR < 50, 20, 19),'YY', YEAR, 'MM', MONTH, 'DD', DAY)

親トピック: Oracle GoldenGateマクロによる作業の簡略化および自動化

マクロ・ライブラリの作成

1つ以上のマクロを含むマクロ・ライブラリを作成できます。マクロ・ライブラリを使用すると、マクロを1回定義するだけで、そのマクロを多くのパラメータ・ファイルで使用できます。

マクロ・ライブラリを作成する手順

  1. テキスト・エディタで新規ファイルを開きます。

  2. 必要に応じて、コメント行を使用してライブラリを説明します。

  3. 次の構文を使用して、各マクロを定義します。
    MACRO #macro_name
PARAMS (#p1, #p2 [, ...])
BEGIN
macro_body
END;

  4. ファイルを次の形式でOracle GoldenGateディレクトリのdirprmサブディレクトリに保存します。 

    filename.mac

    説明:

    filenameは、ファイルの名前です。.mac拡張子によって、ファイルをマクロ・ライブラリとして定義します。

次のdatelibというサンプル・ライブラリには、#make_dateおよび#assign_dateという2つのマクロが含まれます。 

-- datelib macro library
--
MACRO #make_date
PARAMS (#year, #month, #day)
BEGIN
@DATE ('YYYY-MM-DD', 'CC', @IF (#year < 50, 20, 19), 'YY', #year, 'MM', #month, 'DD', #day)
END;

MACRO #assign_date
PARAMS (#target_col, #year, #month, #day)
BEGIN
#target_col = #make_date (#year, #month, #day)
END;

マクロ・ライブラリを使用するには、パラメータ・ファイルの先頭でINCLUDEパラメータを使用します。次のサンプルのReplicatパラメータ・ファイルを参照してください。 

INCLUDE /ggs/dirprm/datelib.mac
REPLICAT rep
ASSUMETARGETDEFS
USERIDALIAS ogg
MAP fin.acct_tab, TARGET fin.account;

パラメータ・ファイルに長いマクロ・ライブラリが含まれる場合、NOLISTパラメータを使用して、ExtractまたはReplicatのレポート・ファイルで各マクロがリスト表示されることを抑止できます。リスト表示の有効化と無効化を切り替えるには、パラメータ・ファイル内またはマクロ・ライブラリ・ファイル内の任意の場所にLISTパラメータおよびNOLISTパラメータを配置します。次の例では、NOLISTによって、hugelibマクロ・ライブラリに含まれる各マクロのリスト表示を抑止します。INCLUDE文の後にLISTを指定することで、レポート・ファイルを通常のリスト表示に戻します。 

NOLIST
INCLUDE /ggs/dirprm/hugelib.mac
LIST
INCLUDE /ggs/dirprm/mdatelib.mac
REPLICAT REP

親トピック: Oracle GoldenGateマクロによる作業の簡略化および自動化

マクロ展開のトレース

CMDTRACEパラメータを使用して、マクロ展開をトレースできます。CMDTRACEを有効化すると、マクロ展開ステップがExtractまたはReplicatのレポート・ファイルに表示されます。

構文 

CMDTRACE [ON | OFF | DETAIL]

説明:

  • ONは、トレースを有効化します。

  • OFFは、トレースを無効化します。

  • DETAILは、マクロ展開の詳細表示を生成します。

次の例では、トレースが#testmacの呼出し前に有効化され、マクロの実行後に無効化されます。 

REPLICAT REP
MACRO #testmac
BEGIN
COL1 = COL2,
COL3 = COL4,
END;
...
CMDTRACE ON
MAP test.table1, TARGET test.table2,
COLMAP (#testmac);
CMDTRACE OFF

親トピック: Oracle GoldenGateマクロによる作業の簡略化および自動化