IBM InfoSphere Replication Server IBM InfoSphere Data Event Publisher

IBM InfoSphere Replication Server IBM InfoSphere Data Event Publisher Version 9.7 ASNCLP Program Reference for Replication and Event Publishing SC19-1018-04

IBM InfoSphere Replication Server IBM InfoSphere Data Event Publisher Version 9.7 ASNCLP Program Reference for Replication and Event Publishing SC19-1018-04

Note Before using this information and the product that it supports, read the information in Notices on page 291. Copyright International Business Machines Corporation 2004, 2009. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Chapter 1. Getting started with the ASNCLP program.......... 1 Supported operating systems......... 1 Setting up a Java environment to run the ASNCLP program................ 1 Binding z/os packages for the ASNCLP program.. 2 Running the ASNCLP commands in interactive mode 3 Running the ASNCLP commands in execute-immediately mode......... 3 Running the ASNCLP commands by using an input file.................. 4 ASNCLP configuration file......... 4 Chapter 2. ASNCLP commands for SQL replication.............. 7 Sample ASNCLP scripts for setting up SQL replication............... 8 ALTER MEMBER ADD COLS command..... 11 ALTER REGISTRATION command...... 12 ALTER SUBSCRIPTION SET command..... 15 ASNCLP SESSION SET TO command (SQL replication).............. 17 CREATE CONTROL TABLES FOR command (SQL replication).............. 18 CREATE MEMBER command........ 20 CREATE REGISTRATION command...... 28 CREATE STMT command......... 33 CREATE SUBSCRIPTION SET command.... 35 DROP CONTROL TABLES ON command.... 37 DROP MEMBER command......... 38 DROP REGISTRATION command....... 39 DROP STMT command.......... 39 DROP SUBSCRIPTION SET command..... 40 OFFLINE LOAD command......... 41 PROMOTE REGISTRATION command..... 41 PROMOTE SUBSCRIPTION SET command.... 43 SET CAPTURE SCHEMA command (SQL replication).............. 45 SET DROP command (SQL replication)..... 46 SET LOG command........... 47 SET OUTPUT command (SQL replication).... 48 SET PROFILE command (SQL replication).... 48 SET RUN SCRIPT command (SQL replication)... 52 SET SERVER command (SQL replication).... 55 SET TRACE command........... 58 Chapter 3. Sample ASNCLP scripts for Q replication............ 59 Sample ASNCLP scripts for setting up unidirectional Q replication......... 59 Sample ASNCLP scripts for setting up unidirectional Q replication from a Classic data source................ 62 Sample ASNCLP scripts for setting up bidirectional Q replication.............. 65 Sample ASNCLP scripts for setting up peer-to-peer Q replication (two servers)......... 70 Sample ASNCLP scripts for setting up peer-to-peer Q replication (three servers)......... 75 Sample ASNCLP script for promoting unidirectional configurations............. 81 Sample ASNCLP scripts for promoting peer-to-peer configurations............. 82 Chapter 4. ASNCLP commands for unidirectional Q replication...... 85 ALTER ADD COLUMN command...... 86 ALTER CAPTURE PARAMETERS command (Classic replication)............ 88 ALTER CONFIGURATION APPLY command... 88 ALTER REPLQMAP command........ 89 ALTER QSUB command (unidirectional replication) 91 ASNCLP SESSION SET TO command..... 95 CREATE CONTROL TABLES FOR command... 96 CREATE REPLQMAP command....... 102 CREATE QSUB command (unidirectional replication).............. 103 DROP CONTROL TABLES ON command.... 119 DROP REPLQMAP command........ 119 DROP QSUB command (unidirectional Q replication).............. 120 LIST QSUB command (Q replication)..... 121 LIST APPLY SCHEMA command....... 122 LIST CAPTURE SCHEMA command..... 123 LIST REPLQMAP command (Q replication)... 124 LOAD DONE command.......... 126 PROMOTE QSUB command........ 127 PROMOTE REPLQMAP command...... 129 SET APPLY SCHEMA command....... 130 SET CAPTURE SCHEMA command...... 130 SET DROP command (unidirectional replication) 131 SET LOG command........... 132 SET OUTPUT command.......... 133 SET PROFILE command.......... 133 SET QMANAGER command........ 137 SET RUN SCRIPT command........ 138 SET SERVER command.......... 140 SET TRACE command.......... 144 SHOW SET ENV command........ 144 START QSUB command.......... 144 STOP QSUB command.......... 146 VALIDATE WSMQ ENVIRONMENT FOR command.............. 147 VALIDATE WSMQ MESSAGE FLOW FOR REPLQMAP command.......... 148 Chapter 5. ASNCLP commands for multidirectional Q replication.... 151 Copyright IBM Corp. 2004, 2009 iii

