infosphere change data capture management console,version 6.5€¦ · the api supports a number of...

IBMInfoSphere Change Data CaptureVersion 6.5.2

InfoSphere Change Data CaptureManagement Console, Version 6.5.2API and Commands Reference

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 63.

First edition, fourth revision

This edition applies to version 6, release 5, modification 2 of IBM InfoSphere Change Data Capture (productnumber 5724-U70), version 6, release 5 of IBM InfoSphere Change Data Capture for z/OS® (product number5755-U96), version 10, release 1 of IBM InfoSphere Classic Change Data Capture for z/OS (product number5655-W29), version 10, release 1, modification 2 of IBM InfoSphere Data Replication for Netezza (product number5725-E30), and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2008, 2011.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

InfoSphere CDC API . . . . . . . . . 1InfoSphere CDC API packages . . . . . . . . 1InfoSphere CDC API architecture . . . . . . . 2

Access Manager and Access Server APIarchitecture . . . . . . . . . . . . . . 2Publisher (source) API architecture . . . . . . 3Subscriber (target) API architecture . . . . . . 4

Sample Java programs . . . . . . . . . . . 4InfoSphere CDC API reference – Javadocs . . . . 13InfoSphere CDC API exceptions . . . . . . . 13User roles and permissions . . . . . . . . . 14

User roles . . . . . . . . . . . . . . 14User permissions . . . . . . . . . . . 15

InfoSphere CDC API considerations . . . . . . 20Access Manager and security reporting . . . . 20API support for Access Manager . . . . . . 21

Management Console Commandsreference. . . . . . . . . . . . . . 23Using commands in Management Console . . . . 23

Opening command environments . . . . . . 23Management Console commands . . . . . . . 24

addTable - Add Table to Catalog . . . . . . 26assignTable - Assign Source Table . . . . . . 27connectAgent - Connect to Datastore . . . . . 29connectServer - Connect to Access Server . . . 30deAssignTable - Unassign Target Table . . . . 31describe - Describe Selected Tables. . . . . . 32disconnectAgent - Disconnect from Datastore . . 33disconnectServer - Disconnect from Access Server 33errorHandle - Define Error Handler . . . . . 34execute - Run Batch File . . . . . . . . . 35exit - Close Command Environment . . . . . 36

getAgents - Get Accessible Datastores . . . . 36getSubscriptionActivity - Get SubscriptionActivity. . . . . . . . . . . . . . . 37getSubscriptions - Get Subscriptions for Datastore 38getSubscriptionStatus - Get Subscription Status 38getSubscriptionTables - Get Subscription Tables 39getTableStatus - Get Source Table Status . . . . 40help - Display Command Help . . . . . . . 41reAddTable - Re-add Table in Catalog . . . . 41removeTable - Remove Table from Catalog . . . 42setReplication - Set Replication Method . . . . 43setTableStatus - Set Source Table Status . . . . 45startRefresh - Start Refresh . . . . . . . . 46startMirror - Start Mirroring . . . . . . . . 47stopAll - Stop All Replication Activities . . . . 49stopMirror - Stop Mirroring . . . . . . . . 50stopRefresh - Stop Refresh . . . . . . . . 51subscribeTable - Select Table to Subscription . . 52unSubscribeTable - Deselect Table fromSubscription . . . . . . . . . . . . . 53

Scripting support . . . . . . . . . . . . 54Creating a script file . . . . . . . . . . 54Compiling a script file . . . . . . . . . . 56Running a batch file . . . . . . . . . . 57

User roles and permissions . . . . . . . . . 58User roles . . . . . . . . . . . . . . 58User permissions . . . . . . . . . . . 58

Troubleshooting and contacting IBMSupport . . . . . . . . . . . . . . 61

Notices . . . . . . . . . . . . . . 63Trademarks . . . . . . . . . . . . . . 65

© Copyright IBM Corp. 2008, 2011 iii

iv InfoSphere Change Data Capture Management Console: API and Commands Reference

InfoSphere CDC API

This reference guide serves as an overview of the application programminginterfaces (APIs) that can be used to integrate InfoSphere® CDC ManagementConsole functions in customized Java applications and programs. It is intended foradvanced users who have a comprehensive knowledge of InfoSphere CDC datareplication concepts. It also assumes a comprehensive knowledge of the Javaprogramming language.

To view the API Javadoc documentation, you will have to refer to the “InfoSphereCDC API reference – Javadocs” on page 13. Certain elements of the API that aredocumented in Javadoc are not covered in this guide. Omitting these elementsindicates that they are not intended for use in Java programs and applications thatare created for your working environment.

By providing an API for accessing Management Console functions within a Javaapplication or program, organizations are able to create specialized software tosatisfy needs and requirements unique to a specific business or industry. Inparticular, customized Java interfaces that include necessary enhancements and theability to access some or all of Management Console functions can be createdin-house.

In this section, you will learn:“InfoSphere CDC API packages”“InfoSphere CDC API architecture” on page 2“Sample Java programs” on page 4“InfoSphere CDC API reference – Javadocs” on page 13“InfoSphere CDC API exceptions” on page 13“User roles and permissions” on page 14“InfoSphere CDC API considerations” on page 20

InfoSphere CDC API packagesThe API shipped with InfoSphere CDC Management Console contains thefollowing three packages:v com.datamirror.ea.apiv com.datamirror.ea.api.publisherv com.datamirror.ea.api.subscriber

The interfaces and classes that expose the InfoSphere CDC functions are identifiedand described in the API Javadocs. For more information, see “InfoSphere CDCAPI reference – Javadocs” on page 13.

© Copyright IBM Corp. 2008, 2011 1

Related concepts

“InfoSphere CDC API reference – Javadocs” on page 13

InfoSphere CDC API architectureThe API supports a number of interfaces and classes, but it is important tounderstand the association between a specific interface or class and a ManagementConsole entity in a replication configuration. It is also important to understand therelationship among different entities. With this understanding, your customizedJava applications and programs can use the interfaces and classes that are providedin an efficient and productive manner.

The following sections present API architecture diagrams that identifyManagement Console entities, their relationships with other entities, and theprincipal interfaces and classes that allow you to work with the entities.Management Console entities are identified in bold text, and the interface or classthat allows you to work with an entity is identified in italic text. Links betweenentities are labelled to indicate the type of relationship that exists. Supportedmethods are not indicated in the diagrams.

Note: Some interfaces and classes documented in this publication are notrepresented in any of the relationship diagrams. Helper interfaces and classes thatact as building blocks for other interfaces and classes do not appear in thediagrams.

In this section, you will learn:“Access Manager and Access Server API architecture”“Publisher (source) API architecture” on page 3“Subscriber (target) API architecture” on page 4

Access Manager and Access Server API architectureFor the following diagram, you should note the following:v In a replication configuration, Management Console users (UserProfile) and

datastores (ReplicationRole) are defined in Access Manager(DefinitionDataSource).

v Access parameters (AccessRule) must be specified when identifying the users(UserProfile) that can access each datastore (ReplicationRole) defined in yourconfiguration.

v In Management Console, InfoSphere CDC (TransformationServer) is representedas a datastore (ReplicationRole).

v The API interacts with the replication configuration though the Access Server(DataSource) component.

v User (UserProfile) access to the replication configuration is through a connectionto the Access Server (DataSource) component.

v Datastores (ReplicationRole) support system parameter settings(SystemParameterSet) as well as notifications (AlertManager).

v Datastores (ReplicationRole) can be source (Publisher) or target (Subscriber). ThePublisher and Subscriber entities also encompass other entities (see Publisherand Subscriber for entity relationship diagrams).

2 InfoSphere Change Data Capture Management Console: API and Commands Reference

Related concepts

“InfoSphere CDC API architecture” on page 2

Publisher (source) API architectureFor the following publisher API architecture diagram, you should note thefollowing:v Auto-recovery (AutoRecoveryConfig) is a feature that is not currently supported

by a InfoSphere CDC product, but is presented as an interface for futureexpansion.

v Publishers are associated with catalogs (Catalog) and manage subscriptions(Subscription).

v Derived columns (DerivedColumn) and IBM® DB2® for i members(TableMember) can only be defined in tables selected for replication(SubscribedTable).

InfoSphere CDC API 3

Subscriber (target) API architectureThe following diagram provides an overview of the subscriber API architecture:

Sample Java programsApiPublisherSample.java and ApiSubscriberSample.java are sample Javaprograms that illustrate how the API can be used with Management Console.

