action.skip

Replicating a Database

This chapter discusses the replication process, which involves two processes: performing the initial clone and then tracking updates to the database.


Start Databridge Twin

Use the following procedure to start Databridge Twin.

To start Databridge Twin

  • Use the following command:

    START WFL/DATABRIDGE/TWIN ("secondarydatabasename" [ , ["logicaldatabasename" ] , "taskstring" ])

    Where Is
    secondarydatabasename The title of the secondary DMSII database DESCRIPTION file without the “DESCRIPTION” node.
    logicaldatabasename The name of the DMSII logical database you are replicating. If you are not replicating a logical database, omit this parameter but include the comma.
    taskstring One of the following commands:
    • STATUS - Prints a report of current audit locations as indicated by the DBTWINCONTROL or restart data set
    • LOAD dumplist – loads the secondary database using dumps from the primary database
    • CLONE – loads the secondary database by reading each record in the primary database
    • LOCATION afn, absn, seg, inx – stores the specified audit location in the secondary database as the starting point for tracking when the secondary database has been loaded using means other than the LOAD or CLONE command
    • UPDATE

When you run Databridge Twin with the UPDATE command, it runs continuously until it is interrupted by a STOP command or a MAXWAIT timeout or it encounters an unhandled DMSII exception.


Choose a Cloning Method

Databridge Twin provides three ways to perform an initial clone. After you determine the appropriate method for your site, proceed to the procedure for that method.

Before you can clone, you must have completed installation and configuration on the primary and secondary systems.

Use this method To
CLONE command Clone the primary database, record by record. This method is similar to how the Databridge Client clones. Choose this method if you have a filter that excludes records from the secondary database.
LOAD command Dump the primary database and then load it to the secondary database. Choose this method if you do not have a filter and want the fastest clone time for a large database.
LOCATION command Populate the secondary database with user-written programs. Choose this method if the CLONE and LOAD methods are unsuitable for some reason.

The LOCATION command gives Databridge Twin the audit location in the primary database so that Databridge Twin can run in its normal tracking mode.

Keep in mind that the amount of time required to populate the secondary database depends on several factors, including the size of the DMSII database you are replicating and the type of mainframes you are using.


Clone Using the CLONE Command

Use this procedure to perform the initial clone using the CLONE command.

If you previously cloned the primary database using a method other than the Databridge Twin CLONE or LOAD commands, skip this procedure and run Databridge Twin with the LOCATION command.

To clone

  1. On the secondary system, sign on to the usercode where the Twin software was installed.

  2. Start Databridge Twin by entering the following:

    START WFL/DATABRIDGE/TWIN ("secondarydatabasename","logicaldatabasename", "CLONE")

    Parameter Description
    secondarydatabasename Name of the DMSII database on the secondary computer. If you also specify a usercode, make sure it is the usercode of the secondary database DESCRIPTION file.
    logicaldatabasename Optional. Name of the DMSII logical database. This is the logical database you want to clone into the secondary database. If you are not using a logical database, just put a second comma after the first parameter.
    CLONE Required literal.

    Databridge Twin resets any family name overrides found in the database CONTROL file and updates the database CONTROL file. Then it requests a clone of the datasets via Databridge Server and Databridge Engine on the primary system, which sends the requested records.

    Note

    If the Databridge Twin clone fails for any reason, remove all of the secondary database files, including the database CONTROL file and the audit files, and go back to step 2. (You can leave the DESCRIPTION, DASDL, DMSUPPORT, and RECONSTRUCT files.)

    When the clone is complete, Databridge Twin prints a status report with a title such as:

    (DB70)DBBD/RUN/TWIN/BANKDB/0002241/0002242/000000000000/STATUS

The following is a sample report for a database called TESTDB:

DBTwin Version 6.6.0.001 compiled Wednesday, April 19, 2017 @ 05:12:28

Source TESTDBTWIN at
    MARS port 7000
    172.27.172.91 port 7000

