Configuring Databridge Twin

Configure the Primary Database

The primary and secondary databases must have identical layouts, i.e. the data sets, sets, data items, etc. must be the same. The values in the PARAMETERS, CONTROL FILE, and AUDIT sections in the DASDL, however, can differ. In fact, if the primary and secondary databases are on the same mainframe the usercode specified in the CONTROL FILE section must be different in the two DASDLs.

If you are going to use a database dump from the primary system to load the secondary database, the pack family names need to stay the same. For example, if the data set PRODUCTS is on DBPACK in the primary database, it needs to be on DBPACK in the secondary database as well. If instead you plan to use cloning to load the secondary database, you can use different family names on the secondary system. (See Choose a Cloning Method for more information).

Databridge Twin needs to store its state information in the secondary database. It will use the restart data set for this if it has suitable data items. Otherwise, you need to add the DBTWINCONTROL data set to both the primary and secondary databases.

In order to use the restart data set for the Twin state information, it must have one of the following:

Key or non-key item at least 6 bytes long and a non-key item at least 12 bytes long
Key or non-key item at least 6 bytes long and two non-key items at least 6 bytes long each
Non-key item at least 18 bytes long

If your restart data set meets the above requirements, skip to Configure the Secondary Database.

If your restart data set does not meet the above requirements, follow this procedure:

Place PATCH/DATABRIDGE/TWIN/DASDL into the database DASDL source. The patch defines a data set called DBTWINCONTROL and is explained in DBTWINCONTROL Data Set.

Add the following line to the primary and secondary database DASDL:

$INCLUDE "PATCH/DATABRIDGE/TWIN/DASDL"
If Twin will use a logical database, make sure you enter the data set name DBTWINCONTROL in the data sets list for the logical database if you added the patch.
Follow the procedures you normally use at your site prior to performing a DASDL update, such as backing up the DESCRIPTION/databasename , DMSUPPORT/databasename , and databasename/CONTROL files.

Note

This is an update, not a reorganization. You do not have to recompile any other applications that use this database. We recommend that you first do a syntax-only compile to verify that it is a simple update and not a reorganization. The CANDE command would be: COMPILE AS $databasename WITH DASDL SYNTAX
Do the actual DASDL update compile. The CANDE command would be:

COMPILE AS $databasename WITH DASDL

This will create a new database DESCRIPTION file.
If $ ZIP is not set in your DASDL, compile the tailored DMSII software using the following command:

START DATABASE/WFL/COMPILEACR ("DB=databasename AUDIT=SET")

If $ DMCONTROL is not set in your DASDL, update the DMSII CONTROL file using the following command:

RUN SYSTEM/DMCONTROL ("DB=databasename* UPDATE")

If $ INITIALIZENEW is not set in your DASDL and you included the patch for the DBTWINCONTROL data set, initialize it using the following command after you bring down the database:

RUN $SYSTEM/DMUTILITY ("DB=databasename INITIALIZE DBTWINCONTROL")

After the initialize is complete, you can allow application programs to use the primary database as usual.

Configure the Secondary Database

Copy the DASDL source and DESCRIPTION/ databasename file from the primary system to the usercode and pack of the secondary system.
Make the following changes to the DASDL source on the secondary system. You might want to use a patch file for these changes so that they don’t have to be repeated if the primary system DASDL changes and you have to recopy it.
- Insert $ RESET DMCONTROL
- Recommended: insert $ SET ZIP
- Ensure UPDATE (rather than INITIALIZE) is specified
- Set the INDEPENDENTTRANS option
- Alter the AUDIT TRAIL settings as desired
- Update any guardfile titles as necessary
- Put the secondary system usercode in the titles for DMSUPPORT and RECONSTRUCT, and in the CONTROL FILE section
  
  CONTROL FILE ( USERCODE = secondarydatabaseusercode );
SAVE the changes to the DASDL source
Compile the secondary database. The CANDE command would be:

COMPILE AS $databasename WITH DASDL

This will create the secondary database DESCRIPTION file.

Note

