IIDR CHCCLP Scripting

1 © 2015 IBM Corporation

Information Management Software

© IBM Corporation 2015. All Rights Reserved.

Disclaimer: Information regarding potential future products is intended to

outline our general product direction and it should not be relied on in making a
purchasing decision. The information mentioned regarding potential future
products is not a commitment, promise, or legal obligation to deliver any
material, code or functionality. Information about potential future products may
not be incorporated into any contract. The development, release, and timing of
any future features or functionality described for our products remains at our
sole discretion.

2 © 2015 IBM Corporation

Information Management Software

Management Console Scripting Support

• Existing CDC API required Java programming skills, advanced
understanding of the product and a high learning curve
• New simpler CDC command line processor (CHCCLP) allows
users to configure and monitor replication environment that:
• Closely resembles how the Management Console tasks work
(connect to datastores, create subscriptions, map tables, control
and monitor subscription status/latency/activity, etc)
• Is easier to learn
• Provides extensive documentation and script samples
• Performs activities at a higher level
• New scripting language allows users to automate actions using
either:
• Interactive command prompt
• Command-line batch execution application
• Embedded into a Java program interface

3 © 2015 IBM Corporation

Information Management Software

Management Console Scripting Support

• Uses of CHCCLP
• Automating the configuration and mapping of many
tables that are otherwise onerous to do manually using
Management Console
• Ability to script the export and import functionality that
was previously unsupported
• Manage replication of large environments
• Minimize tedious, manual user intervention

4 © 2015 IBM Corporation

Information Management Software

Management Console Scripting Support

• Supported Platforms
• Installs with Management Console on Windows, and Access
Server on Windows, Linux or Unix.
• Installs on z/OS as part of the CDC Technology component
(InfoSphere CDC for z/OS) into the HFS on the OMVS Unix
shell.
• On z/OS, runs from OMVS terminal and as a batch job under
BPXBATCH program environment.
• Supported CDC Engines and Versions
• CDC 10.2 engines on z/OS, Linux, UNIX and Windows.
• CDC i 11.3.0 version
• EventServer, and Classic CDC are not supported.

5 © 2015 IBM Corporation

Information Management Software

Syntax
• All commands follow a consistent pattern:
verb object parameter1 value1 parameter2 value2;
add column encodings
clear column mappings
connect/disconnect data translation
delete database schemas
describe database tables
end/start datastore events
exit/quit datastore
export/import/promote datatypes
filter derived column
flag refresh encodings
help index columns
list latency thresholds
lock/unlock journal control fields
map/unmap refresh order
mark capture point replication
modify replication table
monitor replication tables
park server
promote source column
readd source columns
reassign subscription
remove subscription events
run table mapping
select
show

6 © 2015 IBM Corporation

Information Management Software

Syntax
• Verb/object/parameter names and “key”-based parameter values
are case-insensitive.
• CDC/database object names are case-sensitive (e.g. a
subscription name or a database table name).
• Valid syntax requires both the parameter name and its value.
• Parameters can be:
• required or optional
• can provide a default value
• can provide a set of expected values

7 © 2015 IBM Corporation

Information Management Software

Syntax
• A parameter value with any of these characters can be entered
without quotes:
• A-Z a-z 0-9 _ @ * . % -

• If the values contain any other characters, the value must be

surrounded with double quotes or single quotes.
• add subscription name TEST description “This is a test”;

• If a parameter value is an “empty string”, use two double quotes

to represent the value:
• connect server username daniel password “”;

8 © 2015 IBM Corporation

Information Management Software

Concept of context
• Understanding Context
• At any given time CHCCLP can only be connected to one Access
Server. The context defines the source datastore, target datastore,
subscription and table mapping currently referenced through that
Access Server
• The context is similar to a selection in Management Console
• While manipulating a particular function it is important to first establish
the proper context. For example when you are configuring a derived
expression you must first set up the context to reference the correct
table mapping, subscription, datastores, and Access Server.
• The context can be viewed at any time using command ‘show
context’
CONTEXT CURRENT OBJECT
------------------ ----------------------------------
Access Server localhost@10101
Source Datastore DS1Target
Datastore DS2
Subscription SUB1
Table Mapping CDC.TABLE_1 - CDC.TABLE_1

9 © 2015 IBM Corporation