You can modify the sample programs for your working environment. However,note that IBM only supports the unmodified sample programs and thedocumented functions of the API.

ApiPublisherSample.java/*** ApiPublisherSample.java shows how to* - get a connection to an access server* - get a publisher* - add a new subscription to the publisher*/

import com.datamirror.ea.api.*;import com.datamirror.ea.api.publisher.*;

public class ApiPublisherSample{

//// information for connecting to an access server.// Change the information to suit your configuration.//public static final String eaUser = "gsmith";public static final String eaPassword = "cricket";public static final String accessServerHost = "localhost";public static final int accessServerPort = 10101;

//// Publisher name in the sample. Change the name to suit your// configuration.//public static final String samplePublisherName = "OraPubs";

//// The new subscription name in the sample. Change the name// to suit your configuration.//


public static final String sampleSubscriptionName = "NTOraSub";

/*** program entry point*/public static void main(String[] args){

//// gets a connection to an access server//DataSource dataSource = connectToAccessServer();

if (dataSource.isOpen()){

//// At this point, the sample program has connected to// the access server successfully//createSubscription(dataSource);//// disconnects the access server//dataSource.close();

}}

/*** This method shows how the sample program connects to* an access server. It returns a DataSource object* representing the connection to the access server.*/public static DataSource connectToAccessServer(){

DataSource dataSource = null;try{

//// constructs a context with login information for the// access server//DefaultContext c = new DefaultContext();c.setString(DataSource.User, eaUser);c.setString(DataSource.Password, eaPassword);c.setString(DataSource.Hostname, accessServerHost);c.setInt(DataSource.Port, accessServerPort);//// uses com.datamirror.ea.api.Toolkit to get a handle to// a DataSource object. At this point, the DataSource object// is not connected to any access server//dataSource = Toolkit.getDefaultToolkit().createDataSource();//// tries to connect to the access server specified by// the context//dataSource.connect(c);

}catch (ApiException e){

e.printStackTrace(System.out);}finally{

return dataSource;}

}


/*** This method shows how to add a new subscription to a publisher*/public static void createSubscription(DataSource dataSource){

//// gets a publisher to which the new subscription is// to be added.//Publisher publisher = dataSource.getPublisher(samplePublisherName);//// Make sure the publisher is connected before// requesting anything from it//if (publisher.isConnected() == false){

try{

publisher.connect();}catch (ApiException e){

e.printStackTrace();}

}

//// uses a context to define the details of the// new subscription//Context c = new DefaultContext();

c.setString(Subscription.PublisherID, "NTORAPUB");c.setString(Subscription.PublisherIDPending, "NTORAPUB");c.setString(Subscription.PublisherDescription, "NT Oracle Source");c.setString(Subscription.PublisherDescriptionPending, "NT Oracle Source");c.setString(Subscription.SubscriberOS, TransformationServer.getOSPlatformByID(TransformationServer.WINNT));c.setString(Subscription.SubscriberDBPlatform,TransformationServer.getDBPlatformByID(TransformationServer.ORACLE));

c.setString(Subscription.CommunicationProtocol, "TCP/IP");c.setString(Subscription.SubscriberVersion, "V4R2");c.setString(Subscription.DatabaseID, "ORCL");c.setString(Subscription.DatabaseUser, "SMITHGEO");c.setString(Subscription.DatabasePassword, "snake");c.setString(Subscription.SubscriberLocation, "subhost");c.setInt(Subscription.SubscriberPort, 2100);c.setString(Subscription.SubscriptionDescription, "NT Oracle Database");c.setString(Subscription.PublisherLocation, "pubhost");c.setInt(Subscription.PublisherPort, 0);

try{

//// creates a new subscription named "NTOraSub" with its// definition stored in the context c.//

Subscription subscription = publisher.addSubscription(sampleSubscriptionName, c);}catch (ApiException e){

e.printStackTrace();}

}}


ApiSubscriberSample.java/** ApiSubscriberSample.java** This is a sample program for usage of API for Management Console.* To use the sample program, change the parameters in run() method, put* the agent name list on the command line:** java -cp .;api.jar ApiSubscriberSample [agentname1 [agentname2...]]** The output file names will be each agent name.**/

import com.datamirror.ea.api.*;import com.datamirror.ea.api.subscriber.*;

public class ApiSubscriberSample{

java.io.PrintStream out;String tab;

public static void main(String[] args){

ApiSubscriberSample sample = new ApiSubscriberSample();sample.run(args);System.out.println("Done!");

}

/** Connect to the Access Server and get the Agent list.*/private void run(String[] args){

try{

/** User, Password, Hostname and Port are parameters needed to connect* the Access Server. You should change them to your correct parameters.

*/DefaultContext c = new DefaultContext();c.setString(DataSource.User, "gsmith");c.setString(DataSource.Password, "cricket");c.setString(DataSource.Hostname, "localhost");c.setInt(DataSource.Port, 10101);

DataSource dataSource = Toolkit.getDefaultToolkit().createDataSource();dataSource.connect(c);if (dataSource.isOpen()){

for (int i = 0; i < args.length; i ++){Subscriber subscriber = matchSubscriber(dataSource, args[i]);if (subscriber != null)

{out = new java.io.PrintStream(new java.io.FileOutputStream(subscriber.getName()));

testSubscriber(subscriber);System.out.println("\nThe output filename is:" + subscriber.getName() + "\n");

}}

}dataSource.close();

}catch(Exception e){

e.printStackTrace(System.out);}


}

/** Find the Subscriber according to its name.*/private Subscriber matchSubscriber(DataSource ds, String name){

Subscriber[] subscribers = ds.getSubscribers();for (int i = 0; i < subscribers.length; i ++){

if (name.equals(subscribers[i].getName())){

return subscribers[i];}

}return null;

}

/** Do Subscriber level test.*/private void testSubscriber(Subscriber subscriber) throws ApiException{

String[] pubNames;Publication publication;

subscriber.connect();System.out.println("Test Subscriber: " + subscriber.getName());out.println("--Agent--");out.println(subscriber.getName()+ " ("

+ subscriber.getDBPlatform() + " "+ subscriber.getVersion() + " on "+ subscriber.getHostName() + " "+ subscriber.getOSPlatform() + ")");

/* Create target table SAMPLETABLE in master database under owner dbo. The* table has columns: COL1, COL2, COL3. Column COL2 is the key. Change the* parameters to suit your need.

DBColumn[] columns = new DBColumn[3];columns[0] = new DefaultDBColumn("COL1", "decimal", false, 10, 2, true);columns[1] = new DefaultDBColumn("COL2", "decimal", true, 4, 0, false);columns[2] = new DefaultDBColumn("COL3", "varchar", false, 24, 0, true);String[] keys = {"COL2"};

subscriber.createTable("master", "dbo", "SAMPLETABLE", columns, keys, "COL2", "");*/

pubNames = subscriber.getPublicationNames();for(int i = 0; i < pubNames.length; i++){

publication = subscriber.getPublication(pubNames[i]);testPublication(subscriber, publication);

}return;

}

/** Do Publication level test.*/

private void testPublication(Subscriber subscriber,Publication publication) throws ApiException

{String[] pTableNames;DBPath[] paths;PublishedTable pTable;

System.out.println(" Test Publication: " + publication.getName());


tab = " ";out.println("");out.println(tab + "--Publication--");

out.println(tab + publication.getName() + "(" +publication.getDescription() + ")");

paths = publication.getDBPaths();tab = " ";for(int i = 0; i < paths.length; i++){

out.println(tab + "--Owner--");out.println(tab + paths[i].getFullName());pTableNames = publication.getPublishedTableNames(paths[i]);for(int j = 0; j < pTableNames.length; j++){pTable = publication.getPublishedTable(paths[i], pTableNames[j]);testTable(publication, pTable);}

}return;

}

/** Do table level test including Row Identifier and Member Identifier.*/

private void testTable(Publication publication,PublishedTable pTable) throws ApiException

{TableAssignment ta;DBTable destinationTable;DBColumn column;ColumnAssignment ca;

System.out.println(" Test table: " + pTable.getName());tab = " ";if(pTable.isAssigned()){

ta = pTable.getTableAssignment();destinationTable = ta.getDestinedTable();out.println(tab + "--Table--");out.println(tab + pTable.getName() + " ==> " +

destinationTable.getName());

/* Set Row ID to "REPNO < 600" for the published table"CUSTOMER" under the

* publication "API". Change the parameters to suityour configuration.

if("CUSTOMER".equals(pTable.getName()) &&"API4".equals(publication.getName()))

{ta.setRowIDExpression("REPNO < 600");

}*/tab = " ";String rowID = ta.getRowIDExpression();if(rowID != null && rowID.length() != 0){

out.println(tab + "--RowID--");out.println(tab + "(rowID = " + rowID + ")");

}

// Member IdString[] memberNames = ta.getMemberNames();for(int i = 0; i < memberNames.length; i++){

out.println(tab + "--MemberID--");out.println(tab + "(member = " +


memberNames[i] + " : "

+ ta.getMemberIdentifier(memberNames[i]) + ")");}

// UserExittestUserExit(publication, pTable, ta);

// Column mappingString[] dColNames = ta.getDestinedColumnNames();out.println(tab + "--Column--");for(int i = 0; i < dColNames.length; i++){

ca = ta.getColumnAssignment(dColNames[i]);testColumnAssignment(publication, pTable, ca);

}}else // Table is not assigned{