ALTER REPLQMAP command....... 152 ALTER QSUB command (bidirectional replication) 154 ALTER QSUB command (peer-to-peer replication) 157 ASNCLP SESSION SET TO command..... 158 CREATE CONTROL TABLES FOR command... 159 CREATE REPLQMAP command....... 165 CREATE QSUB command (bidirectional replication).............. 167 CREATE QSUB command (peer-to-peer replication) 171 DROP CONTROL TABLES ON command.... 174 DROP REPLQMAP command........ 175 DROP SUBGROUP command (multidirectional Q replication).............. 175 DROP SUBTYPE command (bidirectional replication).............. 176 DROP SUBTYPE command (peer-to-peer replication).............. 176 LIST APPLY SCHEMA command....... 177 LIST CAPTURE SCHEMA command..... 178 LOAD DONE command.......... 179 LOAD MULTIDIR REPL SCRIPT command (multidirectional Q replication)....... 180 PROMOTE QSUB command........ 182 PROMOTE REPLQMAP command...... 183 SET APPLY SCHEMA command....... 185 SET BIDI NODE command......... 185 SET CAPTURE SCHEMA command...... 187 SET CONNECTION command (multidirectional Q replication).............. 188 SET ENFORCE MATCHING CONSTRAINTS command (multidirectional Q replication).... 189 SET LOG command........... 189 SET MULTIDIR SCHEMA command (multidirectional Q replication)....... 190 SET OUTPUT command (multidirectional Q replication).............. 190 SET PEER NODE command........ 191 SET PROFILE command.......... 193 SET QMANAGER command........ 196 SET REFERENCE TABLE command (multidirectional Q replication)....... 197 SET SERVER command (multidirectional Q replication).............. 198 SET SUBGROUP command (multidirectional Q replication).............. 200 SET TABLES command (multidirectional Q replication).............. 200 SET TRACE command.......... 201 SHOW SET ENV command........ 202 START QSUB command.......... 202 STOP QSUB command.......... 203 VALIDATE WSMQ ENVIRONMENT FOR command.............. 205 VALIDATE WSMQ MESSAGE FLOW FOR REPLQMAP command.......... 206 Chapter 6. ASNCLP commands for event publishing.......... 207 Sample ASNCLP scripts for setting up event publishing.............. 208 ALTER ADD COLUMN command...... 211 iv ASNCLP Program Reference for Replication and Event Publishing ALTER PUB command.......... 212 ALTER PUBQMAP command........ 214 ASNCLP SESSION SET TO command..... 215 CREATE CONTROL TABLES FOR command... 216 CREATE PUB command.......... 222 CREATE PUBQMAP command....... 226 DROP CONTROL TABLES ON command.... 228 DROP PUB command.......... 228 DROP PUBQMAP command........ 229 LIST CAPTURE SCHEMA command..... 229 LIST PUBS command........... 230 LIST PUBQMAPS command........ 231 PROMOTE PUB command......... 232 PROMOTE PUBQMAP command...... 234 SET CAPTURE SCHEMA command...... 235 SET LOG command........... 236 SET OUTPUT command.......... 236 SET QMANAGER command........ 237 SET RUN SCRIPT command........ 238 SET SERVER command (event publishing)... 240 SET TRACE command.......... 243 START PUB command.......... 244 STOP PUB command........... 244 VALIDATE WSMQ ENVIRONMENT FOR command.............. 244 Chapter 7. ASNCLP commands for the Replication Alert Monitor...... 247 Sample ASNCLP scripts for setting up the Replication Alert Monitor......... 248 ALTER ALERT CONDITIONS FOR APPLY command.............. 251 ALTER ALERT CONDITIONS FOR CAPTURE command.............. 253 ALTER ALERT CONDITIONS FOR QAPPLY command.............. 256 ALTER ALERT CONDITIONS FOR QCAPTURE command.............. 258 ALTER CONTACT command........ 260 ALTER GROUP command......... 261 ALTER MONITOR SUSPENSION command... 261 ALTER MONITOR SUSPENSION TEMPLATE command.............. 262 CREATE ALERT CONDITIONS FOR APPLY command.............. 263 CREATE ALERT CONDITIONS FOR CAPTURE command.............. 266 CREATE ALERT CONDITIONS FOR QAPPLY command.............. 267 CREATE ALERT CONDITIONS FOR QCAPTURE command.............. 269 CREATE CONTACT command....... 271 CREATE CONTROL TABLES FOR command... 272 CREATE GROUP command........ 274 CREATE MONITOR SUSPENSION command.. 274 CREATE MONITOR SUSPENSION TEMPLATE command.............. 276 DELEGATE CONTACT command...... 277 DROP ALERT CONDITIONS FOR APPLY command.............. 277

DROP ALERT CONDITIONS FOR CAPTURE command.............. 278 DROP ALERT CONDITIONS FOR QAPPLY command.............. 278 DROP ALERT CONDITIONS FOR QCAPTURE command.............. 278 DROP CONTACT command........ 279 DROP GROUP command......... 279 DROP MONITOR SUSPENSION command... 280 DROP MONITOR SUSPENSION TEMPLATE command.............. 280 LIST MONITOR SUSPENSION command.... 281 LIST MONITOR SUSPENSION TEMPLATE command.............. 281 SET OUTPUT command.......... 281 SET SERVER command.......... 282 SUBSTITUTE CONTACT command...... 283 Product documentation....... 285 Contacting IBM............ 285 How to read syntax diagrams.... 287 Product accessibility........ 289 Notices.............. 291 Trademarks.............. 293 Index............... 295 Contents v

vi ASNCLP Program Reference for Replication and Event Publishing

Chapter 1. Getting started with the ASNCLP program Supported operating systems The replication programs store information about your configurations in control tables. The ASNCLP commands create, modify, and remove this information. For example, the ASNCLP program provides a command to create a Q subscription. In Q replication, the output of a command is a SQL script that inserts information into the control tables about the source, target, queues, and other options. Each ASNCLP command works with only a subset of information. You can use multiple commands together to generate the SQL for an entire configuration. Before you run the ASNCLP program, you need to configure your environment. Once your environment is configured, you ll need to know a few basics about using the ASNCLP program. Some commands are available only for specific types of replication or publishing configurations. The ASNCLP program runs on Linux, UNIX, Windows, and UNIX System Services (USS) on z/os. The ASNCLP program does not run natively on z/os or System i. The ASNCLP commands will generate replication definitions for all operating system environments that are supported by the replication products: z/os, System i (SQL replication only), Linux, UNIX, and Windows. You must have connectivity to each server for which you are generating replication definitions; that is, you must be able to issue a database connection statement to each of the servers. Note: Additional configuration steps are required to enable the ASNCLP to run on USS. For details, see Optional: Enabling the ASNCLP program to run on USS in the Information Management Software for z/os Solutions Information Center. Restriction: The ASNCLP program does not support z/vm or VSE because DB2 in these operating-system environments does not support the replication architecture for DB2 Version 8 and later. Setting up a Java environment to run the ASNCLP program The ASNCLP program runs in a Java environment. Your PATH environment variable must contain a path to a Java runtime environment in order to run the ASNCLP. Use the following procedure if the PATH environment does not contain a path to a Java runtime environment. Procedure Add the following path to your PATH environment variable: Copyright IBM Corp. 2004, 2009 1