Filter DBFILTER in OBJECT/DATABRIDGE/SUPPORT
Retry audit every 6 seconds for at most 10 seconds
Database timeout 60 seconds
Other update programs not allowed

DBTwin Status Report for TESTDB as of Thursday, December 3, 2015 @ 17:33:42

Str#   Name          Mode     AFN     ABSN   Segment  Index   Host
----   --------      ------   ---     ----   ------   ----    ----
       (common)      clone
  4    MASTERDS      clone
  8    D             normal   6       68      1       10       BB4
 10    COUNTRIES     normal   6       68      1       10       BB6
 16    BACKORDS      normal   6       68      1       10       BB5
 18    EMPLOYEE      normal   6       68      1       10       BB8
 20    CUSTOMER      normal   6       68      1       10       BB4
 22    ORDDTAIL      normal   6       68      1       10       BB5
 24    PRODUCTS      normal   6       68      1       10       BB8
 26    SUPPLIER      normal   6       68      1       10       BB4
 28    ORDERS        normal   6       68      1       10       BB5
 30    JUAN          normal   6       68      1       10       BB6
 32    DIR           normal   6       68      1       10       BB5
 34    CANDO         clone

Updates Create:0 Modify:0 Delete:0
Errors Create:0 Modify:0 Delete:0

Datasets that have a different audit location or a mode other than normal will be printed on a separate line in the report.

Databridge Twin then switches to the UPDATE command and stays in the mix, replicating any additional updates that occurred on the primary database during and after the clone. The secondary database (named the same as the primary database) is now available for queries. Databridge Twin runs continuously until interrupted (for example, by a STOP command, MAXWAIT parameter setting, or unhandled DMSII exception).


Clone Using the LOAD Command

Use the LOAD command with a dump file as an alternative to cloning using the CLONE command. This method is performed in two separate procedures. The first procedure occurs on the primary system; the second occurs on the secondary system.

Note

This method bypasses any filters you specified in the Databridge Twin parameter file. In other words, once the dump file has been loaded, the secondary database will have all of the records that were dumped from the primary database, not just those that satisfy the filter.

Start the Clone on the Primary System

Use this procedure first when performing an initial clone using a LOAD of a dump file. Complete the process by following the instructions in Finish the Clone on the Secondary System.

To start the initial clone

  1. Dump the primary database to tape or to disk:

    To Do this
    Dump to tape Dump the entire database to tape using the following CANDE command:

    RUN $SYSTEM/DMUTILITY ("DB=databasename DUMP = TO dumpname")

    -or-

    Clone a logical database by dumping (at least) the data sets and sets that belong to the logical database. For example, if the logical database contains data sets D1 and D2 in a physical database called MYDB, you would use the following CANDE command:

    RUN $SYSTEM/DMUTILITY ("DB=MYDB DUMP MYDB/D1/=,MYDB/D2/= TO MYDBDUMP")
    Dump to disk Dump the entire database to a disk file under the primary database usercode by entering:

    RUN $SYSTEM/DMUTILITY("DB=databasename DUMP = TO dumpname ON packname")

    -or-

    Dump selected data sets to the primary database usercode by entering:

    RUN $SYSTEM/DMUTILITY ("DB=databasename DUMP datasetdirectories TO dumpname ON packname")

    Then, change the security of the dump file on the disk to PUBLIC IN so that the secondary usercode can read it, as in the following example:

    SEC dumpname ON packname PUBLIC IN

  2. You can now use the primary database as normal.

    Note

    Run at least one program that does a database OPEN UPDATE before proceeding.

  3. Preserve the audit files covering the period from the start of the dump to the end of the dump for use on the secondary system.

  4. If you wrote the dump to tape, move the tape(s) to the secondary system. If you wrote the dump to disk instead of tape, use BNA or whatever is appropriate at your site to copy the dump to the secondary system.

    At this point, you have the primary database dump (on tape or disk). Now you are ready to start the cloning process on the secondary system, as described in the next section.