Information Management Software

Interactive mode
• Provides an interactive
environment to execute
commands

Handy help for syntax

and examples

Commands are grouped

by category for quick
lookup

10 © 2015 IBM Corporation

Information Management Software
Command-line batch mode
• The commands you would normally
enter in the interactive mode can be
saved into a file and run in a batch
script.
• To develop the script the commands
can be entered in the interactive mode
to test and then saved using command
‘save session’ and later
modified/enhanced.
• The scripts can utilize substitution
variables by using %variableName%
place holders that are passed in as
arguments.
• Scripts are executed by passing the
filename
• E.g CHCCLP –f script.txt
11
Create a script file containing a series of commands.
script.txt:
chcclp session set to cdc;
connect server
hostname %hostname% port %port%
username %username% password %password;
connect datastore name %source% context source;
connect datastore name %target% context target;
...
disconnect server;
exit;
Open an operating system command prompt and issue the
following command, providing variableName:value
arguments for each substitution variable in the script:
CHCCLP –f script.txt hostname:myserver
port:10101 username:user1 password:pass1
source:ds1 target:ds2
© 2015 IBM Corporation
Information Management Software

Embedded mode
• CHCCLP commands can be embedded in a Java program with similar
calls as interactive or batch mode.
• Java programming would be useful in cases where additional ‘logic’ is
required such as conditional statements, loops, etc.
• Results of the commands can also be manipulated in Java objects such
as result lists, tables, etc.

12 © 2015 IBM Corporation

Information Management Software

CHCCLP – Embedded Sample 1

• The following example connects to Access Server and two datastores, creates a subscription,
maps three tables, and starts replication.
public class Sample1
{
public static void main(String[] args)
{
EmbeddedScript script = new EmbeddedScript();
try
{
script.open();
script.execute("connect server username user1 password pass1");
script.execute("connect datastore name DS1 context source");
script.execute("connect datastore name DS2 context target");
script.execute("add subscription name SUB1");

String mapping = "add table mapping sourceSchema {0} sourceTable {1} targetSchema {2} targetTable {3}";
script.execute(MessageFormat.format(mapping, new Object[] { "USER1", "TABLE_1", "USER1", "TABLE_1" }));
script.execute(MessageFormat.format(mapping, new Object[] { "USER1", "TABLE_2", "USER1", "TABLE_2" }));
script.execute(MessageFormat.format(mapping, new Object[] { "USER1", "TABLE_3", "USER1", "TABLE_3" }));
script.execute("start mirroring");
script.execute("disconnect server");
}
catch (EmbeddedScriptException e)
{
System.out.println(e.getResultCodeAndMessage());
}
finally
{
script.close();
}
}
}

13 © 2015 IBM Corporation

Information Management Software

CHCCLP – Interactive Sample 1

• The following session shows the same sample in the interactive prompt.

Repl > connect server username user1 password pass1;

Repl > connect datastore name DS1 context source;
Repl > connect datastore name DS2 context target;
Repl > add subscription name SUB1;
Repl > add table mapping sourceSchema USER1 sourceTable TABLE_1 targetSchema USER1 targetTable TABLE_1;
Repl > add table mapping sourceSchema USER1 sourceTable TABLE_2 targetSchema USER1 targetTable TABLE_2;
Repl > add table mapping sourceSchema USER1 sourceTable TABLE_3 targetSchema USER1 targetTable TABLE_3;
Repl > start mirroring;
Repl > disconnect server;
Repl > exit;

14 © 2015 IBM Corporation

Information Management Software

CHCCLP – Embedded Sample 2

• The following example connects to Access Server and two datastores, gets the list of subscriptions
with monitor summary and starts any that are not currently mirroring.

import com.ibm.replication.cdc.scripting.EmbeddedScript; String subscription;

