IBM Books

Untitled


Table of Contents

Capture and Apply for Windows and OS/2

  • User ID requirements for running the Capture and Apply programs
  • Setting up the Capture and Apply programs
  • Configuring Capture for Windows and OS/2
  • Configuring Apply for Windows and OS/2
  • Providing end-user authentication at the source server
  • Setting up the NT Service Control Manager
  • Operating Capture for Windows and Capture for OS/2
  • Restrictions for running the Capture program
  • Starting Capture for Windows and OS/2
  • Scheduling Capture for Windows and OS/2
  • Stopping Capture for Windows and OS/2
  • Suspending Capture for Windows and OS/2
  • Resuming Capture for Windows and OS/2
  • Reinitializing Capture for Windows and OS/2
  • Pruning the change data and unit-of-work tables
  • Displaying captured log progress
  • Operating Apply for Windows and OS/2
  • Before you start the Apply program
  • Starting Apply for Windows and OS/2
  • Scheduling Apply for Windows and OS/2
  • Stopping Apply for Windows and OS/2

  • Capture and Apply for Windows and OS/2

    This chapter describes how to set up and operate the Capture and the Apply programs on the following platforms:

    Be sure to read the following sections before reading the sections on operating the Capture and Apply programs:


    User ID requirements for running the Capture and Apply programs

    The user ID under which the Capture and Apply programs will run must have the following privileges:


    Setting up the Capture and Apply programs

    Setting up consists of configuring the source, target, and control servers, and setting up NT services on Windows. The following sections provide instructions for configuring each server, providing end-user authentication at the source server, and setting up the NT Service Control Manager.

    Configuring Capture for Windows and OS/2

    Important: The Capture program is bound automatically during execution. Therefore, the following steps for binding the Capture program on Windows and OS/2 are optional. If you want to specify options or check that all bind processes completed successfully, complete the following tasks:

    1. Log on with the user ID that has sufficient privileges.

    2. Connect to the source server database by entering:
      DB2 CONNECT TO database
      

      where database is the source server database.

    3. Prepare the source server database for roll-forward recovery by issuing the UPDATE DATABASE CONFIGURATION command and the BACKUP DATABASE command. For example:
      DB2 UPDATE DATABASE CONFIGURATION FOR database_alias USING LOGRETAIN ON
      DB2 BACKUP DATABASE database_alias
      

      or:

      DB2 UPDATE DATABASE CONFIGURATION FOR database_alias USING USEREXIT ON
      DB2 BACKUP DATABASE database_alias
      

      You might need to increase DBHEAP, APPLHEAPSZ, PCKCACHESZ, LOCKLIST, and LOGBUFSZ based on your installation requirements.

    4. Change to the directory where the Capture program bind files are located, which is usually drive:\SQLLIB\BND.

    5. Create and bind the Capture program package to the source server database by entering the following command:
      DB2 BIND @CAPTURE.LST ISOLATION UR BLOCKING ALL
      

      where UR specifies the list in uncommitted read format for greater performance.

      These commands create a list of packages, the names of which are in the file CAPTURE.LST.

    Configuring Apply for Windows and OS/2

    Important: The Apply package is bound automatically during execution. Therefore, the following steps for binding the Apply package on Windows and OS/2 are optional. If you want to specify options or check that all bind processes completed successfully, complete the following tasks:

    1. Log on with the user ID that has sufficient privileges.

    2. Change to the directory where the Apply program bind files are located, which is usually drive:\SQLLIB\BND.

    3. Connect to the source server database by entering:
      DB2 CONNECT TO database
      

      where database is the source server database.
      Note:If the source server database is catalogued as a remote database, you might need to specify a user ID and password on the DB2 CONNECT TO command. For example:
      DB2 CONNECT TO database USER userid USING password
      

    4. Create and bind the Apply program package to the source server database by entering the following commands:
      DB2 BIND @APPLYCS.LST ISOLATION CS BLOCKING ALL
      
      DB2 BIND @APPLYUR.LST ISOLATION UR BLOCKING ALL 
      

      where cs specifies the list in cursor stability format, and ur specifies the list in uncommitted read format.

      These commands create a list of packages, the names of which are in the files APPLYCS.LST and APPLYUR.LST.

    5. Connect to the target server database by entering:
      DB2 CONNECT TO database
      

      where database is the target server database.

    6. Create and bind the Apply package to the target server database by entering both of the following commands:
      DB2 BIND @APPLYCS.LST ISOLATION CS BLOCKING ALL GRANT PUBLIC
      
      DB2 BIND @APPLYUR.LST ISOLATION UR BLOCKING ALL GRANT PUBLIC
      

      Because the Apply program uses static SQL calls for the control tables, the Apply bind process searches for the control tables at each server that the Apply program is bound to, regardless of whether these control tables are used at a server.

    7. Repeat the connect and bind steps for each server that the Apply program connects to. You must bind the Apply program to all source, target, and control servers.

    Providing end-user authentication at the source server

    For end-user authentication to occur at the source server, you must provide a password file with an AUTH=SERVER scheme. The Apply program uses this file when connecting to the source server. Give read access only to the user ID that will run the Apply program.

    Creating a password file:

    The password file must meet the following criteria:

    For more information about authentication and security, refer to the IBM DB2 Universal Database Administration Guide.

    Setting up the NT Service Control Manager

    You can operate the Capture and Apply programs for Windows by using the DB2 command processor or by using the NT Service Control Manager (SCM). The SCM enables you to automatically start the Capture and Apply programs as services from the NT Control Panel.

    You must install the replication service manually (installation is not automatic). The following steps explain how to install the replication service and set it up as an NT service.
    Tip:In this section, x:\ refers to the drive and directory containing executable programs. These programs are usually located in the \sqllib\bin directory.

    To install replication and set up the NT service:

    1. Open a command window, and change to the directory containing the executable file ASNINST.EXE.

    2. Install the replication service by typing the following command:
      ASNINST x:\ASNSERV.EXE
      

    3. Set up the service from the NT Control Panel.

      1. Double-click the Services icon. The NT Services window opens.

      2. Select Replication and click STARTUP.

      3. Ensure that the startup type is automatic.

      4. Specify the local user ID and password and click OK. The user ID must be the one that runs the Capture and Apply programs and has the appropriate DB2 privileges.

    4. Add the environment variable ASNPATH to specify the location of the Capture and Apply program files.

      1. Double-click the System icon on the NT Control Panel. The System Properties window opens.

      2. Click the Environment tab.

      3. Type the ASNPATH string in the Variable field as shown in the following example:
        ASNPATH=x:\
        

      4. Click OK.

      5. You must reboot the computer after updating the value of the ASNPATH environment variable.

    5. Create an ASCII file called ntserv.asn to run the Capture and Apply programs.

      1. Enter the following records in the file:
        db_name x:\ASNCCP parameters
        
        db_name x:\ASNAPPLY parameters
        

        where db_name specifies the name of the source database for the Capture program and the name of the control database for the Apply program, x:\ is the location of the programs, and parameters specifies one or more invocation parameters (such as APPLYQUAL).

        To use the Capture program and Apply program trace facilities, specify the invocation parameters in the file. For example:

        DBNAME1 C:\SQLLIB\BIN\ASNCCP COLD TRACE<CRLF>
        DBNAME2 C:\SQLLIB\BIN\ASNAPPLY APPLYQUAL DBNAME2 TRCFLOW TRCFILE<CRLF>
        

        The TRCFILE invocation parameter is necessary, in addition to the usual trace invocation parameter (such as TRCFLOW), to generate an Apply program trace.

        Do not specify an output file name for traces. These will be written to default locations, with default file names, as follows:

        • For the Capture program:
          x:\instancenamedbname.trc
          

        • For the Apply program:
          x:\APPLYtimestamp.trc
          

      2. Save the file to the following location:
        x:\ntserv.asn
        

    The Replication Services program stores all messages in x:\asnserv.log. If you encounter any problems, check this log file for error messages.

    To stop the Capture and Apply programs:

    Important: After you start the service, the Capture and Apply programs run independently of ASNSERV. Therefore, stopping ASNSERV does not stop the Capture and Apply programs. Use the ASNCMD STOP command in a command window to stop the Capture program. Use the ASNASTOP command in a command window to stop the Apply program.

    To remove replication from the NT service:

    To remove Replication Services from the NT Control Panel, run the ASNREMV program.


    Operating Capture for Windows and Capture for OS/2

    An administrator can use the commands in this section to operate the Capture program on Windows and the Capture program on OS/2. Enter the commands or a key combination from an NT or an OS/2 window.

    This section explains how to perform the following Capture program tasks:

    This section also lists restrictions for running the Capture program.

    Restrictions for running the Capture program

    Some actions cause the Capture program to terminate while it is running. Stop the Capture program before you take any of the following actions:

    The Capture program cannot capture any changes made by DB2 utilities, because the utilities do not log changes they make.

    Starting Capture for Windows and OS/2

    After you start the Capture program, it runs continuously until you stop it or it detects an unrecoverable error.

    To start the Capture program using the NT Services:

    1. Select Replication from the NT Services window.

    2. Click the START push button. The Capture program starts according to the ASCII file information you provided.

    You can also start the replication service by typing STRTSERV on the NT command line.

    To start the Capture program using the DB2 command window:

    1. If you created one or more DB2 for NT or DB2 for OS/2 instances, use the SET command to set the DB2INSTANCE environment variable to the DB2 for NT or DB2 for OS/2 instance with which you plan to run the Capture program:
      SET DB2INSTANCE=database_instance_name
      

      While the Capture program is running, a file with the name <database_instance_name><database_name>.CCP (Windows) or database_name.CCP (OS/2) is created in the directory from which the Capture program is started. This file is a log file for the messages issued by the Capture program; these messages are also recorded in the trace table.

    2. Set environment variable DB2DBDFT to the source server specified when the Capture program was started (or the DB2DBDFT value used when the Capture program was started).

    3. To start the Capture program, enter the ASNCCP command from the Windows or OS/2 window where you issued the SET command. The syntax is:
    >>-ASNCCP----+------------+---+--------+---+---------+---------->
                 '-src_server-'   +-WARM---+   +-PRUNE---+
                                  +-WARMNS-+   '-NOPRUNE-'
                                  '-COLD---'
     
    >-----+---------+---+---------+---+----------+---+----------+--->
          +-NOTRACE-+   '-TRCFILE-'   '-NOTRCTBL-'   '-AUTOSTOP-'
          '-TRACE---'
     
    >-----+----------+---+-----------+---+---------+---------------><
          '-LOGREUSE-'   '-LOGSTDOUT-'   +-ALLCHG--+
                                         '-CHGONLY-'
     
    

    Table 1 defines the invocation parameters.

    Table 1. ASNCCP Command Invocation Parameter Definitions for Windows and OS/2 Platforms
    Parameter Definition
    src_server Source server name must be the first parameter if entered. If not specified, the value from the DB2DBDFT environment variable is used.
    WARM  (default)  The Capture program resumes processing where it ended in its previous run if warm start information is available. If the Capture program cannot warm start, it switches to a cold start.
    WARMNS The Capture program resumes processing where it ended in its previous run if warm start information is available. Otherwise, it issues a message and terminates. With warmns, the Capture program does not automatically switch to a cold start. The Capture program leaves the trace, UOW, CD, and warm start tables intact. In case of errors, the Capture program terminates instead of switching to a cold start as when warm is specified.
    COLD The Capture program starts by deleting all rows in its CD table, UOW table, and trace table during initialization. All subscriptions to these replication sources will be fully refreshed during the next Apply program processing cycle.
    PRUNE  (default)  The Capture program automatically prunes the rows in the CD and UOW tables that the Apply program has copied, at the interval specified in the tuning parameters table.
    NOPRUNE Automatic pruning is disabled. The Capture program prunes the CD and the UOW tables when you enter the PRUNE command.
    NOTRACE  (default)  No trace information is written.
    TRACE Writes trace messages to the standard output, stdout, unless TRCFILE is also specified.
    TRCFILE If both trcfile and trace are specified, the Capture program writes trace output to the trace file (*.trc). If you do not specify this option, the Capture program sends trace output to the standard output, stdout.
    NOTRCTBL The Capture program messages are not logged in the trace table.
    AUTOSTOP The Capture program terminates after it has captured all transactions logged before the Capture program was started.
    LOGREUSE The Capture program reuses the log file (*.ccp) by first deleting and then re-creating it when the Capture program is restarted. If you do not specify this option, the Capture program appends messages to the log file, even after the Capture program is restarted.
    LOGSTDOUT The Capture program sends all messages to both the standard output (stdout) and the log file.
    ALLCHG  (default)  Specifies that an entry is made to the CD table whenever a source table row changes.
    CHGONLY Specifies that an entry is made to the CD table when a source table row changes only if the columns defined for replication (CD table columns) change values.

    Scheduling Capture for Windows and OS/2

    For Windows: Use the AT command to start the Capture program at a specific time. For example, the following command string starts the Capture program for Windows at 15:00:

    c:\>AT 15:00 /interactive "c:\SQLLIB\BIN\db2cmd.exe c:\CAPTURE\asnccp.exe warmns"
    

    Before you enter the AT command, the Windows Schedule Service should already be started.

    For OS/2: Use the Alarms program in the OS/2 Productivity set to start the Capture program for OS/2 at a specific time.

    Stopping Capture for Windows and OS/2

    Use the STOP command or a key combination to stop the Capture program in an orderly way and commit the log records that it processed up to that point.

    Stop the Capture program before removing for modifying an existing replication source.

    For Windows: If you started the Capture program as an NT service, stop the Capture program by selecting Replication from the NT Services window and clicking the Stop push button. After the stop message appears, the status field becomes blank.

    For Windows and OS/2: If you started the Capture program from the DB2 command window, enter the following command:

    >>-ASNCMD--STOP------------------------------------------------><
     
    

    or

    >>-ASNCMD--src_server--STOP------------------------------------><
     
    

    To use the command, do the following from a window where the Capture program is not running:

    1. Set environment variable DB2INSTANCE to the value set when the Capture program was started.

    2. Set environment variable DB2DBDFT to the source server specified when the Capture program was started (or the DB2DBDFT value used when the Capture program was started).
      Note:You do not need to set the value of DB2DBDFT if you specify a value for src_server when you run the command.

    3. Enter the command.

    Attention: Follow the same 3 steps listed above to enter all of the Capture program commands.

    Suspending Capture for Windows and OS/2

    Use the SUSPEND command to relinquish operating system resources to operational transactions during peak periods without destroying the Capture program environment. This command suspends the Capture program until you issue the RESUME command.

    >>-ASNCMD--SUSPEND---------------------------------------------><
     
    

    or

    >>-ASNCMD--src_server--SUSPEND---------------------------------><
     
    

    Important: Do not use the SUSPEND command when canceling a replication source. Instead, stop the Capture program.

    Resuming Capture for Windows and OS/2

    Use the RESUME command to restart the Capture program if you suspended it using the SUSPEND command.

    >>-ASNCMD--RESUME----------------------------------------------><
     
    

    or

    >>-ASNCMD--src_server--RESUME----------------------------------><
     
    

    Reinitializing Capture for Windows and OS/2

    Use the REINIT command to begin to capture changes from new source tables if you add a new replication source or ALTER ADD a column to a replication source and CD table while the Capture program is running. The REINIT command tells the Capture program to obtain newly added replication sources from the register table.

    REINIT also rereads the tuning parameters table for any changes made to the tuning parameters.

    >>-ASNCMD--REINIT----------------------------------------------><
     
    

    or

    >>-ASNCMD--src_server--REINIT----------------------------------><
     
    

    Important: Do not use the REINIT command to reinitialize the Capture program after canceling a replication source or dropping a replication source table while the Capture program is running. Instead, stop the Capture program and restart it using the WARM or WARMNS option.

    Pruning the change data and unit-of-work tables

    Use the PRUNE command to start pruning the CD and UOW tables.

    This command prunes tables once.

    >>-ASNCMD--PRUNE-----------------------------------------------><
     
    

    or

    >>-ASNCMD--src_server--PRUNE-----------------------------------><
     
    

    The Capture program issues the message ASN0124I when the command is successfully queued.

    During pruning, if you stop or suspend the Capture program, pruning does not resume after you enter the RESUME command. You must enter the PRUNE command again to resume pruning.

    Displaying captured log progress

    Use the GETLSEQ command to provide the timestamp and current log sequence number. You can use this number to determine how far the Capture program has read the DB2 log.

    >>-ASNCMD--GETLSEQ---------------------------------------------><
     
    

    or

    >>-ASNCMD--src_server--GETLSEQ---------------------------------><
     
    

    Tip: The DB2 UDB Find Log Sequence Number command (DB2LFSN) enables you to identify the physical log file associated with the log sequence number. You can use this number to delete or archive log files no longer needed by the Capture program. For more information, see the IBM DB2 Universal Database Command Reference.


    Operating Apply for Windows and OS/2

    An administrator can use the commands in the following sections to perform the following Apply program tasks:

    Before you start the Apply program

    Before you start the Apply program, ensure that:

    Starting Apply for Windows and OS/2

    After you start the Apply program, it runs continuously until:

    To start the Apply program using the NT services:

    1. Select Replication from the NT Services window.

    2. Click the Start push button. The Apply program starts according to the ASCII file information you provided.

    You can also start the replication service by typing STRTSERV on the Windows NT command line.

    To start the Apply program using the DB2 command window:

    Perform the following steps from a Windows or OS/2 window:

    1. Log on with the IBM Replication user ID.

    2. Ensure that you set the DB2 instance as shown:
      SET DB2INSTANCE=db2_instance_name
      

    3. Enter the ASNAPPLY command from the Windows or OS/2 window where you issued the SET command:
    >>-ASNAPPLY--Apl_qual----+-----------+---+-----------+---------->
                             '-Ctrl_serv-'   +-LOADXit---+
                                             '-NOLOADXit-'
     
    >-----+----------+---+---------+---+---------+---+----------+--->
          +-INAMsg---+   +-NOTRC---+   '-TRCFILE-'   +-NOTIFY---+
          '-NOINAMsg-'   +-TRCERR--+                 '-NONOTIFY-'
                         '-TRCFLOW-'
     
    >-----+---------+---+----------+---+----------+---+----------+-->
          +-SLEEP---+   '-DELAY(n)-'   '-COPYONCE-'   '-LOGREUSE-'
          '-NOSLEEP-'
     
    >-----+-----------+---+----------+-----------------------------><
          '-LOGSTDOUT-'   '-TRLREUSE-'
     
    

    Table 2 defines the invocation parameters.

    Table 2. ASNAPPLY Invocation Parameter Definitions on Windows and OS/2
    Parameter Definition
    Apl_qual Specifies the Apply qualifier that the Apply program instance uses to identify the subscriptions to be served. The Apply qualifier is case sensitive and must match the value of the APPLY_QUAL in the subscription set table. This must be the first parameter.
    Ctrl_serv Specifies the name of the server where the replication control tables will reside. If you do not specify this parameter, the default is the default database or the value of DB2DBDFT.
    LOADXit Specifies that the Apply program is to invoke ASNLOAD, an IBM-supplied exit routine that uses the export and load utilities to refresh target tables.
    NOLOADXit  (default)  Specifies that the Apply program will not invoke ASNLOAD.
    INAMsg  (default)  Specifies that the Apply program is to issue a message when the Apply program is inactive.
    NOINAMsg Specifies that the Apply program will not issue this message.
    NOTRC  (default)  Specifies that the Apply program does not generate a trace.
    TRCERR Specifies that the Apply program generates a trace that contains only error information.
    TRCFLOW Specifies that the Apply program generates a trace that contains both error and execution flow information.
    TRCFILE If both trcfile and trace are specified, the Apply program writes trace output to the trace file (*.trc). If you do not specify this option, the Apply program sends trace output to the standard output, stdout.
    NOTIFY Specifies that the Apply program is to invoke ASNDONE, an exit routine that returns control to the user when the Apply program processing ends.
    NONOTIFY  (default)  Specifies that the Apply program will not invoke ASNDONE.
    SLEEP  (default)  Specifies that the Apply program is to go to sleep if no new subscriptions are eligible for processing.
    NOSLEEP Specifies that the Apply program is to stop if no new subscriptions are eligible for processing.
    DELAY(n) Where n=0, 1, 2, 3, 4, 5, or 6. Specifies the delay time (in seconds) at the end of each Apply program cycle when continuous replication is used. The default delay time is 6 seconds.
    COPYONCE The Apply program executes one copy cycle for each eligible subscription set and then terminates. An eligible subscription set is such that:

    • ACTIVATE > 0

    • REFRESH_TIMING = R or B or REFRESH_TIMING = E and the specified event has occurred.
    MAX_SYNCH_MINUTES and END_OF_PERIOD are honored if specified.
    LOGREUSE The Apply program reuses the log file (*.app) by first deleting it and then re-creating it when the Apply program is restarted. If you do not specify this option, the Apply program appends messages to the log file, even after the Apply program is restarted.
    LOGSTDOUT The Apply program sends all messages to both the standard output (stdout) and the log file.
    TRLREUSE The Apply program empties the Apply trail table when the Apply program is started.

    Scheduling Apply for Windows and OS/2

    For Windows: Use the Windows AT command to start the Apply program at a specific time. For example, the following command string starts the Apply program for Windows at 15:00.

    c:\>AT 15:00 /interactive "c:\SQLLIB\BIN\db2cmd.exe
        c:\SQLLIB\BIN\asnapply.exe qualid1 cntldb"
    

    Before you enter the AT command, the Windows Schedule Service should already be started.

    For OS/2: Use the Alarms program in the OS/2 Productivity set to start the Apply program at a specific time.

    Stopping Apply for Windows and OS/2

    Use the ASNASTOP command or a key combination to stop the Apply program in an orderly way.

    >>-ASNASTOP--Apply_qualifier-----------------------------------><
     
    

    To use the command, do the following from a window where the Apply program is not running:

    1. Set environment variable DB2INSTANCE to the value set when the Apply program was started.

    2. Set environment variable DB2DBDFT to the source server specified when the Apply program was started (or the DB2DBDFT value used when the Apply program was started).

    3. Enter the command.