Finish the Clone on the Secondary System

Use this procedure to complete the initial cloning process started in Start the Clone on the Primary System. In this procedure, you'll create the cloned database using the LOAD command.

To complete the initial clone

  1. Do one of the following:

    • If you dumped the primary database to tape, mount the tape on the secondary system.
    • If you dumped the primary database to disk, make sure that you copy the dump file(s) to the secondary system.

  2. Sign on to the usercode containing the Databridge Twin software and enter the following to start Databridge Twin:

    START WFL/DATABRIDGE/TWIN

    (" secondarydatabasename "," logicaldatabasename ", "LOAD dumpname [ON familyname ]")

    Where Is
    secondarydatabasename The name of the DMSII database on the secondary system.

    Note: If you specify a usercode, make sure it is the usercode of the secondary database DESCRIPTION file.
    logicaldatabasename The name of the DMSII logical database you want to clone on the secondary system. If you are not using a logical database, omit this parameter but include the comma as shown in the following example:

    ("secondarydatabasename",, "LOAD dumpname")
    dumpname

    –or–

    dumpname,

    dumpname, ...    		 The name of the dump(s) from the primary database. If you used the example in Start the Clone on the Primary System, the dump name is MYDBDUMP.

    You can also specify a comma-delimited list of tape dump names for the dump parameter. This allows partial dumps to be combined into a complete secondary database. The following is an example of a comma-delimited list of tape dumps:

    START WFL/DATABRIDGE/TWIN("BANKDB",,"LOAD MONDAYDUMP, THURSDAYDUMP, CUSTDUMP")

    The default is tape dumps. If you dumped to disk, be certain to include ON familyname in the dump name.
    LOAD A required literal that initializes the secondary database and loads the structures from the dumps taken on the primary system.

    Databridge Twin resets any family name overrides in the database CONTROL file, updates the database CONTROL file, and then initiates DMUTILITY to load the dump. In addition, Databridge Twin will request one or more audit files by displaying a NO FILE message on the terminal and ODT. The messages look similar to the following:

    NO FILE databasename /AUDIT nnnn (MT) #1

  3. Copy the requested audit file from the primary system to the secondary system and usercode.

    If you use sectioned audit files, be sure to copy all of the sections. Then give the waiting task an FA command:

    mixnumber FA TITLE = databasename/ AUDIT nnnn ON family

  4. Watch for additional requests for audit files and repeat the previous step if necessary.

    If the requested audit file is in use on the primary system because it is the current audit file, either wait for DMSII to switch to the next audit file or force a switch immediately. To force an audit file switch, find the mix number of the database by entering the DBS command from the ODT or MARC, and then enter mixnumber SM AUDIT CLOSE FORCE.

    Note

    If Databridge Twin fails for any reason, remove all of the secondary database files, including the database CONTROL file and the audit files. (Leave the DESCRIPTION, DASDL, DMSUPPORT, and RECONSTRUCT files.) Then, go back to step 2.

    After the load, Databridge Twin prints a status report. See Twin Status Report for more information.

    Then, Databridge Twin stays in the mix (automatically switching to the UPDATE command), replicating any additional updates that occurred on the primary database since the end of the dump. The secondary database (named the same as the primary database) is now available for queries. Databridge Twin runs continuously until interrupted (for example, by a STOP command, MAXWAIT parameter setting, or unhandled DMSII exception). For information on manually starting Databridge Twin, see Tracking for more information.

Clone Using the LOCATION Command

If you cloned the primary database using a method other than the Databridge Twin LOAD and CLONE commands, you must specify the audit file location. The LOCATION command provides the audit location in the cloned database so that Databridge Twin can run in its normal tracking mode.