INSTDIR\java\jdk Where INSTDIR is the DB2 instance directory. On Linux and UNIX, the instance directory is the INSTDIR/sqllib directory, where INSTDIR is the home directory of the instance owner. On Windows, the instance directory is the \sqllib directory where DB2 was installed. For all DB2 products except the IBM Data Server Runtime Client, the DB2 Database for Linux, UNIX, and Windows installation process automatically installs the SDK for Java. If you need to install the SDK, go to the IBM developer kits page on IBM developerworks: http://www.ibm.com/developerworks/java/jdk/ index.html Examples To set the PATH environment variable from a UNIX command prompt: export CLASSPATH=$PATH :/u/myinst/sqllib/java/jdk; To set the PATH environment variable from a Windows command prompt: set CLASSPATH=%PATH%;%c:\Program File\sqllib\java\jdk; Binding z/os packages for the ASNCLP program Before you use the ASNCLP program with DB2 for z/os, you must bind the basic DRDA and CLI packages to the DB2 subsystem that you will be working with. Before you begin Before you can bind the z/os packages, you must connect to the DB2 subsystem on the z/os server. Procedure To bind the basic z/os packages for the ASNCLP program, open an operating system command prompt and issue the following command: bind @ddcsmvs.lst blocking all sqlerror continue db2 bind @db2cli.lst isolation ur blocking all If you do not perform this bind, the first time you use the ASNCLP program with a DB2 for z/os server, the ASNCLP program might return the following error message: ASN1560E The replication action ended in error. An SQL error was encountered. SQL Message: "[IBM][CLI Driver][DB2] SQL0805N Package "package_name" was not found. SQLSTATE=51002 2 ASNCLP Program Reference for Replication and Event Publishing

Running the ASNCLP commands in interactive mode You can run the ASNCLP commands in interactive mode from a command prompt. Procedure To run the ASNCLP commands in interactive mode: 1. Open an operating system command prompt and issue the following command: ASNCLP The ASNCLP command starts the ASNCLP program and changes the command prompt to Repl >. 2. Issue any of the ASNCLP commands. For example: To set the Q Capture server to the database aliasname, issue the following command: SET SERVER CAPTURE TO DBALIAS aliasname 3. To exit the ASNCLP program, issue the following command: quit To get help for the ASNCLP program, issue the following command from an operating system command prompt: ASNCLP? Running the ASNCLP commands in execute-immediately mode The execute-immediately mode is useful when you need to issue a single command. You can use the START QSUB command, STOP QSUB command, and LIST commands in execute-immediately mode. Before you begin The ASNCLP command that you execute cannot rely on previous commands. The command must be self-contained. For example, many commands rely on the SET SERVER command to define where objects are created. Procedure To execute an ASNCLP command in execute-immediately mode: 1. Open an operating system command prompt. 2. Run the ASNCLP command: ASNCLP -exe my_command Replace my_command with the ASNCLP command that you want to immediately execute. The following command is an example of starting a Q subscription for a Classic replication source: asnclp -exe START QSUB SUBNAME sub1 CAP SERVER OPTIONS CONFIG SERVER classic1 FILE asnservers.ini ID id1 PASSWORD passwd1 Chapter 1. Getting started with the ASNCLP program 3