String[] pColNames = pTable.getColumnNames();tab = " ";out.println(tab + "--Table--");out.println(tab + pTable.getName() + " ==> ?");tab = " ";out.println(tab + "--Column--");for(int i = 0; i < pColNames.length; i++){

column = pTable.getColumn(pColNames[i]);out.println(tab + column.getName());

}

/* Assign the published table "PRODUCT" underpublication "API4" to destination

* table "CUST10K" owned by "dbo" in the "master"database. Change the parameters

* to suit your configuration.

if("PRODUCT".equals(pTable.getName()) &&"API4".equals(publication.getName()))

{pTable.assign("CUST10K", "dbo", "master");

}*/

}return;

}

/** Do column level mapping test.*/

private void testColumnAssignment(Publication publication,PublishedTable pTable, ColumnAssignment ca)

throws ApiException{

String temp = null;String[] valueTrans;PublishedDBColumn pColumn = ca.getPublishedColumn();

/* Do column mapping and set value translation for thepublished table "PRODUCT" that

* has been assigned to a destination table.* Map the first column of destination table to a

constant "APPLE".* Map the second column of the destination table to

a published column named "PRICE".* Map the third column of the destination table to a

derived expression.


* Add a value translation to the mapping of thefourth column.

* Change the parameters to suit your configuration.

if("PRODUCT".equals(pTable.getName()) &&"API4".equals(publication.getName()))

{for(int i = 0; i < colNames.length; i++){

ca = ta.getColumnAssignment(colNames[i]);if (i == 1)

ca.mapTo(ColumnAssignment.MAP_CONSTANT, "APPLE");if (i == 2)

ca.mapTo(ColumnAssignment.MAP_PUBLISHED_COLUMN, "PRICE");if (i == 3)

ca.mapTo(ColumnAssignment.MAP_DERIVED_EXPRESSION,"UNITPRICE + 10");

if (i == 4)ca.addValueTranslation("ON", "Ontario");

}}*/

switch(ca.getAssignmentType()){

case ColumnAssignment.MAP_PUBLISHED_COLUMN:if (pColumn.getDescription() != null &&

!pColumn.getDescription().equals(pColumn.getName()))temp = pColumn.getName() + "(" + pColumn.getDescription() + ")";

elsetemp = pColumn.getName() ;

break;case ColumnAssignment.MAP_CONSTANT:

temp = "(Constant)" + ca.getConstantValue();break;

case ColumnAssignment.MAP_ZERO:temp = "(zero)";break;

case ColumnAssignment.MAP_DERIVED_EXPRESSION:temp = "(Derived_Expression)" + ca.getDerivedExpression();break;

case ColumnAssignment.MAP_BLANK:temp = "(blank)";break;

case ColumnAssignment.MAP_NULL:temp = "(null)";break;

case ColumnAssignment.MAP_CURRENT_DATE:temp = "(curDate)";break;

case ColumnAssignment.MAP_DATABASE_DEFAULT:temp = "(DBdefault)";

}tab = " ";out.println(tab + temp + " -> " + ca.getDestinedColumn().getName());if(ca.hasValueTranslation()){

tab = " ";out.println(tab + "--Value_Translation--");valueTrans = ca.getValueTranslationNames();for( int i = 0; i < valueTrans.length; i++)

out.println(tab + valueTrans[i] + " .x. "+ ca.getValueTranslationValue(valueTrans[i]));

}return;

}


/** Test User Exit.*/

private void testUserExit(Publication publication,PublishedTable pTable, TableAssignment ta)

throws ApiException{/* Set User Exit for the published table "CUSTOMER" under publication "API4".* Create a C/C++ DLL user exit, the program is located at "/gsmith/home/lib/",* Add operation "function3" at BEFORE_DELETE entry point, and "clearme" at* AFTER_CLEAR entry point. Disable STANDARD_DELETE and STANDARD_UPDATE TS* operation. Change the parameters to suit your configuration.

if("CUSTOMER".equals(pTable.getName()) && "API4".equals(publication.getName())){UserExit nue = ta.createNewUserExit(UserExit.C_CPP_DLL);nue.setFunctionPath("/gsmith/home/lib/");nue.addOperation(UserExit.BEFORE_DELETE, "function3");nue.addOperation(UserExit.AFTER_CLEAR, "clearme");nue.setStdOperation(UserExit.STANDARD_DELETE, UserExit.DISABLE);nue.setStdOperation(UserExit.STANDARD_UPDATE, UserExit.DISABLE);ta.setUserExit(nue);}*/UserExit ue = ta.getUserExit();if(ue != null){

String type = null;switch(ue.getFunctionType()){

case UserExit.STANDARD_FUNCTION:type = "Standard Function";break;

case UserExit.C_CPP_DLL:type = "C/C++ Dll";break;

case UserExit.IDISPATCH_COM_DLL:type = "COM";break;

case UserExit.STORED_PROCEDURE:type = "Stored procedure";break;

case UserExit.JAVA_CLASS:type = "Java class";

}out.println(tab + "--User Exit--");out.print(tab + "(type:" + type + " path:"

+ ue.getFunctionPath() +" entry_point:)");}return;

}

private String matchEntryPoint(int ep){

String result = "";switch(ep){

case UserExit.BEFORE_CLEAR:result = "BEFORE_CLEAR";break;

case UserExit.AFTER_CLEAR:


result = "AFTER_CLEAR";break;

case UserExit.BEFORE_DELETE:result = "BEFORE_DELETE";break;

case UserExit.AFTER_DELETE:result = "AFTER_DELETE";break;

case UserExit.BEFORE_INSERT:result = "BEFORE_INSERT";break;

case UserExit.AFTER_INSERT:result = "AFTER_INSERT";break;

case UserExit.BEFORE_UPDATE:result = "BEFORE_UPDATE";break;

case UserExit.AFTER_UPDATE:result = "AFTER_UPDATE";break;

case UserExit.BEFORE_REFRESH:result = "BEFORE_REFRESH";break;

case UserExit.AFTER_REFRESH:result = "AFTER_REFRESH";break;

case UserExit.BEFORE_CONNECT_DISCONNECT:result = "BEFORE_CONNECT_DISCONNECT";break;

case UserExit.AFTER_CONNECT_DISCONNECT:result = "AFTER_CONNECT_DISCONNECT";break;

}return result;

}

}

InfoSphere CDC API reference – JavadocsThe API documentation is available in Javadoc format in your ManagementConsole installation directory. To open the API documentation, click the index.htmlfile in the following directory:v :\\api

InfoSphere CDC API exceptionsThe API throws different exceptions that can be caught and handled by your Javaprograms and applications. This section identifies each exception and describes thesituations that result in the exception being raised.

ApiException

This exception encompasses all other recognized API exceptions(CommunicationException, DataNotFoundException, DuplicateException, andUnsupportedFeatureException), and is raised in a variety of situations by differentmethods. For instance, it will be raised if a value passed through a methodparameter is not valid or a connection to Access Server cannot be established.

CommunicationException

This exception is raised when a communications problem has been detected


DataNotFoundException

This exception is typically raised when an attempt to retrieve data of a particulartype cannot be performed. It is also raised in certain situations where an attempt ismade to assign a value to a setting that does not exist.

DuplicateException

This exception is raised when an attempt is made to define an entity in areplication configuration that already exists. For instance, it is raised when anattempt is made to define a subscription that has the same name as anothersubscription.

UnsupportedFeatureException

