Augmenting and downloading DBDs for IMS change data capture

IMS Remote Source replicates changes that are made to an IMS database by using the IMS data capture record (0x99).

An EXIT statement added to an IMS DBD or SEGM definition enables the production of data capture records. An IMS DBDGEN must then be run, and the DBD must be updated in the active ACBLIB, before IMS starts generating data capture log records when the database is modified by an application. In a managed ACB environment, the same basic procedure must be performed with the DBD augmented with EXIT statements, staged, and then promoted.

EXIT parameter

The format of the EXIT parameter is as follows:

EXIT=(Exit-
Name,KEY|NOKEY,DATA|NODATA,PATH|NOPATH,FLD|NOFLD,INPOS|NOINPOS
,SSPCMD|
NOSSPCMD(CASCADE|NOCASCADE,KEY|NOKEY,DATA|NODATA,PATH|NOPATH),
LOG|NOLOG)

For more details on the format of the EXIT parameter and the CASCADE operand, see Database Description (DBD) Generation utility.

The table that follows describes how IMS Remote Source uses each of these parameters.

Table 1. Parameters used by IMS Remote source
Keyword	Purpose and usage
Exit-Name	The name of the synchronous data capture exit. An asterisk () indicates that there is no exit. To disable an exit routine in a SEGM statement, specify NONE. However, IMS Remote Source does not use data capture exits, it can coexist with an existing exit. If you do not have any data capture exits, enter an asterisk () as the Exit-Name keyword. If you already have an exit and its data capturing options differ from those required by IMS Remote Source, define the EXIT options first.
KEY\|NOKEY	Indicates whether you want the log records to include concatenated key information on the physical path of deleted, inserted, or modified segments. The default is KEY. The KEY option is optional for a root segment or when the PATH parameter is supplied. The KEY option should be included when all relational tables that reference a child segment contain columns that correspond to parent segment sequence fields. Note: If this database is being replicated with InfoSphere IMS Replication for z/OS version 11.3.0, the KEY must be provided.
DATA\|NODATA	Indicates whether you want to include before and after images of the altered segment in the log entries for deleted, inserted, and updated segments. The default is DATA. DATA must be provided for the leaf section in a relational table.
PATH\|NOPATH	Indicates whether to include physical segment data in log records for deleted, inserted, or updated segments. The default setting is NOPATH. If a relational table mapping has columns that refer to nonsequence fields in the parent segment, PATH must be given.
FLD\|NOFLD	When an application uses a FLD call to update a DEDB database, IMS determines whether a data capture log record should be created. The default setting is NOFLD. If you are unsure whether any of your applications make FLD calls, offer the FLD option. Enabling this option adds no further burden to IMS unless FLD updates are detected. In that instance, you want the modifications to be recorded and replicated on the target.
DLET\|NODLET	Determines whether X'99' log records are written for DLET calls. This applies just to the DEDB database. The default is DLET. Do not specify NODLET.
BEFORE\|NOBEFORE	Indicates whether the preceding data is included in X'99' log records for REPL calls. This applies just to the DEDB database. The default is BEFORE. Do not specify NOBEFORE
CASCASE\|NOCASCADE	Specifies whether the exit routine is called on when a segment is deleted, as well as whether data captures records for any deleted child segments are created. The default is CASCADE. NOCASCASE specifies that IMS does not need to establish data capture records for any removed child segments. NOCASCADE should be used if the data is being replicated to a relational target with referential integrity rules enabled that simulate the effect of deleting the parent segment, or if the consuming application implements something similar to referential integrity rules for a nonrelational target. When not provided, the default contents of the data capture records for deleted child segments are KEY, DATA, and NOPATH IMS Remote Source allows NOPATH to be specified for table mappings that include columns that reference nonsequence fields in parent segments. If the data capture record for a cascade delete does not include column information, the target receives a NULL response.
LOG\|NOLOG	Indicates whether you want to create log entries for data collection in IMS log files. If you enter an asterisk (*) for Exit-Name, the default value is LOG. If you already have a data capture exit in place, make sure LOG is specified.