Running the ASNCLP commands by using an input file You can run the ASNCLP commands in batch mode by using an input file. Procedure ASNCLP configuration file To run the ASNCLP commands in batch mode by using an input file: 1. Create an input file that contains the ASNCLP commands that you want to run. Commands in the input file must be delimited by the semicolon (;) and can span multiple lines. You can also add comments to the input file by beginning the comment line with a number (#) sign. 2. Open an operating system command prompt and issue the following command: ASNCLP -f myfile.in In the example the input-file name is myfile.in and can consist of any valid file name plus an extension. You can also specify a full file path and file name. For example: ASNCLP -f c:\temp\myfile.in The ASNCLP command starts the ASNCLP program, which processes all of the commands in the input file until it encounters an error or the end of the file. Tip: You can specify that the ASNCLP program ignores some errors that it encounters when creating objects that already exist by using the SET RUN SCRIPT LATER GENERATE SQL FOR EXISTING YES command. If your input file does not contain the quit command, you can exit the ASNCLP program by issuing the following command: quit To access Classic sources or run on UNIX System Services (USS) for z/os, the ASNCLP program requires connectivity information to be provided through a configuration file. The ASNCLP configuration file contains a group of lines for each data source that the ASNCLP needs to access. Each grouping has a unique name for the group followed by lines that specify the connection information. The unique name is used in ASNCLP scripts to identify a source. Specify the server information in the configuration file in the following format: [NAME] Type=source_type Data source=data_source_name Host=host_name Port=port_number Codepage=code_page... 4 ASNCLP Program Reference for Replication and Event Publishing

Parameters [NAME] Specifies a unique name for a configuration. You provide this name in ASNCLP scripts so that the ASNCLP program can connect to the data source. You can define multiple servers in a single configuration file by indicating the beginning of a new server definition in the enclosing brackets (for example, [NAME2]). Important: The value cannot be longer than eight characters. Type Specifies the type of server: Classic replication Specify Type=classic. ASNCLP on USS If the server is DB2 for z/os or DB2 for Linux, UNIX, and Windows and you are running the ASNCLP on USS, specify Type=DB2. Data source Specifies the location of the source data: Classic replication Specifies the name of the query processor on the Classic data server. ASNCLP on USS If you are running the ASNCLP on USS, for DB2 sources this parameter specifies the DB2 for z/os location name or DB2 for Linux, UNIX, and Windows database name. Host Specifies the host name or IP address of the data server where the data_source_name resides. Port Port is the port number of the server where the data source resides. Codepage Codepage is an optional parameter for Classic sources that describes the code page of the data. Example 1 The following example shows a configuration file that is used on USS to specify a connection to a DB2 for z/os subsystem: [DB2ZOS] Type=DB2 Data source=dsn7 Host=stplex4a.svl.ibm.com Port=2080 Example 2 The following example shows a configuration file with multiple server definitions: [server_1] Type=classic Data source=cacsamp1 Host=123.123.123.1 Port=8096 [server_2] Chapter 1. Getting started with the ASNCLP program 5

Type=classic Data source=cacsales Host=145.145.231.87 Port=8095 Usage notes You can save the configuration file to any location. The default file name is asnservers.ini. You must use the SET SERVER command to provide the ASNCLP program with the location of the configuration file. The following example shows that the asnservers.ini configuration file is saved in the /home/db2inst/sqllib/ classic_files/ directory. SET SERVER capture TO CONFIG SERVER cacsamp1 FILE "/home/db2inst/sqllib/classic_files/asnservers.ini" ID my_user_id PASSWORD "my_password"; 6 ASNCLP Program Reference for Replication and Event Publishing

Chapter 2. ASNCLP commands for SQL replication The ASNCLP commands for SQL replication define and change objects such as control tables, registrations, and subscription sets. Sample ASNCLP scripts for setting up SQL replication on page 8 demonstrates how you can combine SQL replication commands to create an ASNCLP setup script. Table 1 lists the ASNCLP commands for SQL replication and links to topics that describe each command. Table 1. ASNCLP commands for SQL replication If you want to... Use this command Add columns to an existing member ALTER MEMBER ADD COLS command on page 11 Change the properties of a registration ALTER REGISTRATION command on page 12 Change the properties of a subscription set ALTER SUBSCRIPTION SET command on page 15 Establish a session for SQL replication ASNCLP SESSION SET TO command (SQL replication) on page 17 Create control tables CREATE CONTROL TABLES FOR command (SQL replication) on page 18 Create a subscription-set member CREATE MEMBER command on page 20 Create a registration CREATE REGISTRATION command on page 28 Create a SQL statement that is processed with an existing CREATE STMT command on page 33 subscription set Create a subscription set CREATE SUBSCRIPTION SET command on page 35 Drop control tables DROP CONTROL TABLES ON command on page 37 Delete a subscription-set member DROP MEMBER command on page 38 Delete a registration DROP REGISTRATION command on page 39 Delete SQL statements for an existing subscription set DROP STMT command on page 39 Delete a subscription set DROP SUBSCRIPTION SET command on page 40 Control a manual full refresh for offline load procedures OFFLINE LOAD command on page 41 Promote a registration PROMOTE REGISTRATION command on page 41 Promote a subscription set PROMOTE SUBSCRIPTION SET command on page 43 Set a source and target Capture schema for all task commands Specify whether to drop the table space when you drop the replication object that it contains SET CAPTURE SCHEMA command (SQL replication) on page 45 SET DROP command (SQL replication) on page 46 Set the log file name for the ASNCLP program SET LOG command on page 47 Specify a name for the output files that contain the SQL SET OUTPUT command (SQL replication) on page 48 scripts Set up customization rules for creating table space objects SET PROFILE command (SQL replication) on page 48 Specify whether to automatically run the SQL statements before the ASNCLP commands process the next task command SET RUN SCRIPT command (SQL replication) on page 52 Copyright IBM Corp. 2004, 2009 7

Table 1. ASNCLP commands for SQL replication (continued) If you want to... Specify the server (database) used in the ASNCLP session, authentication information, and other required parameters for connecting to the server Enable and disable the tracing for the ASNCLP commands Use this command SET SERVER command (SQL replication) on page 55 SET TRACE command on page 58 Sample ASNCLP scripts for setting up SQL replication This sample contains five ASNCLP scripts for setting up a basic SQL replication environment. It includes Capture control tables, a registration, Apply control tables, a subscription set, and a subscription-set member. Each ASNCLP script generates one or more SQL scripts to create a replication object. Because some replication objects depend on the existence of other objects, run the ASNCLP scripts and the SQL scripts that they generate in the following order: 1. Capture control tables 2. Registration 3. Apply control tables 4. Subscription set (generates one SQL script that creates definitions at the Capture control server and the Apply control server). 5. Subscription-set member (generates three SQL scripts that create definitions at the Capture control server and the Apply control server and create a target table and table space at the target server. Table 2 on page 11 below the sample describes each SQL script. This sample has a section for each ASNCLP script, which you can copy to a text file and run by using the ASNCLP -f filename command. Within the code sample in each section, details about each group of commands are preceded by a comment character (#). ASNCLP script 1 (Capture control tables) This script generates SQL statements that create Capture control tables at the SAMPLE database. It includes commands for the following tasks: 1 Setting the environment 2 Creating Capture control tables 3 Ending the ASNCLP session # 1 Setting the environment # The scope of environment commands is the entire ASNCLP script file unless # the commands are overridden by another value. # In the SET SERVER command, the user ID and password are optional. If you omit # these keywords, the ASNCLP will use the implicit ID and password for connecting # to the database. # The SET OUTPUT command generates a SQL script, capctrl.sql. # The SET LOG command sets one log file, capctrl.err, to record results for the # ASNCLP script. # The SET RUN SCRIPT LATER option allows you to review the SQL scripts before # they are run. SET SERVER CAPTURE TO DB SAMPLE ID DB2ADMIN PASSWORD "passw0rd"; SET OUTPUT CAPTURE SCRIPT "capctrl.sql"; 8 ASNCLP Program Reference for Replication and Event Publishing

SET LOG "capctrl.err"; SET RUN SCRIPT LATER; # 2 Creating Capture control tables # This command generates a SQL script that connects to the SAMPLE database and # creates the control tables. CREATE CONTROL TABLES FOR CAPTURE SERVER; # 3 Ending the ASNCLP session. QUIT; ASNCLP script 2 (registration) This script generates SQL statements that register the PROJECT table at the SAMPLE database for replication. It includes commands for the following tasks: 1 Setting the environment 2 Registering a source table 3 Ending the ASNCLP session. # 1 Setting the environment # The SET OUTPUT command generates a SQL script, register.sql. SET SERVER CAPTURE TO DB SAMPLE ID DB2ADMIN PASSWORD "passw0rd"; SET OUTPUT CAPTURE SCRIPT "register.sql"; SET LOG "register.err"; SET RUN SCRIPT LATER; # 2 Registering a source table. # The CREATE REGISTRATION command specifies the PROJECT table. The # DIFFERENTIAL REFRESH STAGE keywords specify to update the target table # periodically when the source table changes, and create a change-date (CD) # table named CDPROJECT. Because the COLS keyword is not specified, all columns # in the source table are registered. CREATE REGISTRATION (DB2ADMIN.Project) DIFFERENTIAL REFRESH STAGE CDPROJECT; # 3 Ending the ASNCLP session. QUIT; ASNCLP script 3 (Apply control tables) This script generates SQL statements that create the Apply control tables at the TARGET database. It includes commands for the following tasks: 1 Setting the environment 2 Creating Apply control tables 3 Ending the ASNCLP session # 1 Setting the environment # The SET OUTPUT command generates a SQL script, appctrl.sql. SET SERVER CONTROL TO DB TARGET ID DB2ADMIN PASSWORD "passw0rd"; SET OUTPUT CONTROL SCRIPT "appctrl.sql"; SET LOG "appctrl.err"; SET RUN SCRIPT LATER; # 2 Creating Apply control tables # These statements generate a SQL script that connects to the TARGET database # and creates the control tables. CREATE CONTROL TABLES FOR APPLY CONTROL SERVER; Chapter 2. ASNCLP commands for SQL replication 9

# 3 Ending the ASNCLP session. QUIT; ASNCLP script 4 (subscription set) This script generates SQL statements that create a subscription set. It includes commands for the following tasks: 1 Setting the environment 2 Creating a subscription set 3 Ending the ASNCLP session. # 1 Setting the environment # Two SET SERVER commands are used because the subscription set definitions # are stored in both the Capture control tables and Apply control tables. # The SET OUTPUT command generates one script, ctlsubset.sql, which inserts # the subscription set definition in the IBMSNAP_SUBS_SET table. SET SERVER CAPTURE TO DB SAMPLE ID DB2ADMIN PASSWORD "passw0rd"; SET SERVER CONTROL TO DB TARGET ID DB2ADMIN PASSWORD "passw0rd"; SET SERVER TARGET TO DB TARGET ID DB2ADMIN PASSWORD "passw0rd"; SET OUTPUT CONTROL SCRIPT "ctlsubset.sql"; SET LOG "subset.err"; SET RUN SCRIPT LATER; # 2 Creating a subscription set # The CREATE SUBSCRIPTION SET command creates a set named SET00 with an Apply # qualifier of AQ00. It specifies that the set be activated indefinitely on a # specified start date and time, and that the set be processed every minute. CREATE SUBSCRIPTION SET SETNAME SET00 APPLYQUAL AQ00 ACTIVATE YES TIMING INTERVAL 1 START DATE "2006-10-22" TIME "09:00:00.000000"; # 3 Ending the ASNCLP session. QUIT; ASNCLP script 5 (subscription-set member) This script generates SQL statements that create a subscription-set member for the registered source table PROJECT. It includes commands for the following tasks: 1 Setting the environment 2 Creating a subscription-set member 3 Ending the ASNCLP session. # 1 Setting the environment # The SET OUTPUT command generates three SQL scripts, capmember.sql and # appmember.sql to define the subscription set member in the Capture and # Apply control tables, and projtrg.sql to create a target table and table # space. SET SERVER CAPTURE TO DB SAMPLE ID DB2ADMIN PASSWORD "passw0rd"; SET SERVER CONTROL TO DB TARGET ID DB2ADMIN PASSWORD "passw0rd"; SET SERVER TARGET TO DB TARGET ID DB2ADMIN PASSWORD "passw0rd"; SET OUTPUT CAPTURE SCRIPT "capmember.sql" CONTROL SCRIPT "appmember.sql" TARGET SCRIPT "projtrg.sql"; SET LOG "member.err"; SET RUN SCRIPT LATER; # 2 Creating a subscription-set member. # The SET PROFILE command creates a profile, TBSPROFILE, to store options # for the tablespace that is used by the target table. The CREATE MEMBER command 10 ASNCLP Program Reference for Replication and Event Publishing

# specifies the SET00 set, AQ00 Apply qualifier, and STAFF source table. The # TRGSTAFF target table is specified as a user copy with all columns registered. SET PROFILE TBSPROFILE FOR OBJECT TARGET TABLESPACE OPTIONS UW USING FILE "c:\tstrg.ts" SIZE 700 PAGES; CREATE MEMBER IN SETNAME SET00 APPLYQUAL AQ00 ACTIVATE YES SOURCE PROJECT TARGET NAME TRGPROJECT DEFINITION IN TSTRG00 CREATE USING PROFILE TBSPROFILE TYPE USERCOPY COLS ALL REGISTERED; # 3 Ending the ASNCLP session. QUIT; Output of the scripts In addition to the log files, this sample produces six SQL script files in the same directory where you run the ASNCLP program. Table 2 describes the files. Table 2. SQL script files that are created by the sample ASNCLP scripts Output file Contains SQL to... capctrl.sql Create Capture control tables register.sql Register a source table appctrl.sql Create Apply control tables ctlsubset.sql Insert definitions for a subscription set into the Apply control tables capmember.sql Insert definitions for a subscription-set member into the Capture control tables appmember.sql Insert definitions for a subscription-set member into the Apply control tables projtrg.sql Create a target table and table space ALTER MEMBER ADD COLS command Use the ALTER MEMBER ADD COLS command to add columns to an existing member in an existing subscription set. ALTER MEMBER ADD COLS IN SETNAME setname APPLYQUAL applyqual SOURCE objowner. objname TARGET objowner. objname COLS ( EXPRESSION source-col-or-expr ) TARGET name + Parameters SETNAME setname Specifies the subscription-set name. APPLYQUAL applyqual Specifies the Apply qualifier for the subscription set. Chapter 2. ASNCLP commands for SQL replication 11

SOURCE objowner.objname Specifies the source object s owner and name. TARGET objowner.objname Specifies the target object s owner and name. COLS Specifies the columns to add. You can specify multiple columns by using commas and parentheses. EXPRESSION source-col-or-expr Specifies an expression for the column. The double quotation marks are required. TARGET name Specifies the target s column name. + Specifies that the column is part of the primary key. Usage notes v v For update-anywhere subscription sets, the columns are added to the members for both replication directions (master-to-replica and replica-to-master). The Capture schema for the target table is inherited from the subscription set. Example To add column NEWSTAFF to the existing subscription set SET00 : ALTER MEMBER ADD COLS IN SETNAME SET00 APPLYQUAL AQ00 SOURCE DB2ADMIN.STAFF TARGET DB2ADMIN.TRGSTAFF COLS (EXPRESSION "source-col-or-expr" TARGET NEWSTAFF) ALTER REGISTRATION command Use the ALTER REGISTRATION command to alter a registration row in the IBMSNAP_REGISTER table and to add new columns to a registered source. ALTER REGISTRATION ROW row-clause ADD add-cols-clause row-clause:, ( objname ) objowner. CONFLICT NONE STANDARD ENHANCED UPDATE AS DELETE INSERT OFF ON CAPTURE ALL CHANGES FORWARDING OFF ON 12 ASNCLP Program Reference for Replication and Event Publishing

FULL REFRESH ON OFF STOP ON ERROR ON OFF add-cols-clause: objowner. objname, COLS ( colname ) IMAGE AFTER BOTH BEFORE PREFIX X befimgpref Parameters ROW Specify to alter a registration row in the IBMSNAP_REGISTER table. ADD Specify to add new columns from a source object to a registration. This parameter only applies if the source object is a table or nickname. objowner Specifies the owner of the registered source object (table, view, or nickname). You can specify multiple objects. objname Specifies the name of the registered source object (table, view, or nickname). You can specify multiple objects. CONFLICT Specifies the conflict-detection level. NONE No conflict detection. Conflicting updates between the master table and the replica table will not be detected. This option is not recommended for update-anywhere replication. This is the default. STANDARD Moderate conflict detection. During each Apply cycle, the Apply program compares the key values in the master s CD table with those in the replica s CD table. If the same key value exists in both CD tables, it is a conflict. In the case of a conflict, the Apply program will undo the transaction that was previously committed at the replica by reading from the replica s CD table and keeping only the changes that originated at the master. ENHANCED Conflict detection that provides the best data integrity among the master and its replicas. As with standard detection, the Apply program compares the key values in the master s CD table with those in the replica s CD table during each Apply cycle. If the same key value exists in both CD tables, it Chapter 2. ASNCLP commands for SQL replication 13

is a conflict. However, with enhanced detection, the Apply program waits for all in-flight transactions to commit before checking for conflicts. To ensure that it catches all in-flight transactions, the Apply program locks all target tables in the subscription set against further transactions and begins conflict detection after all changes are captured in the CD table. In case of a conflict, the Apply program will undo the transaction that was previously committed at the replica by reading from the replica s CD table and keeping only the changes that originated at the master. UPDATE AS DELETE INSERT ON Specify to capture updates as delete-insert pairs. OFF Specify to capture updates as updates. This is the default. CAPTURE ALL Specify to capture everything. CHANGES Specify to capture only changes. FORWARDING OFF Specify not to forward changes from this source. ON Specify to forward changes from this source. FULL REFRESH ON Specify to allow full refreshes for this source. OFF Specify to not allow full refreshes for this source. STOP ON ERROR ON Specify to stop the Capture program if it detects an error for this registration. OFF Specify to not stop the Capture program if it detects an error for this registration. COLS Specifies the columns that you want to register. colname Specifies a list of the columns that you want to register. IMAGE AFTER Specify to register only after-image columns. BOTH Specify to register both after-image and before-image columns. 14 ASNCLP Program Reference for Replication and Event Publishing

BEFORE Specify to register only before-image columns. PREFIX v v If you specify IMAGE AFTER, the prefix will be null and the source will not allow any before-image columns. If you specify IMAGE BOTH or IMAGE BEFORE and do not specify PREFIX, a default value of X is used as a prefix for the before images. If you specify PREFIX, that value is used. v If you choose IMAGE BOTH and do not specify a prefix, the before-imaged prefix will be X. You cannot alter an existing before-image prefix by using the ALTER REGISTRATION ROW command. However, you can add that prefix to a new before-image column. If the existing before-image prefix is null and you want to add a before-image column to the existing registration, you can specify the before-image prefix by using the ALTER REGISTRATION ADD command. If you do not specify the prefix, the ASNCLP program sets it to a default value of X. Usage notes The parameters in this command do not have default values. If you add a column to a CD table when the registered source also has an internal CCD table associated with it, you must: v v Use the ALTER ADD REGISTRATION COL command to add a column to the CD table Use the ALTER ADD SUBSCRIPTION MEMBER COL command to add a column to the internal CCD table. If you do not do this step, you will not be able to add the column to any target table that is dependent on the registered source. Example 1 To alter a registration row for DB2ADMIN.STAFF that captures updates as delete-insert pairs: ALTER REGISTRATION ROW (DB2ADMIN.STAFF) UPDATE AS DELETE INSERT ON Example 2 To alter a registration by adding a new column C002 to table DB2ADMIN.STAFF: ALTER REGISTRATION ADD DB2ADMIN.STAFF COLS (C002 IMAGE BOTH) ALTER SUBSCRIPTION SET command Use the ALTER SUBSCRIPTION SET command to alter certain values for a subscription set. ALTER SUBSCRIPTION SET SETNAME setname APPLYQUAL applyqual SETTYPE R U P F ONLY S ONLY Chapter 2. ASNCLP commands for SQL replication 15

ACTIVATE NO YES ONCE TIMING EVENT eventname INTERVAL minutes BOTH EVENT eventname INTERVAL minutes CONTINUOUS BLOCKING minutes COMMIT COUNT n NULL Parameters SETNAME setname Specifies the subscription-set name. APPLYQUAL applyqual Specifies the Apply qualifier for the subscription set. SETTYPE Specifies the subscription set type. R Specifies a read-only set. This is the default. U Specifies an update-anywhere set. The default is both F and S directions. F ONLY Specifies an update-anywhere set in the F direction only, where the source table is the replica and the target table is the master. S ONLY Specifies an update-anywhere set in the S direction only, where the source table is the mast table or the other source, and the target table is the replica or other copy. P Specifies a peer-to-peer set. ACTIVATE Specifies whether to activate the subscription set. NO Specify to not activate the subscription set. This is the default. YES Specify to activate the subscription set. ONCE Specify to activate the subscription set for one Apply cycle, then deactivate the subscription set. TIMING Specifies the timing for the subscription set. EVENT eventname Specifies the event that when posted to the IBMSNAP_SUBS_EVENT table, causes the Apply program to process the subscription set. INTERVAL minutes Specifies the interval for the Apply program to process the subscription set. The default interval is 20 minutes. BOTH Specifies that this subscription set uses both event and interval timing. 16 ASNCLP Program Reference for Replication and Event Publishing

CONTINUOUS Specifies that the Apply program should process the subscription set continuously. This keyword is equivalent to specifying an interval of zero minutes. BLOCKING minutes Specifies a threshold limit to regulate the amount of data to fetch and apply. This keyword controls the MAX_SYNCH_MINUTES column of the IBMSNAP_SUB_SET table. COMMIT COUNT n Specifies the number of transactions that the Apply program should process before issuing a SQL COMMIT statement for the subscription set. Specify a NULL value to have the Apply program issue just one COMMIT statement for the subscription set after it processes the entire set. Example 1 To alter the SET00 subscription set within the AQ00 Apply qualifier to a read-only subscription set type and to change the timing interval from 20 minutes to 15 minutes: ALTER SUBSCRIPTION SET SETNAME SET00 APPLYQUAL AQ00 SETTYPE R ACTIVATE YES TIMING INTERVAL 15 COMMIT COUNT NULL Example 2 To alter the SET00 subscription set so that it activates once and sets the source table as the replica and the target table as the master: ALTER SUBSCRIPTION SET SETNAME SET00 APPLYQUAL AQ00 SETTYPE U F ONLY ACTIVATE ONCE COMMIT COUNT 5 ASNCLP SESSION SET TO command (SQL replication) Use the ASNCLP SESSION SET TO command to define an ASNCLP session for SQL replication. ASNCLP SESSION SET TO SQL REPLICATION Parameters SQL REPLICATION Specify to set the ASNCLP session to SQL replication. This ASNCLP session only accepts SQL replication syntax. Usage notes Issue the ASNCLP SESSION SET command before all other commands in an ASNCLP session. If you do not issue the ASNCLP SESSION SET command, the ASNCLP program defaults to SQL replication. Example To set the ASNCLP session to SQL replication: ASNCLP SESSION SET TO SQL REPLICATION Chapter 2. ASNCLP commands for SQL replication 17

CREATE CONTROL TABLES FOR command (SQL replication) Use the CREATE CONTROL TABLES FOR command to create a new set of Capture, Apply, or Replication Alert Monitor control tables. CREATE CONTROL TABLES FOR CAPTURE SERVER APPLY CONTROL SERVER MONITOR CONTROL SERVER IN ZOS zos-ts-clause UW uw-ts-clause NONIBM federated-clause zos-ts-clause: UOW DB dbname tsname prof-clause NAMING PREFIX prefix ALERTS DB dbname tsname prof-clause NAMING PREFIX prefix PAGE LOCK DB dbname tsname prof-clause NAMING PREFIX prefix ROW LOCK DB dbname tsname prof-clause NAMING PREFIX prefix uw-ts-clause: UOW tsname prof-clause NAMING PREFIX prefix OTHERS tsname prof-clause NAMING PREFIX prefix federated-clause: OTHERS tsname prof-clause NAMING PREFIX prefix SCHEMA schemaname prof-clause: CREATE USING PROFILE REUSE pname 18 ASNCLP Program Reference for Replication and Event Publishing

Parameters CAPTURE SERVER Specify to create replication control tables for the Capture server. APPLY CONTROL SERVER Specify to create replication control tables for the Apply control server. MONITOR CONTROL SERVER Specify to create replication control tables for the Monitor control server. IN Specifies the table space. If you do not specify the IN clause, the CREATE CONTROL TABLES command uses the DB2 defaults for table spaces. ZOS Specifies z/os or OS/390. UW Specifies Linux, UNIX, or Windows. NONIBM Specifies federated data source such as Oracle or Informix. Federated-clause OTHERS Specifies the table space for all replication control tables whenever the tables are created in a non-db2 database. You specify a table space name or a segment name for only those remote sources that support them. SCHEMA Specifies the remote schema name for a federated replication source server. The default is the remote user ID. If the schema is in lower or mixed case on the federated data source, you must use double quotation marks around the string to ensure that it is not converted to uppercase. Lower case names and quotation marks are recommended for Informix sources. UOW Specifies the table space for the unit-of-work (UOW) table. ALERTS Specifies an existing database on z/os to create the control tables in. This keyword is valid only when creating monitor control servers. PAGE LOCK Specifies the table space for replication control tables that require page-level locking. The table must be in an existing database. ROW LOCK Specifies the table space for replication control tables that require row-level locking. The table must be in an existing database. DB dbname Specifies the name of an existing database. You must specify the database name, even if you set the database name in the profile. OTHERS Specifies the table space for all replication control tables except the UOW table. tsname Specifies the table space name for the monitor alerts table. The tsname input can be a heterogeneous segment or table space name. Chapter 2. ASNCLP commands for SQL replication 19

NAMING PREFIX prefix Specifies a naming prefix for the control tables. CREATE USING PROFILE pname Specify to create the control tables and use the pname profile. If you specify the CREATE USING PROFILE parameter, the ASNCLP program uses tsname as the key (for z/os, the key is dbname.tsname). REUSE Specify to reuse the current table space or index. You must issue the CREATE USING PROFILE parameter before you can use the REUSE parameter. When you specify the REUSE parameter, the ASNCLP program checks if the table space or index exists for the tsname: v v If the table space or index exists, the ASNCLP program resets the flags and passes the fully populated object. If the table space or index does not exist, the ASNCLP program displays a syntax error saying that the CREATE USING PROFILE parameter is expected. Example 1 To create the Capture control tables and to name the UOW table space TSUOW100 and all other table spaces TSASN100: CREATE CONTROL TABLES FOR CAPTURE SERVER IN UW UOW TSUOW100 OTHERS TSASN100 Example 2 CREATE MEMBER command To create the Apply control tables and to name all table spaces except the UOW table space TSASN100: CREATE CONTROL TABLES FOR APPLY CONTROL SERVER IN UW OTHERS TSASN100 Use the CREATE MEMBER command to add a subscription-set member to an existing subscription set. Adding a member to a set includes: v Creating the mapping between the source and target tables (database objects). v Creating the mapping between the source and target columns. v Creating the target table (database object), if it doesn t already exist. v Creating the target index, if necessary. v Setting the KEYS value for the index. CREATE MEMBER IN SETNAME setname APPLYQUAL applyq ACTIVATE NO YES ONCE SOURCE objowner. objname target-clause TGT KEY CHANGE OFF ON 20 ASNCLP Program Reference for Replication and Event Publishing

WHERE sql-where-stmts COLS ALL REGISTERED, INCLUDE ( EXPRESSION expr ) TARGET name, EXCLUDE ( colname ), loadx-clause KEYS ( keyname + ) target-clause: TARGET NAME name federated-clause owner. DEFINITION trg-def-clause federated-clause: REMOTE SCHEMA owner REMOTE TABLE name trg-def-clause: IN tsname prof-clause DB name NAMING PREFIX prefix TYPE PIT USERCOPY BASEAGGREGATE CHANGEAGGREGATE REPLICA replica-clause CCD ccd-clause EXTERNAL INTERNAL prof-clause: CREATE USING PROFILE REUSE pname Chapter 2. ASNCLP commands for SQL replication 21

replica-clause: CD cdowner. cdname IN tsname prof-clause DB NAME NAMING PREFIX prefix UPDATE AS DELETE INSERT OFF ON FORWARDING OFF ON FULL REFRESH ON OFF STOP ON ERROR ON OFF ccd-clause: join-options no-join-options join-options: JOIN CD UOW AS SOURCE COMPLETE WITH UOW COLS ON OFF ALL cols-clause CONDENSED ON OFF cols-clause:, ( colname ) no-join-options: NO JOIN CD UOW AS SOURCE COMPLETE ON OFF CONDENSED ON OFF loadx-clause: LOADX TYPE NO ASNLOAD USER DEFINED CROSSLOADER LOAD SRC NICKNAME owner.tablename LOAD EXPORT IMPORT EXPORT Parameters SETNAME setname Specifies the subscription-set name. 22 ASNCLP Program Reference for Replication and Event Publishing

APPLYQUAL applyqual Specifies the Apply qualifier for the subscription set. ACTIVATE Specifies whether to activate the subscription set. NO Specify to not activate the subscription set. This is the default. YES Specify to activate the subscription set. ONCE Specify to activate the subscription set for one Apply cycle, then deactivate the subscription set. SOURCE objowner.objname Specifies the source object name and owner. TGT KEY CHANGE Specifies whether the target key can change. OFF Specifies that the key value cannot change. This is the default. ON Specifies that the key value can change. WHERE sql-where-stmts Specifies the WHERE clause that will be evaluated for this member. The double quotation marks are required. COLS Specifies the columns to include in the target table. ALL REGISTERED Specify to include all registered columns. INCLUDE Specifies the columns to include. EXPRESSION column_or_expression The EXPRESSION keyword must precede the name of any source column that you want to include in the target table, or any SQL expression that you use to transform data between the source and target. Surround column names or expressions with double quotation marks ( ). Separate multiple columns or expressions by using commas. The following example specifies that you want to include columns C1 and C2 from the source table: COLS INCLUDE (EXPRESSION "C1", EXPRESSION "C2") TARGET column_name You must use the TARGET keyword in the following cases: v An expression is specified in the COLS INCLUDE statement. The TARGET keyword specifies the column or columns in the target table to which you want the results of the expression applied. v The target table already exists, a regular source column name is used in the COLS INCLUDE statement, and the target column name is different from the source column name. The following example specifies that you want to include two columns and an expression from the source table: column C1, column C2 mapped to a column named TGTC2 at the target, and an expression Chapter 2. ASNCLP commands for SQL replication 23

that concatenates the values in columns C3 and C4 from the source table and applies the new value into the column C3C4 at the target: COLS INCLUDE (EXPRESSION "C1", EXPRESSION "C2" TARGET "TGTC2", EXPRESSION "C3 C4" TARGET "C3C4") EXCLUDE (column_name) Specify to exclude one or more source columns from the target table definition. You can only use this keyword when you are creating a new target table, or for an existing target table when the source and target tables have the same column names. KEYS keyname Specifies the key names. Include a plus sign (+) for ascending keys and a minus sign (-) for descending keys. target-clause: TARGET Specifies the target object. NAME owner.name Specifies the target object owner and name. DEFINITION Specifies the database, table space, and target-table type. federated-clause REMOTE SCHEMA owner Specifies the schema of a new target table that is created by the ASNCLP. If this keyword is not used, the default schema is the remote authorization ID for the non-db2 target database. REMOTE TABLE name Specifies the name of a new target table that is created by the ASNCLP. If this keyword is not used, the default table name is the name of the corresponding nickname in the federated database. trg-def-clause: IN Specifies the table space for the target table. If you do not specify the IN clause, the command uses the DB2 defaults for table spaces. DB name Specifies the name of the database that contains the target table and its table space. You must specify the database name, even if you set the database name in the profile. tsname Specifies the name of the table space. For z/os, the name includes the database name (for example, dbname.tsname ). This command does not create the database. You can specify a heterogeneous segment or table space name, but it must already exist. NAMING PREFIX prefix Specifies a naming prefix to use to create the table space. TYPE Specifies the type of target table. PIT Specifies a point-in-time table. 24 ASNCLP Program Reference for Replication and Event Publishing