This exception is raised when an attempt is made to work with functions that arenot supported by the type of datastore with which you are working. For instance,it is raised if the datastore does not support the definition of derived columns.

Note: Methods are provided to indicate which functions are currently supported.The names of these methods typically start with is (for example,isAlarmFilteringSupported). It is recommended that you use these methods beforeworking with functions that may not be available for a particular datastore.Checking the availability of these functions before working with them will avoidthis exception from being raised.

User roles and permissionsThis section identifies and briefly describes the four user roles. It then lists the userpermissions for particular methods in the API.

In this section, you will learn:“User roles”“User permissions” on page 15

User rolesA Management Console user belongs to one of the following four roles:v TS System Administrator—The user can view, configure, and initiate

replication.v TS Administrator—The user can view, configure, and initiate replication, but

cannot change InfoSphere CDC system parameters.v TS Operator—The user can view and initiate replication.v TS Monitor—The user can only view replication.

For more information about user roles, see your Management Consoledocumentation.

To determine the role to which a user is currently assigned, see the getRole methodin the UserProfile interface. For more information, see “InfoSphere CDC APIreference – Javadocs” on page 13.


User permissionsThis section identifies those methods in the Management Console API that are onlyaccessible by specific user roles. The remainder of the methods in the API do notrequire a specific user role. For more information, see “User roles” on page 14.

Note: The permissions for each method apply to a Management Console userconnected to an Access Server. The User property specified when invoking theconnect method in the DataSource interface determines the user that will beaffected by the specified permissions. For more information on this method andinterface, see “InfoSphere CDC API reference – Javadocs” on page 13.

The table below uses the following conventions for user permissions.v Unlimited—The user has permission to invoke the method.v No permission—The user does not have permission to invoke the method. If the

user attempts to invoke restricted methods will result in the ApiExceptionexception being thrown. In cases where a method is out of scope (such as amethod that is equivalent to an Access Manager function) or calledautomatically for all user roles, this symbol will also indicate that a method isnot applicable at the user level.

MethodTS SystemAdministrator

TSAdministrator TS Operator TS Monitor

addDerivedColumn

Unlimited Unlimited Nopermission

No permission

addDerivedColumns


No permission

addMemberIdentifier


No permission

addParameter Unlimited No permission Nopermission

No permission

addQueue Unlimited Unlimited Nopermission

No permission

addConnection Unlimited Unlimited Nopermission

No permission

addMapFile Unlimited Unlimited Nopermission

No permission

addSubscription Unlimited Unlimited Nopermission

No permission

addValueTranslation


No permission

addTable Unlimited Unlimited Nopermission

No permission

addTables Unlimited Unlimited Nopermission

No permission

assign Unlimited Unlimited Nopermission

No permission

assignToXml Unlimited Unlimited Nopermission

No permission

bind Unlimited Unlimited Nopermission

No permission




clear Unlimited Unlimited Nopermission

No permission

createNewUserExitUnlimited


No permission

createTable Unlimited Unlimited Nopermission

No permission

deassign Unlimited Unlimited Nopermission

No permission

describe Unlimited Unlimited Unlimited No permission

generateStaticSQL

Unlimited No permission Nopermission

No permission

getConflictResolutionInfo

Unlimited Unlimited Unlimited No permission

getDynamicSelectionRules


No permission

getLatencyAlert


No permission

mapTo Unlimited Unlimited Nopermission

No permission

modify Unlimited Unlimited Nopermission

No permission

reAddTable Unlimited Unlimited Nopermission

No permission

reAddTables Unlimited Unlimited Nopermission

No permission

reassign Unlimited Unlimited Nopermission

No permission

refresh(AlarmCategorycategory)AlertManagerClass


No permission

refreshSystemParameterSetClass


No permission

removeConnection


No permission

removeDerivedColumn


No permission

removeDerivedColumns


No permission

removeFilter Unlimited Unlimited Nopermission

No permission

removeMapFile


No permission




removeMemberIdentifier


No permission

removePublication


No permission

removeQueue Unlimited Unlimited Nopermission

No permission

removeTable Unlimited Unlimited Nopermission

No permission

removeTables Unlimited Unlimited Nopermission

No permission

removeParameter


No permission

removeSubscription


No permission

removeValueTranslation


No permission

setAlertsEnabled


No permission

setAutoRecoveryConfig


No permission

setBasedOnColumn


No permission

setChargeableName


No permission

setColumnAlias Unlimited Unlimited Nopermission

No permission

setColumnSelected


No permission

setColumnUnicodeHandling


No permission

setConflictDetectionColumns


No permission

setConflictResolutionInfo


No permission

setConflictResolutionMethod


No permission

setCommunicationEventHandler


No permission

setDataType Unlimited Unlimited Nopermission

No permission

setDateTimeFormat


No permission

setDTSeparator Unlimited Unlimited Nopermission

No permission

setDescription Unlimited Unlimited Nopermission

No permission




setDynamicSelectionRules


No permission

setEnabledUnlimited


No permission

setEvalFrequency


No permission

setExpression Unlimited Unlimited Nopermission

No permission

setFilter Unlimited Unlimited Nopermission

No permission

setFunctionPath Unlimited Unlimited Nopermission

No permission

setGroupOrder Unlimited Unlimited Nopermission

No permission

setIntervalUnit Unlimited Unlimited Nopermission

No permission

setJavaClass Unlimited Unlimited Nopermission

No permission

setJavaParameters


No permission

setLatencyAlert Unlimited No permission Nopermission

No permission

setLatencyAlertEnabled


No permission

setLength Unlimited Unlimited Nopermission

No permission

setLocalPort Unlimited Unlimited Nopermission

No permission

setLogChangedDBAction


No permission

setMemberIdentifier


No permission

setName Unlimited Unlimited Nopermission

No permission

setNullable Unlimited Unlimited Nopermission

No permission

setNumberofRetries


No permission

setOrder Unlimited Unlimited Nopermission

No permission

setParameterValue


No permission

setPassword Unlimited Unlimited Unlimited No permission

setPath Unlimited Unlimited Nopermission

No permission

setPathAlias Unlimited Unlimited Nopermission

No permission




setPrecision Unlimited Unlimited Nopermission

No permission

setProblemThreshold


No permission

setProperty Unlimited Unlimited Nopermission

No permission

setRecoveryMode


No permission

setRefreshOrder Unlimited Unlimited Nopermission

No permission

setReplicationMethod


No permission

setReplicationStatus


No permission

setRetrieveCurrentValues


No permission

setRetryInterval Unlimited Unlimited Nopermission

No permission

setRetryPeriod Unlimited Unlimited Nopermission

No permission

setRowIDExpression


No permission

setRowSelection Unlimited Unlimited Nopermission

No permission

setScale Unlimited Unlimited Nopermission

No permission

setSelected Unlimited Unlimited Nopermission

No permission

setSequence Unlimited Unlimited Nopermission

No permission

setSQLStatement Unlimited Unlimited Nopermission

No permission

setStdOperation Unlimited Unlimited Nopermission

No permission

setTable Unlimited Unlimited Nopermission

No permission

setTableAlias Unlimited Unlimited Nopermission

No permission

setTableImage Unlimited Unlimited Nopermission

No permission

setTimeOut Unlimited Unlimited Nopermission

No permission

setTimeOutValue Unlimited Unlimited Unlimited No permission

setUEFunctionPath Unlimited Unlimited Nopermission

No permission

setUserExit Unlimited Unlimited Nopermission

No permission




setWarningThreshold


No permission

setValue Unlimited Unlimited Nopermission

No permission

setValueComparisonColumn


No permission

setValueTranslation Unlimited Unlimited Nopermission

No permission

setXmlUserExits Unlimited Unlimited Nopermission

No permission

startMirror Unlimited Unlimited Unlimited No permission

startRefresh Unlimited Unlimited Unlimited No permission

stopAllActivity Unlimited Unlimited Unlimited No permission

stopMirror Unlimited Unlimited Unlimited No permission

stopRefresh Unlimited Unlimited Unlimited No permission

trace Unlimited No permission Nopermission

No permission

unbind Unlimited Unlimited Nopermission

No permission

updateAlert Unlimited Unlimited Nopermission

No permission

updateAlerts Unlimited Unlimited Nopermission

No permission

updateDerivedColumn


No permission

updateDerivedColumns


No permission

verifyStaticSQL Unlimited No permission Nopermission

No permission

InfoSphere CDC API considerationsThis section identifies some important considerations about using the InfoSphereCDC API.