You can specify EXIT information on the DBD and/or SEGM statements. If the DBD statement has the code EXIT, the settings provided apply to all segments in the database. When an EXIT statement is specified on a SEGM statement, it controls the information included in the data capture log record for that segment and overrides the information that is supplied on the DBD EXIT statement. It can also be used to selectively generate data capture log records when an EXIT is not specified on the DBD statement and only a subset of the segments in the IMS database need to be captured.

You can also use the following SEGM-level EXIT statement to prevent data capture records from being generated when EXIT information is provided on the DBD statement:

EXIT=(*,NOKEY,NODATA,NOPATH,(NOCASCADE),NOLOG)

Versions of the DBD used by IMS Remote Source

IMS Remote Source requires access to several copies of an IMS DBD, as detailed in the following table.

Table 2. IMS DBD
Tool/component	Format	Use
Classic Data Architect	Source	To define a relational table in Classic Data Architect, you must first download and import the source specification of each DBD. Classic Data Architect use SEGM statements to populate choose list items and to determine the database structure (parent-child relationships) when mapping a child segment. The DBD that is imported into CDA does not need to include EXIT information. The source definition can only include DBD, SEGM, and other statements; any third-party statements must be manually deleted before the DBD can be imported into CDA.
Container	DBDLIB binary	The IMS Remote Source Linux container loads a binary version of the DBD from the DBDLIB directory. This version of the DBD is used to process a CREATE TABLE or ALTER statement, and to reference an active table mapping in a subscription when replication is enabled. When processing data captures log entries, the container validates the mapping information and allocates storage to build I/O regions by using the EXIT information, as well as the DBD structure and SEGM information in the binary version of the database. The container does not verify that the information in the copy of the DBD downloaded to the container is consistent with the version of the DBD referenced by the IMS Remote Source log reader, or the actual version of the DBD used by IMS.
IMS Remote Source log reader	DBDLIB or managed ACB active library	When a refresh process begins, the IMS Remote Source log reader checks DBD information to get segment length and EXIT augmentation information for the relational table being refreshed. The information is used to determine what data should be delivered to the container based on the EXIT information, as well as whether path calls will be used to access the database. This information will be obtained by the IMS Remote Source log reader through the IMS-managed ACB interface for full-function databases. If managed ACB is not enabled or a DEDB database is being refreshed, this information is retrieved from the DBDLIB datasets. When a DL/I batch entry occurs in the RECON, the IMS DBDLIB is queried (optionally) during stream activation processing. If no EXIT information is available for a DBD, it is assumed that the associated log does not include data capture entries and not be read. The DLIUSELOGALLINFO configuration parameter controls the analysis of the DBDLIB for DL/I batches.

Procedure

To augment a DBD to capture all required changes, follow these steps:

To capture log entries for changing data, add an EXIT keyword to the SEGM command for each DBD segment.
1. Use the KEY option to add concatenated key information to the log record to specify the physical path to the modified segment.
2. Use the DATA option to record before and after picture data for the altered section in the log records.
3. If the database and table definitions do not adhere to the third normal form design standards, use the PATH option to include physical segment data in log records for parent segments that have changed.
  If they follow the third normal form, use the NOPATH option.
4. Use the relevant cascade option.
  If you construct the target database with the necessary referential integrity and delete rules to support cascading, you do not need to create an IMS CASCADE option. Otherwise, use CASCADE.
Run DBDGEN to get the modified DBD.
Use the ACBGEN function to update all program specification blocks (PSBs) referencing the DBD.
Add updated DBD and PSB members to your production ACLIB libraries.
On the system where the IMS Remote Source container is deployed, use binary FTP or SFTP to download the DBD, then copy it to the classiccdcdbdlib volume's mount location. For more information, refer to Preparing a source IMS subsystem for replication.
On the system where the IMS Remote Source container is deployed, use binary FTP or SFTP to download the DBD, then copy it to the classiccdcdbdlib volume's mount location.
Use CDA to obtain and import the DBD source definition.
CDA employs FTP protocols; if these are not permitted, you can use a safe method to download the DBD source definition to a drive/directory accessible to CDA and then use the local import option.