To specify the audit file location

  • Run Databridge Twin with the LOCATION command, as follows:

    START WFL/DATABRIDGE/TWIN ("secondarydatabasename" [, "logicaldatabasename"], "LOCATION afn absn seg inx"])

    Databridge Twin stores this audit location in the secondary database as the starting point for tracking. Databridge does not validate the specified audit location until the next time Databridge Twin is run in tracking mode.

    Databridge Twin prints a STATUS report after storing the new location.

    Note

    Incorrect use of the LOCATION command can cause the client database to miss the updates that would have occurred before the specified audit location.

When you're done, use the primary database as you usually would, using the secondary database only for queries.


Tracking

After you have performed the initial clone, Databridge Twin automatically retrieves changes from the audit files and applies them to the replicated database.

If you have set the STOP command to stop Databridge Twin, or if you have set the MAXWAIT parameter to something other than 0, Databridge Twin will stop when the STOP or MAXWAIT conditions are met. In this case, you must restart Databridge Twin using the following command:

START WFL/DATABRIDGE/TWIN ("secondarydatabasename"[ , "logicaldatabasename" ] )

If you find that data in the secondary database is not current enough, you can also set the Read Active Audit option to true in the Databridge Engine parameter file on the primary system for near real-time access to the audit trail. Alternatively, you might consider adjusting the number of times audit files close on the primary database. You can accomplish this via the DBAuditTimer utility, which is described in the Databridge Host Administrator’s Guide.

Caution

Programs that update the same records in the secondary database as Databridge Twin can cause Databridge Twin to encounter various DMSII errors such as NOTFOUND or DUPLICATES. To prevent these problems, consider using guardfiles, which are explained in the Unisys mainframe documentation. Some update programs, such as LINC-generated report programs, can generally coexist with Databridge Twin because they don't actually update the same records as Databridge Twin.


Twin Status Report

Databridge Twin writes a report each time it runs showing various parameter values and the current audit location. The internal name of the report is REPORT. By default, it is a printer file whose external name is STATUS. The title of the report is (secondaryusercode)DBBD/RUN/TWIN/databasename/jobnumber/tasknumber/000000000000/STATUS

If a dataset has a mode other than normal or a different audit location from the others, it will be printed on a separate line in the report.

Here is a sample report:

DBTwin Version 6.6.0.001 compiled Tuesday, April 19, 2017 @ 05:12:28

Source TESTDBTWIN at
   MARS port 7000
   172.27.172.91 port 7000

Filter DBFILTER in OBJECT/DATABRIDGE/SUPPORT
Retry audit every 6 seconds for at most 10 seconds
Database timeout 60 seconds
Other update programs not allowed

DBTwin Status Report for TESTDB as of Thursday, December 3, 2015 @ 17:33:42

Str#  Name               Mode    AFN     ABSN   Segment    Index   Host  info
----  -----------------------   ------   ----   ---------- ------- ----- --------
----
      (common)           clone
  4   MASTERDS           clone
  8   D                 normal    6      68       1         10       BB4
 10   COUNTRIES         normal    6      68       1         10       BB6
 16   BACKORDS          normal    6      68       1         10       BB5
 18   EMPLOYEE          normal    6      68       1         10       BB8
 20   CUSTOMER          normal    6      68       1         10       BB4
 22   ORDDTAIL          normal    6      68       1         10       BB5
 24   PRODUCTS          normal    6      68       1         10       BB8
 26   SUPPLIER          normal    6      68       1         10       BB4
 28   ORDERS            normal    6      68       1         10       BB5
 30   JUAN              normal    6      68       1         10       BB6
 32   DIR               normal    6      68       1         10       BB5
 34   CANDO              clone

Updates Create:0 Modify:0 Delete:0
Errors Create:0 Modify:0 Delete:0


Audit File Numbers Won't Match

In most cases, the audit file numbers on the secondary system will not match those on the primary system after tracking begins. Even though both databases start with the same audit file number, the secondary database may close its audit files more or less frequently than the primary database. Remember that the only program updating the secondary database should be Databridge Twin. All other secondary database activity should be from queries only.