In this section, you will learn:“Access Manager and security reporting”“API support for Access Manager” on page 21

Access Manager and security reportingAccess Manager security and reporting features can only be accessed through theAccess Manager perspective in Management Console. To prevent security measuresfrom being modified through Java programs, the API does not provide methodsthat interrogate and manipulate security settings. However, before creating Javaprograms that use the Management Console API, you should consult your AccessManager administrator to determine the current security settings. The behavior of


some methods provided through the API will be influenced by certain securitysettings established through the Access Manager perspective in ManagementConsole

API support for Access ManagerPreviously, customized Java programs could only manipulate an ManagementConsole user currently connected to an Access Server. Furthermore, programscould only work with datastores that had already been defined and can beaccessed by the connected Management Console user. Although existingfunctionality to create and work with all users and datastores in a configurationwas provided through the Access Manager perspective in Management Console,the API did not provide equivalent support. For more information about AccessServer and the Access Manager perspective, see your Management Consoledocumentation.

The API supports the definition of all Management Console users and datastores inyour configuration. This means that it is now possible to add certain AccessManager operations to your Java programs.


Management Console Commands reference

This guide describes the Management Console interactive command promptenvironment that you can use on a client workstation to configure and initiatetransformational replication between source and target datastores. Commands aresubmitted through a command prompt in Windows or UNIX, or a Telnetenvironment.

Although Management Console provides the full range of support, commands canbe used when your replication configuration is relatively simple to manage.Commands can be issued interactively or included in script files. This guide alsodescribes how script files are created and compiled into a batch file. You can thenrun the batch file to perform a sequence of commands. Depending on individualpreferences, the interactive command prompt environment may be chosen insteadof the application.

In this section, you will learn:“Using commands in Management Console”“Management Console commands” on page 24“Scripting support” on page 54“User roles and permissions” on page 58

Using commands in Management ConsoleAs an alternative to defining a replication configuration through the ManagementConsole application, Management Console commands can be used to performadministrative and operational functions. Although InfoSphere CDC also supportssome of these commands, command syntax is not consistent across all InfoSphereCDC product offerings. In addition, InfoSphere CDC commands must be issuedlocally on source or target systems that may be geographically dispersed. Bycomparison, Management Console commands can be applied to a specifieddatastore. All commands can be interactively submitted on a workstation at thecommand prompt in Windows and UNIX, or in a Telnet environment.

In this section, you will learn:“Opening command environments”

Related concepts

“Opening command environments”

Opening command environmentsTo interactively submit Management Console commands, you must open aninteractive environment where these commands are recognized. This sectionexplains how to open a Windows, UNIX, or Telnet environment on a workstationwhere Management Console (Windows) or Access Server (UNIX) has beeninstalled.

See also:“To issue commands in a Windows environment” on page 24“To issue commands in a UNIX or Linux environment” on page 24“To issue commands in a Telnet environment” on page 24

© Copyright IBM Corp. 2008, 2011 23

To issue commands in a Windows environment1. Open a command prompt window.2. Navigate to the root of theManagement Console installation directory.3. Issue the following command:

online.bat

You can now invoke Management Console commands at the prompt.Related reference

“exit - Close Command Environment” on page 36

To issue commands in a UNIX or Linux environment1. Log on to the UNIX or Linux system where Access Server is installed.2. Navigate to the following directory:

//bin

3. Issue the following command:./online



To issue commands in a Telnet environment1. Follow the instructions below for the operating system where you want to issue

the commands:Windows:Open a command prompt and navigate to the Management Console installationdirectory and then issue the following command:online.bat -t

where is an available port number on the local workstation that will beused by the Telnet command environment.UNIX and Linux:Navigate to the following directory:\bin

Issue the following command:./online -t

where is an available port number on the local workstation that will beused by the Telnet command environment.

2. Open Telnet and specify the host name and port of the local workstation thatyou reserved in the previous step:open gsmith.mycompany.com 1012



Management Console commandsYou should note the following conventions in the definition of the commandparameters:v Angle brackets < > indicate mandatory parameters.


v Square brackets [ ] show optional arguments. You can select any or none of theparameters, depending on requirements.

v A vertical bar | separates items in a list of parameters or options when thechoices are limited only to the parameters and options listed. When the verticalbar appears in a list enclosed by SQUARE BRACKETS, the choices are limited tothe items in the list, but the user still has the option not to use any parametersor options.

v Ellipsis ... mean that a parameter or option can be repeated more than once.

Further considerations:v Command names are case-sensitive, and must be entered as documented in this

appendix. Command parameters (for instance, datastore names, table names,and so on) may be case-sensitive on certain platforms. In the examples,command parameters are expressed in uppercase characters.

v All command invocations must end with a semicolon before pressing the Enterkey.

v For commands with no parameters, you must specify an empty parameter listafter the command name (in other words, () ).

v For optional command parameters ( [ ] ), default values are used if theseparameters are omitted in an invocation.

v Special values must be specified in lowercase characters.v In each interactive command prompt environment, the connectServer command

must be issued before invoking any of the other Management Consolecommands (except help - Display Command Help) documented in the followingsections. Conversely, no Management Console commands can be issued in thecommand environment after invoking disconnectServer - Disconnect from AccessServer.

v Command syntax is verified, and syntax errors that are detected are reportedafter command invocation. Specific names (such as datastore names, subscriptionnames, and so on) identified in a command invocation are not verified.

In this section, you will learn:“addTable - Add Table to Catalog” on page 26“assignTable - Assign Source Table” on page 27“connectAgent - Connect to Datastore” on page 29“connectServer - Connect to Access Server” on page 30“deAssignTable - Unassign Target Table” on page 31“describe - Describe Selected Tables” on page 32“disconnectAgent - Disconnect from Datastore” on page 33“disconnectServer - Disconnect from Access Server” on page 33“errorHandle - Define Error Handler” on page 34“execute - Run Batch File” on page 35“exit - Close Command Environment” on page 36“getAgents - Get Accessible Datastores” on page 36“getSubscriptionActivity - Get Subscription Activity” on page 37“getSubscriptions - Get Subscriptions for Datastore” on page 38“getSubscriptionStatus - Get Subscription Status” on page 38“getSubscriptionTables - Get Subscription Tables” on page 39“getTableStatus - Get Source Table Status” on page 40

Management Console Commands reference 25

“help - Display Command Help” on page 41“reAddTable - Re-add Table in Catalog” on page 41“removeTable - Remove Table from Catalog” on page 42“setReplication - Set Replication Method” on page 43“setTableStatus - Set Source Table Status” on page 45“startRefresh - Start Refresh” on page 46“startMirror - Start Mirroring” on page 47“stopAll - Stop All Replication Activities” on page 49“stopMirror - Stop Mirroring” on page 50“stopRefresh - Stop Refresh” on page 51“subscribeTable - Select Table to Subscription” on page 52“unSubscribeTable - Deselect Table from Subscription” on page 53

Related reference

“help - Display Command Help” on page 41“disconnectServer - Disconnect from Access Server” on page 33

addTable - Add Table to Catalog

This command adds a table to the source tables available for replication for thespecified datastore.

Adding a source table to the tables available for replication is discussed in moredetail in the Management Console documentation.

SyntaxaddTable(,,);

Parameters

The name of the datastore that will have a source table added to its catalog.

The datastore that you specify must be either a dual or source datastore. Formore information about datastores, see your Management Consoledocumentation.

Depending on the type of datastore, the owner of the source table or thelibrary where the source table is located.

The name of the source table that will be added to the catalog.

Result

None

Example

addTable(ORAPUBS, GSMITH, EMP);

The source table named EMP owned by GSMITH will be added to the catalog forthe datastore ORAPUBS.


addTable(PRODPUBS, MASTDB.BMOORE, SALES);

The source table named SALES (in the database MASTDB) owned by BMOOREwill be added to the catalog for the datastore PRODPUBS.

addTable(HQAGENT, CUSTLIB, CUSTOMER);

The source table named CUSTOMER located in library CUSTLIB will be added tothe catalog for the datastore HQAGENT.

assignTable - Assign Source Table

This command assigns a source table that has been described (by the describecommand) to the specified target table.

For general information about table assignments and mapping tables, see theManagement Console documentation.

SyntaxassignTable(,, , , , ,, , , [, index | , noindex]);

Parameters

The name of the datastore that will have a source table assigned to a describedtarget table.