This is a simple update—not a reorganization. If the DASDL compiler says a reorganization is required there were changes made to the DASDL source that are not permitted. In this case you will need to back out those changes, recopy the primary system DESCRIPTION file and try the compile again.
If $ ZIP is not set in your DASDL, compile the tailored DMSII software using the following command.

START DATABASE/WFL/COMPILEACR ("DB=databasename AUDIT=SET")

At this point you will have the DMSII software ready for the secondary database but no database files or CONTROL file. These will be created when you load a dump from the primary database or clone it. See Replicating a Database for more information.

Configure Databridge Server for Twin

Use this procedure to configure the Databridge Server software for Databridge Twin.

Define a DBServer SOURCE for the primary database in DATA/SERVER/CONTROL for Twin.

The SOURCE to which Databridge Twin connects must not include any of the following options:

NOTIFY AUDIT JOB FILTER STOP PREFILTERED

Warning

The SOURCE must include the following option:

TRANSFORM = RAWFORMAT
Confirm this setting, modify any other part of the file to reflect the settings for your installation, and SAVE the file.
If Databridge Server is not already running, enter the following CANDE command to start it:

START WFL/DATABRIDGE/SERVER

Refer to Databridge Server in the Databridge Host Administrator’s Guide for more instructions.

Configure Databridge Twin for the Secondary Database

Use this procedure to configure the Databridge Server software for Databridge Twin. When configuring the Databridge Twin parameter file, note the following:

You can list the options in the parameter file in any order.
You can list multiple options on a single line.
You can split options across multiple lines.
If you name any entry the same as a parameter file keyword, enclose the name in quotation marks. For example, if you create a filter named SUPPORT (which is also the name of a keyword in the Databridge Twin parameter file), enclose SUPPORT in quotation marks as follows:

FILTER "SUPPORT"

To configure Twin:

On the secondary system, get the Databridge Twin parameter file using CANDE, as follows: GET DATA/TWIN/SAMPLE/CONTROL AS DATA/TWIN/databasename/CONTROL where databasename is the name of the secondary database. If you are using a logical database, enter the logical database name in place of databasename.
Modify the Databridge Twin parameter file (DATA/TWIN/ databasename /CONTROL) to reflect settings for your site. See the following section for a description of the Twin parameters. For a sample configuration file, see Sample Databridge Twin Parameter File.
Save the Databridge Twin parameter file.

Databridge Twin Parameters

Each parameter in the Databridge Twin parameter file is explained as follows.

SOURCE

Required

The SOURCE parameter enables Databridge Twin to link up with Databridge Server. The syntax of the SOURCE parameter is:

SOURCE sourcename AT host VIA protocol PORT portnumber [ OR host2 PORT portnumber2 ... ]

Where	Is
sourcename	Your entry for the SOURCE option in the Databridge Server parameter file. The SOURCE option in the Databridge Server parameter file is a unique name that is assigned to the primary database.
host	The host name or IP address where Databridge Server is running.
protocol	TCP/IP
portnumber	The Databridge Server TCP/IP port number.
host2	An alternate Databridge Server host to use if the original host becomes unavailable due to a network failure. The alternate host must contain an exact copy of the primary database and audit files as would be the case using Remote Database Backup (RDB) or disk mirroring. Databridge Twin will revert to the original host when it detects that it has more audit available than the alternate host.
portnumber2	The Databridge Server port number of the alternate host.

SUPPORT

Optional

Enter the name of the Support library you want to use for replicating the primary database. The default support library is OBJECT/DATABRIDGE/SUPPORT. If you create a tailored support library for the secondary database, however, enter that file name instead. For an explanation of the Support Library and instructions on creating your own tailored support library, refer to the Databridge Host Administrator’s Guide.

Syntax: SUPPORT title

FILTER

Optional

Enter the name of the filter you want to use. The filter prevents replication of certain records into the secondary database. (Note that Databridge Twin ignores any column filtering.) You must create and name a filter and compile it in the tailored support library before you can enter a filter here. For instructions, refer to the Databridge Host Administrator’s Guide.

Syntax: FILTER filtername

RETRY

Optional

The default is 60 seconds. Enter the number of seconds you want Databridge Twin to wait after reaching the end of the available primary database audit. Databridge Twin will wait this many seconds before it tries to read more audit.

