7 Configuring Custom Operations

User exits expect records to have a specific format. For example, user exits expect:

• Deletes, inserts, and updates to appear in the buffer as full record images

• Non-compressed data to have no offset or length preceding data

• Compressed Enscribe and SQL updates to both have the following format:

  (offset)(length)(value)(offset)(length)(value)(. . .)
  

where

• (offset) is the offset into the Enscribe record of the data fragment that changed.

• (length) is the length of the fragment.

• (value) is the data. Fragments can span field boundaries, so full fields are not always retrieved (unless compression is off or FETCHCOMPS is used).

• Enscribe has an I/O type of 11; SQL has an I/O type of 15. All other I/O types for deletes, inserts, and updates are in non-compressed format.

  Note:

  The above record formats only apply to data sourced from an HP NonStop system.

• Binding User Exits in Native Mode
  

Once you have bound your user exit into Replicat to create a new object, you will want to debug your new code. If your Replicat is in TNS mode, use the following command:

TACL> RUN replicat_name/in $vol.subvol.parameter_name, name $xxxx, lib/

This decouples your Replicat from our licensed PRIVLIB and prevents errors.

If you are running the native form of Replicat, you may debug as usual.

Two sample user exits are supplied with Oracle GoldenGate: DEMOXCOB (written in COBOL) and DEMOXC (written in C programming language). You can use these exits as skeletons for your own routines.

DEMOXCOB illustrates several applications of user exits. DEMOXCOB responds to Extract events and performs several tasks, including:

• Mapping data from Enscribe to SQL formats

• Writing a record to an attention log file under certain conditions

• Rejecting records with invalid codes

• Accumulating and outputting order totals

• Writing archive records when delete records are encountered

DEMOXC provides an example of how to write a user exit that responds to Replicat events. DEMOXC maps records from a source to a target layout and creates a summary transaction record for each delivered transaction.

Create an Oracle GoldenGate macro with the MACRO statement.

MACRO #macro_name
PARAMS ([param1] [, param2] [...])
BEGIN
macro_body

END;

MACRO #macro_name

PARAMS ([param1] [, param2] [...])

BEGIN

macro_body

COL1 = COL2

COL1 = #val2

#colmap(COL1, #sourcecol)

END;

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;

1. Parameter names must begin with the # macro character, such as #param1. (You can define a different macro character. See "Changing the Macro Character" for details.) When the macro is run, the invocation must include a parameter value for each parameter named in the PARAMS statement. Parameter names are not case-sensitive.

   When the macro processor encounters a parameter with the # prefix that is not in the parameter list, the processor determines whether it is an invocation of another macro. Invocations of other macros also begin with the # character, followed by parentheses enclosing a list of parameter values that are separated by commas.

2. Besides the leading # character, valid parameter characters are alphanumeric and can include the underscore character (_).
3. If a parameter name or macro is encountered within quotation marks, it is treated as text and ignored.

Anything in the parameter file that begins with the # macro character is assumed to be either a macro or macro parameter. This rule does not apply to text within quotation marks; quoted text is ignored.

If the macro character conflicts with a specification in the parameter file, such as table names that include the # character, you specify a different macro character with the MACROCHAR parameter. In the following example, $ is defined as the macro character, rather than #.

MACROCHAR $
MACRO $mymac
PARAMS ($p1)
BEGIN
col = $p1
END;

The MACROCHAR can only be specified once, and must be specified before any macros are defined.

To run a macro, place the run statement in the parameter file at every place you want the process to occur.

[target =] #macro_name ([value1] [, value2] [, . . .])

target =

DATECOL1 = #make_date(YR1, MO1, DAY1)

#macro_name

([value1] [, value2] [, . . .])

my_col_1
"your text here"
#mycalc (col2, 100)
#custdate (#year, #month, #day)
#custdate (#getyyyy (#yy), #month, #day)

If the macro does not specify parameters, the parameter value list is empty, but the parentheses are still required. For example:

#no_params_macro ()

This section shows you sample macros for implementing multiple uses of a statement and invoking another macro.

• Implementing Multiple Uses of a Statement
  
• Consolidating Multiple Commands
  

You can create libraries of macros to be included in different parameter files.

• Sample Macro Libraries
  
• Suppressing Report File Listing
  
• Tracing Parameter Expansion
  

For Replicat PCREATE must be combined with the relinkable PRIVLIB to build a combined library that will include intercepts to create a high pin TACL.

The following example combines the PCREATE intercept object, PCREATEO, with the relinkable (R) native mode (N) PRIVLIB to create a new user library named PRIVLIBX.

eld -ul -o PRIVLIBX PRIVLIBR PCREATEO -set interpose_user_library on
FUP LICENSE PRIVLIBX
eld -change libname $DATA.GGS1000.PRIVLIBX REPLICAT

In the last step the new PRIVLIBX is assigned as Replicat's library. The library name must be fully qualified as shown in the example.

Extract and GGSCI can use a combined library, such as created in the above example, or PCREATE can be linked into a user library, such as the PCREATEL in the example below.

eld -ul -o PCREATEL PCREATEO -set interpose_user_library_on

Enter the DEFINE for TACL, =GGS_TACL_PROGRAM, in GLOBALS if it is to be the same for all Extract, Replicat, and GGSCI programs for that Oracle GoldenGate instance. If it is more specific, include it in the Extract or Replicat parameter file. Alternatively it can also be added to TACLLOC or to TACLCSTM.

The following example DEFINE assumes you first FUP DUP $SYSTEM.SYSnn.TACL to $SYSTEM.SYSnn.TACLHP, turn HighPin ON, then add the DEFINE.

ADD DEFINE =GGS_TACL_PROGRAM, CLASS MAP, FILE $SYSTEM.SYSnn.TACLHP