The datastore that you specify must be either a dual or target datastore. Formore information about datastores, see the Management Consoledocumentation.

The identifier for the source server.

This identifier is specified when creating a new subscription throughManagement Console.


The name of the source table that you want to assign to the target table.

The name of the database that contains the target table.

If a database name is not required, set this parameter to the special value of*null.

Depending on the type of datastore, the owner of the target table or the librarywhere the target table is located.

The name of the target table that you want to assign to the target table.

Indicates how members in source and target tables are assigned.


If you specify the name of a member in the target table, all members in thesource table will be merged into a single member in the multi-member targettable.

Alternatively, this parameter can be set to one of the following special values:v member—Corresponding members in the source and target tables will be

assigned. This value should be specified if the multi-member target table hasthe same member structure as the multi-member source table.

v only—Merges all members in the source table to the single-member targettable.

v *null—Indicates that this parameter is not applicable.

The library containing the unique index for the target table.

If this parameter is not applicable, set it to the special value of *null.

indexThe name of the unique index for the target table.

If this parameter is not applicable, set it to the special value of *null.

noindexIndicates the operation performed by the command when a unique index forthe target table is not specified.

This parameter is applicable only when the index parameter is omitted (thename of a unique index or *null is not specified) in a command invocation. Inthis case, it provides confirmation whether or not to proceed with the tableassignment.

For example, under Live Audit replication, a unique index is not required forthe target table. By specifying the appropriate value for this parameter, you canconfirm that the assignment must still be performed.

You can specify one of the following special values:v y—Confirms the table assignment with the specified parameters.v n—Rejects the table assignment with the specified parameters. Instead, the

deAssignTable command is performed using some of the parameters thathave been specified.

If this parameter is omitted, the default setting is n.

Result

None.

Example

assignTable(ORASUBS, NTORAPUB, GSMITH, EMP, *null, GSMITH, DESTEMP, *null,*null, *null);

The source table EMP owned by GSMITH will be assigned to the target tableDESTEMP also owned by GSMITH.

The assignment is performed without a unique index for the target tableDESTEMP.

assignTable(ORASUBS, NTORAPUB, BJONES, CUST, DESTDB, BJONES, DESTCUST,*null, *null, *null);


The source table CUST owned by BJONES will be assigned to the target tableDESTCUST (also owned by BJONES) that is located in the database DESTDB.

The assignment is performed without a unique index for the target tableDESTCUST.

assignTable(BRANCHAGENT, HQSYS, CUSTLIB, CUSTOMER, *null, DESTLIB, CUST,MEMBER, DESTLIB, CUSTIX);

The multi-member source table CUSTOMER located in the library CUSTLIB will beassigned to the multi-member target table CUST located in the library DESTLIB.

Corresponding members in the source and target tables will be assigned.

The unique index CUSTIX for the target table is located in the library DESTLIB.

assignTable(REGION1, PUB, SALESDB, SALES, *null, DESTDB, DESTSALES, *null,*null, y);

The source table SALES located in the library SALESDB will be assigned to thetarget table DESTSALES located in the library DESTDB.

The assignment is performed without a unique index for the target tableDESTSALES.Related reference

“deAssignTable - Unassign Target Table” on page 31

connectAgent - Connect to Datastore

This command establishes a connection to the specified datastore that has beendefined in the Access Manager perspective and can be accessed by theManagement Console user identified in the connectServer command.

Successfully issuing this command allows you to use other commands where thedatastore name has to be identified.

To list the datastores that can be specified in this command, use getAgentscommand.

Establishing a connection to a datastore through the Management Console isdiscussed in more detail in the Management Console documentation.

SyntaxconnectAgent();

Parameters

The name of the datastore to which you will connect.

Result

None.


Example

connectAgent(ORAPUBS);

A connection to the datastore named ORAPUBS will be established.Related reference

“connectServer - Connect to Access Server”“getAgents - Get Accessible Datastores” on page 36

connectServer - Connect to Access Server

This command establishes a connection to Access Server running on the specifiedserver and listening for TCP/IP communications on the specified port number.

This command must be issued before other supported Management Consolecommands (except the help - command) can be invoked.

From a single command prompt environment, only one connection to an AccessServer can be maintained at the same time. You must use the disconnectServercommand to end the connection to the Access Server. However, if you have morethan one command environment active at the same time, simultaneous connectionsto different Access Servers is possible (one connection per command environment).

Note: If you have connected to an Access Server through Management Console,you must still issue this command and identify the same Access Server. In otherwords, a connection established to an Access Server through Management Consoleis not recognized in a command environment.

Establishing a connection to an Access Server through Management Console isdiscussed in more detail in Management Console documentation.

SyntaxconnectServer(, , , );

Parameters

A Management Console user defined in Access Server.

The password associated with the Management Console user specified throughthe first parameter (user).

If no password is associated with the Management Console user, specify twodouble quotes ("") for this parameter.

Note: If this command is included in a script file, the specified password willbe encrypted after the script file has been successfully compiled into a batchfile that can be executed.

The host name of the server where Access Server is running.

If Access Server is running on the local system, set this parameter to localhost.

The port number that will be used to establish a connection to Access Server.


Result

None.

Example

connectServer(GSMITH, APPLEJUICE, HOST1, 10101);

The Management Console user GSMITH with the password APPLEJUICE willestablish a connection to Access Server running on the server HOST1, and listeningfor TCP/IP communications on port number 10101.

connectServer(EAHIGGINS, "", LOCALHOST, 4545);

The Management Console user EAHIGGINS will establish a connection to AccessServer running on the local system, and listening for TCP/IP communications onport number 4545.

No password is associated with the user EAHIGGINS.Related concepts

“Scripting support” on page 54Related reference

“help - Display Command Help” on page 41“disconnectServer - Disconnect from Access Server” on page 33“execute - Run Batch File” on page 35

deAssignTable - Unassign Target Table

This command unassigns the specified source table from the currently assignedtarget table.

SyntaxdeAssignTable(, , , );

Parameters

The name of the datastore that will have a target table unassigned from thespecified source table.

The datastore that you specify must be either a dual or target datastore. Formore information about datastores, see Management Console documentation.

The identifier for the source server.

This identifier is specified when creating a new subscription throughManagement Console.


The name of the source table that you want to unassign from the target table.


Result

None.

Example

deAssignTable(ORASUBS, NTORAPUB, GSMITH, EMP);

The source table EMP owned by GSMITH will be deassigned from the target tablethat was assigned to it.

deAssignTable(PRODSUBS, PRODPUB, MASTDB.BMOORE, SALES);

The source table SALES (in the database MASTDB) owned by BMOORE will bedeassigned from the target table that was assigned to it.

deAssignTable(BRANCHAGENT, HQSYS, CUSTLIB, CUSTOMER);

The multi-member source table CUSTOMER located in the library CUSTLIB will bedeassigned from the multi-member target table that was assigned to it.

describe - Describe Selected Tables

This command sends descriptions of all source tables selected to the specifiedsubscription.

Source table descriptions have to be sent to the target environment after a changehas been made to the table definition within Management Console or beforereplicating table data for the first time. For example, if you change columnselections for a source table, the table definition is updated to reflect these changes.Before data from this table can be replicated, a new description of the source tablehas to be sent to the subscription environment to update the current tabledefinition.

The subscription that you reference in this command must have been definedthrough Management Console, as there is no command available in the API tocreate a new subscription.

Syntaxdescribe(, );

Parameters

The name of the datastore that will have descriptions of source tables selectedto one of its subscriptions sent by this command.

The datastore that you specify must be either a dual or source datastore. Formore information about datastores, see Management Console documentationGuide.

The name of the subscription that will have descriptions of its selected sourcetables sent by this command.


Result

None.

Example

describe(ORAPUBS, NTORASUB);

Descriptions of source tables selected to the NTORASUB subscription will be sentto the target environment.

describe(HQAGENT, BRANCHSYS);

Descriptions of source tables selected to the BRANCHSYS subscription will be sentto the target environment.

disconnectAgent - Disconnect from Datastore

This command ends the connection to the specified datastore that has been definedin Access Manager and can be accessed by the Management Console useridentified in connectServer - Connect to Access Server.

To list the datastores that can be specified in this command, use getAgents - GetAccessible Datastores.

Ending a connection to a datastore through Management Console is discussed inmore detail in the Management Console documentation.

SyntaxdisconnectAgent();

Parameters

The name of the datastore that will be disconnected.

Result

None.

Example

disconnectAgent(ORAPUBS);