Syntax: RETRY numseconds

MAXWAIT

Optional

The default is 0 seconds. Enter the maximum number of seconds you want Databridge Twin to wait for more audit to become available. Since Databridge Twin is designed to run continuously, you can enter 0 (zero, which is the default) to indicate there is no limit to the waiting time.

Syntax: MAXWAIT numseconds

When you enter a value, Databridge Twin will try to access more audit every nn seconds, where nn is the value of the RETRY option. If the MAXWAIT time expires before more audit becomes available, Databridge Twin terminates on the secondary system. Once Databridge Twin terminates, you must restart it manually.

DATABASE TIMEOUT

Optional

The default is 60 seconds. Enter the maximum number of seconds you want Databridge Twin to wait after reaching the end of the available primary database audit on a host before switching to an alternate host, if specified.

Syntax: DATABASE TIMEOUT numseconds

STOP

Optional

Use this command when you want Databridge Twin to stop processing when it reaches a certain point in the audit.

You can stop Databridge Twin at a specified quiet point. The quiet point can be before or after a specified time, day, or program. For example, if you wanted to limit daily transactions to only those processed before 4:00 P.M., you would configure the STOP command to stop processing at the last quiet point before 4:00 P.M. Once Databridge Twin terminates, you must restart it manually. See Databridge Twin AX Commands for instructions.

Note

Time in the STOP command refers to the time the update occurred on the primary system, not the current time of day.

The “+/- days” are in relation to the Databridge Twin start date. For example, when Databridge Twin starts, it calculates an Audit location STOP date based on the current date plus or minus the “+/- days” parameter. Databridge Twin stops when it reaches an Audit location from the primary system with this calculated date.

Syntax:

Use one of the following examples of syntax when entering a STOP command:

STOP before_or_after timedate STOP [before_or_after "taskname" OR] before_or_after timedate

where before_or_after is either the word BEFORE or AFTER and timedate or "taskname" is a value from the following table. If you specify a taskname , you must also specify a timedate.

timedate or taskname Value	Sample Entry
hh:mm	`STOP BEFORE 22:30` This command informs Databridge Twin to stop processing at the last quiet point before 10:30 P.M.
hh:mm `AM`	`STOP AFTER 10:30 AM` This command informs Databridge Twin to stop processing at the first quiet point after 10:30 A.M.
hh:mm `PM`	`STOP BEFORE 9:45 PM` This command informs Databridge Twin to stop processing at the last quiet point before 9:45 P.M.
hh:mm + days	`STOP BEFORE 22:30 + 1` This command informs Databridge Twin to stop processing at the last quiet point before 10:30 P.M. tomorrow.
hh:mm - days	`STOP AFTER 22:30 - 1` This command informs Databridge Twin to stop processing at the first quiet point after 10:30 P.M. yesterday.
hh:mm `AM` + days	`STOP BEFORE 10:30 AM + 1` This command informs Databridge Twin to stop processing at the last quiet point before 10:30 A.M. tomorrow.
hh:mm `PM` - days	`STOP AFTER 10:30 PM - 1` This command informs Databridge Twin to stop processing at the first quiet point after 10:30 P.M. yesterday.
hh:mm ON mm/dd/yyyy	`STOP BEFORE 13:30 ON 12/9/2012` This command informs Databridge Twin to stop processing at the last quiet point before 1:30 P.M. on December 9, 2012.
hh:mm `AM ON` mm/dd/yyyy	`STOP BEFORE 10:30 AM ON 12/9/2012` This command informs Databridge Twin to stop processing at the last quiet point before 10:30 A.M. on December 9, 2012.
hh:mm `PM ON` mm/dd/yyyy	`STOP AFTER 9:30 PM ON 12/9/2012` This command informs Databridge Twin to stop processing at the first quiet point after 9:30 P.M. on December 9, 2012.
"taskname" or timedate	`STOP AFTER "OBJECT/SAVINGS/POSTING" OR BEFORE 8:15 PM` This command informs Databridge Twin to stop processing at the first quiet point after the EOT of task name "OBJECT/ SAVINGS/POSTING" or at the last quiet point before 8:15 P.M., whichever occurs first.