import com.ibm.replication.cdc.scripting.EmbeddedScriptException; String state;
import com.ibm.replication.cdc.scripting.Result; for (int row = 0, rows = table.getRowCount(); row < rows; row++)
import com.ibm.replication.cdc.scripting.ResultStringTable;
{
subscription = table.getValueAt(row, "SUBSCRIPTION");
public class Sample2
{ state = table.getValueAt(row, "STATE");
public static void main(String[] args) if (state.equals("Inactive"))
{ {
EmbeddedScript script = new EmbeddedScript(); System.out.println("Starting " + subscription);
try script.execute("start mirroring name " + subscription);
{ }
script.open(); }
script.execute("connect server username user1 password pass1");
}
script.execute("connect datastore name DS1 context source");
script.execute("disconnect server");
script.execute("connect datastore name DS2 context target");
script.execute("monitor replication"); }
catch (EmbeddedScriptException e)
Result result = script.getResult(); {
if (result.getType() == Result.TABLE) System.out.println(e.getResultCodeAndMessage());
{ }
ResultStringTable table = (ResultStringTable) result; finally
{
// Prints the table to the console window.
script.close();
table.display(System.out);
}
}

Traverse result set and add

conditional logic

15 © 2015 IBM Corporation

Information Management Software

CHCCLP Support Added in IIDR 11.3.0

• Support for CDC i
• Support for almost all operations
• Subscription status is available through the ‘monitor replication’ command. No
additional monitoring information (including performance metrics) are available
• Promotion is not supported
• Support for new FlexRep target engine
• Notification configuration support
• System parameter configuration support
• Support for generating a performance snapshot
• The command writes performance snapshots until you hit an endtime or # of
collection points export subscription performance snapshot
[name] Specifies the name of the subscription. If a name is not
provided, the subscription identified as the context will be used
folder Specifies the output folder where the statistics snapshot will be saved
[endTime] Statistics will be collected at each interval until the time is exceeded.
Specifies the end time using “yyyyMMddHHmm”
[count] Specifies the number of times to request statistics
Valid range: 1 to 2147483647
[wait] Specifies the number or seconds to wait between sending each statistic
request
Valid range: 1 to 2147483647
Default: 5
16 © 2015 IBM Corporation
Information Management Software

CHCCLP Support Added in IIDR 11.3.3

• Generates a sample CHCCLP script
based on the definition of a
subscription in Management
Console

• Allows users to define a

subscription in Management
Console and then generate a
sample CHCCLP script to re-create
the subscription, make copies, etc.

• Supports all functionality available in

CHCCLP

17 © 2015 IBM Corporation

Information Management Software

Sample CHCCLP script generation

• Simplifies learning CHCCLP by generating
a well-formed and well-documented
complete sample

• Optionally excludes unnecessary syntax or

parameters

• Clearly identifies functionality that is not

supported and provides hyperlink access
to markers in the script that require user
modification

• Provides syntax highlighting of a script

• Allows in-place editing of the script

© 2015 IBM Corporation

Information Management Software

Sample CHCCLP Script generation…

• Allows the user to save the script

to a file or execute it in-place

• Provides the same execution

output as if the script was
executed in the standalone
CHCCLP environment

© 2015 IBM Corporation

Information Management Software

Sample CHCCLP Script generation…

Prompts user to reload datastores

used in the script in order to refresh
Management Console

© 2015 IBM Corporation

New CHCCLP Commands in IIDR 11.3.3

list access connections

Displays Access Manager connections between a datastore and
user

set property recreateSubscription yes;

Command added to support recreating a subscription during
execution using add subscription

Previously add subscription stopped with an error if the subscription
already existed

Utilizing the set property will result in the old subscription being deleted
and the new one created

21 © 2015 IBM Corporation

New CHCCLP Commands in IIDR 11.3.3 …

list replication tables

Enhanced to optionally filter tables that aren't used in subscriptions

Can specify ‘Unused’ to easily find unused tables from catalog

Simplifies catalog clean-up

remove replication tables

Enhanced to optionally filter tables that aren't used in subscriptions
and remove them in bulk

Added ‘unused’ filter

list subscription

Enhanced to support reloading

List subscriptions reload true

show data translation

Added capability to display translations for all columns

Previously only supported showing translations for a specific target column
22 © 2015 IBM Corporation
New CHCCLP Commands in IIDR 11.3.3 …

readd replication table

Enhanced to print column differences when verbose mode is
enabled

reassign table mapping

Enhanced to print column mapping differences when verbose mode
is enabled

add table mapping

Enhanced to support creating a table on the target

23 © 2015 IBM Corporation

Information Management Software

Questions?

?
CDC Center of Excellence-SWG-WW

24 © 2015 IBM Corporation