The connection to the datastore named ORAPUBS will be ended.Related reference

“connectServer - Connect to Access Server” on page 30“getAgents - Get Accessible Datastores” on page 36

disconnectServer - Disconnect from Access Server

This command ends the connection to the Access Server established throughconnectServer - Connect to Access Server.


After successfully issuing this command, you cannot invoke other ManagementConsole commands (except the help - Display Command Help) in the samecommand environment.

Since a connection to only one Access Server can be maintained in each commandenvironment, this command does not require any parameters.

Note: Existing connections to datastores established through the connectAgentcommand are automatically ended when disconnecting from Access Server. This isequivalent to issuing disconnectAgent - Disconnect from Datastore for eachconnected datastore.

SyntaxdisconnectServer();

Parameters

None.

Result

None.

Example

disconnectServer();

The current connection to the Access Server will be ended.

Existing connections to datastores established in the command environment willalso be ended.Related reference

“connectServer - Connect to Access Server” on page 30“help - Display Command Help” on page 41“disconnectAgent - Disconnect from Datastore” on page 33

errorHandle - Define Error Handler

This command determines whether batch file processing should stop or continueupon encountering an error.

This command is primarily intended for use in a script file that includes one ormore execute commands. An invocation applies to all subsequent executecommands prior to the next use of this command.

SyntaxerrorHandle([mode]);

Parameters

modeIndicates whether batch file processing should stop or continue when an erroris encountered.

This is an optional parameter. You can specify one of the following specialvalues:


v continue—batch file processing initiated by execute commands will continuewhen an error is encountered.

v stop—batch file processing initiated by execute commands will stop whenan error is encountered.

If this parameter is omitted, the default setting is stop.

Result

None.

Example

errorHandle();

Batch file processing will stop when an error is encountered.

errorHandle(continue);

Batch file processing will continue when an error is encountered.

execute - Run Batch File

This command runs the specified batch file that was produced as a result ofcompiling a script file.

If you include this command in a script file, it should not reference the batch file inwhich it is contained, as this would lead to recursive executions withouttermination.

Syntaxexecute();

Parameters

The name of the existing batch file that you want to run.

If you specify the name of the batch file without providing the full path, thebatch file must be located in the same folder where the online.bat file resides.

Result

None.

Example

execute(EA.BAT);

The batch file ea.bat located in the same folder where the online.bat file resides,and a sequence of Management Console commands will be performed.

execute(C:\EA\BATCH\SUBSCRIBE.TXT);

The batch file subscribe.txt will run, and a sequence of Management Consolecommands will be performed.


Related concepts

“Scripting support” on page 54

exit - Close Command Environment

This command closes the command environment where this command was issued.

This command ensures that connections established to Access Server anddatastores are completely disconnected before closing the command environment.

If this command is encountered in a script file, batch processing stops and allsubsequent commands in the script file are not performed.

Syntaxexit();

Parameters

None.

Result

None.

Example

exit();

The command environment where this command was issued will be closed.Related concepts

“Opening command environments” on page 23

getAgents - Get Accessible Datastores

This command lists the datastores that have been defined in Access Manager andcan be accessed by the Management Console user identified in connectServer -Connect to Access Server.

Use this command to identify the datastores that you can reference in othercommands that require a datastore name to be specified.

SyntaxgetAgents();

Parameters

None.

Result

This command returns the names of datastores that can be accessed and referencedin other commands.


Example

getAgents();

The datastores that can be accessed and referenced in other commands will belisted.Related reference

“connectServer - Connect to Access Server” on page 30

getSubscriptionActivity - Get Subscription Activity

This command returns replication activity information for one or moresubscriptions.

The subscription that you may reference in this command must have been definedthrough Management Console, as there is no command to create a newsubscription.

Displaying replication activity information through Management Console isdiscussed in more detail in Management Console documentation.

SyntaxgetSubscriptionActivity( [, subscription]);

Parameters

The name of the datastore that will have replication activity information forone or more of its subscriptions returned by this command.

The datastore that you specify must be either a dual or source datastore. Formore information about datastores, see Management Console documentation.

subscriptionThe name of the subscription that will have replication activity informationreturned by this command.

This is an optional parameter. If it is omitted, information will be returnedabout all subscriptions defined for the specified datastore.

Result

This command returns a state that identifies the current replication activity foreach subscription.

Example

getSubscriptionActivity(ORAPUBS);

Replication activity information about all subscriptions defined for the datastoreORAPUBS will be retrieved and displayed.

getSubscriptionActivity(HQAGENT, BRANCHSYS);

Replication activity information about the subscription BRANCHSYS defined forthe datastore HQAGENT will be retrieved and displayed.


getSubscriptions - Get Subscriptions for Datastore

This command lists the subscriptions that have been defined for the specifieddatastore.

Use this command to identify the subscriptions that you can reference in othercommands that require a subscription name to be specified.

SyntaxgetSubscriptions();

Parameters

The name of the datastore for which you want to list existing subscriptions.

Result

This command returns the names of subscriptions defined for the specifieddatastore.

Example

getSubscriptions(ORAPUBS);

The subscriptions defined for the datastore ORAPUBS will be listed.

getSubscriptionStatus - Get Subscription Status

This command returns replication status information for one or more subscriptions.

The subscription that you may reference in this command must have been definedthrough Management Console, as there is no Management Console command tocreate a new subscription.

Displaying replication status information through Management Console isdiscussed in more detail in the Management Console documentation.

SyntaxgetSubscriptionStatus( [, subscription]);

Parameters

The name of the datastore that will have replication status information for oneor more of its subscriptions returned by this command.

The datastore that you specify must be either a dual or source datastore. Formore information about datastores, see the Management Consoledocumentation.

subscriptionThe name of the subscription that will have its replication status returned bythis command.

This is an optional parameter. If it is omitted, information will be returnedabout all subscriptions defined for the specified datastore.


Result

This command returns a state that identifies the current replication status for eachsubscription.

Example

getSubscriptionStatus(ORAPUBS);

Replication status information about all subscriptions defined for the datastoreORAPUBS will be retrieved and displayed.

getSubscriptionStatus(HQAGENT, BRANCHSYS);

Replication status information about the subscription BRANCHSYS defined for thedatastore HQAGENT will be retrieved and displayed.

getSubscriptionTables - Get Subscription Tables

This command lists the source tables that are currently selected to the specifiedsubscription.

Use this command to identify the source tables that you can reference in othercommands that require a source table name to be specified.

SyntaxgetSubscriptionTables(, [, path]);

Parameters

The name of the datastore for which you want to list selected source tables.

The datastore that you specify must be either a dual or source datastore.

The name of the subscription for which you want to list selected source tables.

pathDepending on the type of datastore, the owner of the source tables or thelibrary where the source tables are located.

This parameter is optional. If it is omitted, all source tables selected to thespecified subscription are listed.

Result

This command returns the names of source tables selected to the specifiedsubscription.

Example

getSubscriptionTables(ORAPUBS, NTORASUB);

All source tables selected to the subscription NTORASUB will be listed.

getSubscriptionTables(HQAGENT, BRANCHSYS, EAHIGGINS);


Source tables owned by EAHIGGINS that are selected to the subscriptionBRANCHSYS will be listed.

getSubscriptionTables(PRODPUBS, PRODSUB, MASTDB.BMOORE);

Source tables (in the database MASTDB) owned by BMOORE that are selected tothe subscription PRODSUB will be listed.

getSubscriptionTables(HQAGENT, BRANCHSYS, CUSTLIB);

Source tables located in library CUSTLIB that are selected to the subscriptionBRANCHSYS will be listed.

getTableStatus - Get Source Table Status

This command retrieves the status of a source table selected to the specifiedsubscription.

The status of a source table can be displayed in Management Console, and isdiscussed in more detail in Management Console documentation.

SyntaxgetTableStatus(, , , );

Parameters

The name of the datastore that has the source table currently selected to thespecified subscription.

The source that you specify must be either a dual or source datastore.

The name of the subscription to which the source table is selected.


The name of the source table that will have its status returned by thiscommand.

Result

This command returns either idle, refresh, or active.

Example

getTableStatus(ORAPUBS, NTORASUB, GSMITH, EMP);

The current status of the source table named EMP owned by GSMITH that iscurrently selected to the subscription NTORASUB will be returned.

getTableStatus(PRODPUBS, PRODSUB, MASTDB.BMOORE, SALES);