Keep in mind the following when using the STOP command:

The STOP command terminates Databridge Twin (it takes Databridge Twin out of the mix). To get Databridge Twin back into the mix, you must manually start Databridge Twin. See Start Databridge Twin.
If a STOP BEFORE "taskname" command is specified, Databridge Twin will stop at the quiet point before the task did an OPEN UPDATE on the database. If the task opened the database more than once, Databridge Twin will stop at the last quiet point before the first open.
If a STOP AFTER "taskname" command is specified, Databridge Twin will stop at the quiet point after the task closed the database. If the task opened the database more than once, Databridge Twin will stop at the first quiet point after the first close.
If more than one "taskname" is specified, only the last one specified is used. Similarly, if more than one timedate is specified, only the last timedate specified is used.

FIND

Optional

Normally, Databridge Twin uses the set that does not allow duplicates and contains the fewest number of key elements to find a data set record to update. In situations where a data set has subsets but no sets, you can use this option to tell Databridge Twin which subsets to use to locate records.

Enter the subsets to use when searching for a data set record when there is no set available. Use the following syntax when entering a FIND command:

FIND dataset USING subsetlist

where dataset is the data set Databridge Twin is searching for, and subsetlist is the list of subsets you want Databridge Twin to search.

For example, to search the POSTDAY, POSTUSR, and POSTBATCH subsets for a data set called EVENT, you would enter the following command:

FIND EVENT USING POSTDAY, POSTUSR, POSTBATCH;

When searching for a data set record, Databridge Twin will try the listed subsets in the order specified until it finds the record. List the subsets that most likely contain the data set record first in the subset list. If Databridge Twin does not find the data set record using the listed subsets, it reports an error and the data set record will not be updated.

UPDATERS

Optional

The default is DENIED. Use this parameter to specify if the database should open for exclusive updating by Databridge Twin (recommended) or if it should open to allow other programs to update the database concurrently with Databridge Twin.

Syntax:

UPDATERS [ DENIED | ALLOWED ]

DENIED - Only Databridge Twin can update the database.
ALLOWED - One or more programs can update the database at the same time as Databridge Twin.

Sample Databridge Twin Parameter File

Databridge Twin uses a SEQDATA file for its parameter file (DATA/TWIN/ databasename /CONTROL). This file provides information to the Databridge Twin program on where and how to locate the Databridge Server SOURCE of the primary database.

Each parameter in this file is explained in the Databridge Twin Parameters section.

%-----------------------------------------------------------------------
%
% Copyright 2019 Micro Focus or one of its affiliates.
%
% Module: DATA/TWIN/SAMPLE/CONTROL
%
% Project: Databridge
%
% Description: Databridge Twin Parameter File
%
% Copyright 2019 Micro Focus or one of its affiliates.
%
%-----------------------------------------------------------------------

                  % How to locate DBServer SOURCE ...

           SOURCE <sourcename>  % SOURCE name in DBServer parameter file
               AT <host>        % DBServer's hostname or IP address
              VIA <protocol>    % network protocol, e.g. TCPIP
             PORT <portnumber>  % DBServer's port number, e.g. 11367

           % example: SOURCE BANKDB AT PRODHOST VIA TCPIP PORT 11367

                   % Filter in DBSupport selects which records ...

           SUPPORT OBJECT/DATABRIDGE/SUPPORT  % title of DBSupport
           FILTER DBFILTER          % filter entrypoint name in "

                   % When waiting for an audit file ...

           RETRY 60                 % seconds delay between retries
           MAXWAIT 0                % max total seconds to wait

                                    % (0 means 'forever')

                  % When to stop processing ...

         % STOP AFTER "<program name>" OR BEFORE hh:mm PM ON mm/dd/yyyy

                  % How to find records using subsets if no sets

         % FIND dataset USING subset1, subset2, ...

                  % Allow other update programs ...

          UPDATERS DENIED              % DENIED - no other updaters (default)
                                       % ALLOWED - other programs can update
                                       % the client database while Twin
                                       % is running