The current status of the source table named SALES (in the database MASTDB)owned by BMOORE that is currently selected to the subscription PRODSUB willbe returned.

getTableStatus(HQAGENT, BRANCHSYS, CUSTLIB, CUSTOMER);

The current status of the source table named CUSTOMER located in libraryCUSTLIB that is currently selected to the subscription BRANCHSYS will bereturned.

help - Display Command Help

This command displays help information about the specified command.

This command can be issued before or after establishing a connection to AccessServer.

Syntaxhelp([command]);

Parameters

commandThe name of the command for which you want to display help information.

This parameter is optional. If it is omitted, a list of Management Consolecommands is displayed without help information.

Command names are case-sensitive, and must be entered as documented.

Result

This command lists the Management Console commands (if no parameter isspecified) or displays help information for the specified command.

Example

help();

All Management Console commands will be listed.

help(connectAgent);

Help information for the connectAgent command will be displayed.

reAddTable - Re-add Table in Catalog

This command changes the metadata definition of an existing table in the catalog.

You must issue this command if you have physically changed the table in someway in the database. For example, adding a new column or modifying a columnname are changes that affect the physical table. This command ensures that thetable definition within Management Console is updated accordingly.

Note: Mirroring of the named table to all subscriptions must be stopped before thetable can be successfully re-added.


Re-adding a catalog table through Management Console is discussed in more detailin the Management Console documentation.

SyntaxreAddTable(, , );

Parameters

The name of the datastore that will have a table re-added to its catalog.


Depending on the type of datastore, the owner of the catalog table or thelibrary where the catalog table is located.

The name of the table that will be re-added in the catalog.

Result

None.

Example

reAddTable(ORAPUBS, GSMITH, EMP);

The table named EMP owned by GSMITH will be re-added in the catalog for thedatastore ORAPUBS.

reAddTable(PRODPUBS, MASTDB.BMOORE, SALES);

The table named SALES (in the database MASTDB) owned by BMOORE will be re-addedin the catalog for the datastore PRODPUBS.

reAddTable(HQAGENT, CUSTLIB, CUSTOMER);

The table named CUSTOMER located in library CUSTLIB will be re-added in thecatalog for the datastore HQAGENT.

removeTable - Remove Table from Catalog

This command removes a table from the catalog for the specified datastore.

SyntaxremoveTable(, , [, endjrn]);

Parameters

The name of the datastore that will have a table removed from its catalog.


Depending on the type of datastore, the owner of the catalog table or thelibrary where the catalog table is located.


The name of the table that will be removed from the catalog.

endjrnIndicates whether active journalling of the specified table will be stopped.

Set this parameter to "Y" to stop active journaling of the table or "N" tocontinue active journaling of the table.

This parameter is optional and only applies to DB2 for i tables.

Result

None.

Example

removeTable(ORAPUBS, GSMITH, EMP);

The table named EMP owned by GSMITH will be removed from the catalog for thedatastore ORAPUBS.

removeTable(PRODPUBS, MASTDB.BMOORE, SALES);

The table named SALES (in the database MASTDB) owned by BMOORE will be removedfrom the catalog for the datastore PRODPUBS.

removeTable(HQAGENT, CUSTLIB, CUSTOMER, "Y");

The table named CUSTOMER located in library CUSTLIB will be removed from thecatalog for the datastore HQAGENT.

Active journaling of the table will be stopped.

setReplication - Set Replication Method

This command sets the method that you want to use to replicate the specifiedsource table.

For platforms that support table updates by unique key or relative record number(RRN), this command also allows you to set the method of applying replicatedupdates to the subscription table.

The subscription that you reference in this command must have been definedthrough Management Console, as there is no command to create a newsubscription.

Setting the replication or update methods for a source table through ManagementConsole is discussed in more detail in Management Console documentation.

SyntaxsetReplication(, , , , , , [, updmethod]);


Parameters

The name of the datastore that will have the replication or update methods fora selected source table changed by this command.

The datastores that you specify must be either a dual or source datastore. Formore information about datastores, see the Management Consoledocumentation.



The name of the source table that will have its replication or update methodschanged by this command.

Depending on the type of datastore, the owner of the journal or the librarywhere the journal is located.

This parameter only applies to datastores that allow you to specify the journalwhere source table updates are maintained, and when the selected replicationmethod is mirror.

Set this parameter to "" in order to specify the journal owner or locationidentified through a recognized InfoSphere CDC system parameter.

The name of the journal where source table updates are maintained.

This parameter only applies to datastores that allow you to specify the journalwhere source table updates are maintained, and when the selected replicationmethod is mirror.

Set this parameter to "" in order to specify the journal name identified througha recognized InfoSphere CDC system parameter

This parameter must be set to refresh or mirror. For descriptions of thesereplication methods, see the Management Console documentation.

The method that you want to use to replicate the specified source table.

updmethodThe method that you want to use to apply replicated updates to thesubscription table.

This is an optional parameter that can be specified when working withplatforms that support updates either by unique key or relative record number(RRN). When specified, this parameter must be set to key or rrn. The defaultsetting is key. For descriptions of these update methods, see the ManagementConsole documentation.

Note: You cannot specify an update method without also specifying areplication method.


Result

None.

Example

setReplication(ORAPUBS, NTORASUB, GSMITH, EMP, GSMITH, EMPJRN, mirror);

The replication method for the source table named EMP owned by GSMITH that iscurrently selected to the subscription NTORASUB will be set to mirror.

The journal named EMPJRN owned by GSMITH is used for source table updates.

setReplication(PRODPUBS, PRODSUB, MASTDB.BMOORE, SALES, MASTDB.BMOORE,SALESJRN, refresh);

The replication method for the source table named SALES (in the databaseMASTDB) owned by BMOORE that is currently selected to the subscriptionPRODSUB will be set to refresh.

The journal named SALESJRN (in the database MASTDB) owned by BMOORE isused for source table updates.

setReplication(HQAGENT, BRANCHSYS, CUSTLIB, CUSTOMER, refresh, rrn);

The replication method for the source table named CUSTOMER located in libraryCUSTLIB that is currently selected to the subscription BRANCHSYS will be set torefresh.

The update method for this table will be set to rrn.

setTableStatus - Set Source Table Status

This command sets the status of a source table selected to the specifiedsubscription.

The subscription that you reference in this command must have been definedthrough Management Console, as there is no command to create a newsubscription.

Setting the status of a source table through Management Console is discussed inmore detail in Management Console documentation.

SyntaxsetTableStatus(, , , , ,);

Parameters

The name of the datastore that will have a selected source table set to arecognized state.





The name of the source table that will be set to a recognized state.

The state that will be assigned to the source table specified in the command.

This parameter must be set to either idle, refresh, or active. For definitions ofthese states, see the Management Console documentation.

Result

None.

Example

setTableStatus(ORAPUBS, NTORASUB, GSMITH, EMP, idle);

The source table named EMP owned by GSMITH that is currently selected to thesubscription NTORASUB will be set to an idle state.

setTableStatus(PRODPUBS, PRODSUB, MASTDB.BMOORE, SALES, refresh);

The source table named SALES (in the database MASTDB) owned by BMOOREthat is currently selected to the subscription PRODSUB will be set to a refreshstate.

setTableStatus(HQAGENT, BRANCHSYS, CUSTLIB, CUSTOMER, active);

The source table named CUSTOMER located in library CUSTLIB that is currentlyselected to the subscription BRANCHSYS will be set to an active state.

startRefresh - Start Refresh

This command starts refresh activities for one or all subscriptions defined for adatastore.

Refresh activities can be started for all selected source tables or just those tablesthat have a status of REFRESH.

The subscriptions that you reference in this command must have been definedthrough Management Console, as there is no command to create newsubscriptions.

Starting refresh activities through Management Console is discussed in more detailin Management Console documentation.

SyntaxstartRefresh(, [, tabrfsh]);


Parameters

The name of the datastore that will have refresh activities started by thiscommand.


The subscriptions that will have refresh activities started by this command.

You can specify a subscription name or the special value of *all to referenceall subscriptions defined for the specified datastore.

tabrfshIndicates whether all or certain selected tables are included in refresh activities.

This is an optional parameter. You can specify one of the following specialvalues:v flagged—selected source tables that have a status of refresh are included in

refresh activities.v *all—all selected source tables are included in refresh activities regardless of

table status.

If this parameter is omitted, the default setting is flagged.

Note: Dependi

infosphere change data capture management console,version 6.5€¦ · the api supports a number of...

Documents