C 1891862

IBM DB2 Information Integrator
Getting Started with Classic Event

Publishing
Version 8.2
GC18-9186-02
IBM DB2 Information Integrator
Getting Started with Classic Event

Publishing
Version 8.2
GC18-9186-02
Before using this information and the product it supports, be sure to read the general information under “Notices” on page 65.
This document contains proprietary information of IBM. It is provided under a license agreement and copyright law
protects it. The information contained in this publication does not include any product warranties, and any
statements provided in this manual should not be interpreted as such.
You can order IBM publications online or through your local IBM representative:
v To order publications online, go to the IBM Publications Center at www.ibm.com/shop/publications/order
v To find your local IBM representative, go to the IBM Directory of Worldwide Contacts at
www.ibm.com/planetwide
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2003, 2004. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
© CrossAccess Corporation 1993, 2003
Contents
Chapter 1. Overview of setting up and Chapter 5. Configuring correlation
starting Classic Event Publisher . . . . 1 services, publication services, and
Introduction to Classic Event Publisher . . . . . 1 publications . . . . . . . . . . . . 37
Overview of configuring to capture information . . 2 Copying the correlation service JCL . . . . . . 37
Overview of configuring to publish information . . 3 Configuring the correlation service and publication
Overview of starting Classic Event Publisher . . . 4 service . . . . . . . . . . . . . . . . 37
Configuring the maximum size of messages . . . 40
| Chapter 2. Preparing data and Configuring Cross Memory services . . . . . . 41
| configuring change-capture agents for Creating publications . . . . . . . . . . . 41
| CA-IDMS . . . . . . . . . . . . . . 5 Creating the Classic Event Publisher recovery data
sets . . . . . . . . . . . . . . . . . 43
| Setup procedures for CA-IDMS sources . . . . . 5
| Enabling CA-IDMS change-capture . . . . . . . 5
| Punching the schema and subschema . . . . . 6 Chapter 6. Starting the processes of
| Mapping the CA-IDMS schema and subschema . 6 capturing and publishing . . . . . . . 45
| Loading the data server metadata catalog . . . . 9 Starting the process of publishing . . . . . . . 45
| Activating change-capture in a CA-IDMS Central | Activating change-capture for CA-IDMS . . . . . 45
| Version . . . . . . . . . . . . . . . . 9 | Setting up the IDMSJNL2 exit . . . . . . . 45
| Modifying the Central Version JCL . . . . . 11 | Before starting a change-capture agent . . . . 46
| Modifying automatic journaling . . . . . . 11 | Starting an active change-capture agent . . . . 46
| Configuring a named server environment . . . 11 Activating change capture for an IMS
| Relinking the CA-IDMS database I/O module database/segment . . . . . . . . . . . . 46
| IDMSDBIO . . . . . . . . . . . . . . 12 Activating change capture for VSAM . . . . . . 47
| Relinking the presspack support module . . . . 12 Monitoring correlation services and publication
| Setting up a server to access a CA-IDMS Central services . . . . . . . . . . . . . . . . 47
| Version . . . . . . . . . . . . . . . . 13
Chapter 7. Recovering from errors . . . 49
Chapter 3. Preparing data and Introduction to recovery mode . . . . . . . . 49
configuring change-capture agents for | Starting a recovery change-capture agent for
IMS . . . . . . . . . . . . . . . . 15 | CA-IDMS . . . . . . . . . . . . . . . 50
Supported environments and program types . . . 15 | Parameter example . . . . . . . . . . . 51
Enabling IMS change capture . . . . . . . . 15 | Execution JCL . . . . . . . . . . . . 52
Mapping the sample IMS DBD and copybooks 15 | Journal files in execution JCL . . . . . . . 52
Loading the metadata catalogs . . . . . . . 22 Preparing for recovery mode when using IMS
Installing the IMS active change-capture agent . . . 23 change-capture agents . . . . . . . . . . . 52
Advantages and disadvantages of the IMS logger Recovering from errors when using IMS
exit installation options . . . . . . . . . 24 change-capture agents . . . . . . . . . . . 53
Adding the IMS logger exit to an existing exit . . . 25 Starting recovery change-capture agents for VSAM 54
Augmenting a DBD to generate IMS data capture Stopping recovery change-agents for VSAM . . . 54
log records . . . . . . . . . . . . . . 25
DB2 Information Integrator
Chapter 4. Preparing data and documentation . . . . . . . . . . . 55
configuring change-capture agents for Accessing DB2 Information Integrator
documentation . . . . . . . . . . . . . 55
VSAM . . . . . . . . . . . . . . . 27
Documentation about replication function on z/OS 57
Prerequisites for VSAM monitoring . . . . . . 27
Documentation about event publishing function for
Setup procedures for CICS monitoring for VSAM
DB2 Universal Database on z/OS . . . . . . . 58
changes. . . . . . . . . . . . . . . . 27
Documentation about event publishing function for
Configuring CICS resource definitions . . . . . 28
IMS and VSAM on z/OS . . . . . . . . . . 58
VTAM resource definitions . . . . . . . . 28
Documentation about event publishing and
CICS resource definitions . . . . . . . . . 29
replication function on Linux, UNIX, and Windows . 59
Mapping VSAM data . . . . . . . . . . . 30
Documentation about federated function on z/OS 60
Mapping the sample VSAM copybook . . . . 30
Documentation about federated function on Linux,
Loading the metadata catalogs . . . . . . . . 34
UNIX, and Windows . . . . . . . . . . . 60
Configuring change-capture agents for VSAM . . . 35
© Copyright IBM Corp. 2003, 2004 iii

Documentation about enterprise search function on Index . . . . . . . . . . . . . . . 69
Linux, UNIX, and Windows . . . . . . . . . 62
Release notes and installation requirements . . . . 62 Contacting IBM . . . . . . . . . . . 71
Product information . . . . . . . . . . . 71
Notices . . . . . . . . . . . . . . 65 Comments on the documentation . . . . . . . 71
Trademarks . . . . . . . . . . . . . . 67
iv DB2 II Getting Started with Classic Event Publishing

Chapter 1. Overview of setting up and starting Classic Event
Publisher
The following topics briefly introduce Classic Event Publisher and how to
configure and start it:
v Introduction to Classic Event Publisher
v Overview of configuring to capture information
v Overview of configuring to publish information
v Overview of starting Classic Event Publisher
Introduction to Classic Event Publisher

Classic Event Publisher captures and publishes committed changes made to
CA-IDMS databases, to IMS™ databases, or to VSAM files. Captured committed
changed-data items are first reformatted into a consistent relational data format
and then translated into a message in an Extensible Markup Language (XML)
format. The XML messages are then published to WebSphere® MQ message queues
from which they can be read by an application working with a WebSphere MQ
server, WebSphere MQ client, or with WebSphere Business Integration Event
Broker.
Each message contains changes from a single type of data source (for example,
only CA-IDMS changes, IMS changes, or VSAM changes). Each message can
contain an entire transaction or only a row-level change.
You can control which fields within which CA-IDMS files, IMS segments, or VSAM
files will be monitored for changes by using a metadata catalog to identify the
specific data items to be captured and published. This metadata catalog also
defines how the individual data items are to be reformatted into relational data
types. This relational mapping results in ″logical″ CA-IDMS, IMS, and VSAM
tables.
You can use Classic Event Publisher to push data changes to a variety of tools. The
most common consumers of changed data will be information brokers, data
warehousing tools, workflow systems and enterprise application integration (EAI)
solutions. Consider a scenario in which changing prices and inventory are
published to potential buyers. For example, a food wholesaler procures perishable
food products such as bananas from world markets in bulk and sells them to
grocery food retailers and distributors.
The value of bananas decreases the longer that they are in the warehouse. The
wholesaler wants to inform its potential buyers of the changing price and
inventory data and can set up event publishing to do that. Each time the price
changes, an XML message can be sent to potential buyers, informing them of the
″price change event.″
Each buyer (retailer or distributor) wants to maximize profit. These organizations

can determine when to buy the bananas based upon price, age (or time to spoil),
and historical knowledge regarding how quickly they can sell a certain quantity. If
they purchase too early, they will pay a higher price for the bananas and will not
achieve the maximum profit. Buying too late will likely result in spoilage and
© Copyright IBM Corp. 2003, 2004 1

again profit will not be maximized. Profit maximization can be achieved by timing
the purchase appropriately. Applications can receive the event notification
messages and generate purchase orders automatically at the right time to maximize
profit.
Overview of configuring to capture information

For each data source, there is a change-capture agent that captures changes made
to the source database or file that is being monitored. A change-capture agent runs
on the same machine as your data source. The change-capture agent monitors the
logs that are associated with your database (or in the case of VSAM, the CICS®
logs), looking for actions that affect the designated data. All log records that are
associated with logical INSERT, DELETE, and UPDATE operations are checked
against the metadata that defines which CA-IDMS files, IMS segments, and VSAM
records are to be monitored. The raw log data for monitored segments and records
is then delivered to Classic Event Publisher’s correlation service for additional
handling.
The correlation service collects information from the change-capture agents and
segregates the log data by unit-of-work identifiers. If a ROLLBACK occurs, the
correlation service discards all of the data collected for that unit of work. When a
COMMIT occurs, the correlation service processes all of the log data for that unit
of work.
The correlation service’s COMMIT-related processing reformats the data in the log
records into a relational format represented by one or more SQL Descriptor Areas
(SQLDAs). This reformatting ensures that all captured data changes are
consistently formatted before they are packaged for delivery. The SQLDAs are then
passed to the publication service that will handle the transformation into XML and
the delivery to WebSphere MQ.
The key to all of this processing is the metadata that is stored in the Classic Event
Publisher’s metadata catalog. You use Classic Event Publisher’s GUI administration
tool, Data Mapper, to define the metadata that tells Classic Event Publisher which
IMS or VSAM data is to be monitored for changes, as well as how to reformat the
IMS segment and VSAM record data into ″logical relational table″ format (i.e.
SQLDAs.). The metadata defined in the Data Mapper is then exported to the
z/OS® platform as USE GRAMMAR that is used as input to a metadata utility. The
metadata utility creates or updates the metadata stored in the Classic Event
Publisher’s metadata catalog.
The following steps provide an overview of how to configure Classic Event

Publisher to capture changes made to source data:
1. Configure change–capture agents for your source databases and populate the
metadata catalog with information about your source data.
For the steps required to configure change-capture agents for CA-IDMS
source databases and to populate the metadata catalog with information
about your CA—IDMS logical tables, see the following topics:
v Setup procedures for CA-IDMS sources
v Enabling IDMS change-capture
v Relinking the CA-IDMS database I/O module IDMSDBIO
v Relinking the presspack support module
v Setting up a server to access a CA-IDMS Central Version
2 DB2 II Getting Started with Classic Event Publishing

For the steps required to configure change-capture agents for IMS source
databases and to populate the metadata catalog with information about
your IMS logical tables, see the following topics:
v Enabling IMS change capture
v Installing the IMS active change-capture agent
v Adding the IMS logger exit to an existing exit
v Augmenting a DBD to generate IMS data capture log records
For the steps required to configure change-capture agents for VSAM source
files being updated through CICS and to populate the metadata catalog
with information about the VSAM logical tables, see the following topics:
v Prerequisites for VSAM monitoring
v Setup procedures for CICS monitoring for VSAM changes
v Configuring CICS resource definitions
v Mapping VSAM data
v Loading the metadata catalog
v Configuring change-capture agents for VSAM
2. Configure the correlation service.
For the steps required to configure the correlation service, see the following
topics:
1. Copying the correlation service JCL
2. Configuring the correlation service and publication service
3. Configuring Cross Memory services
4. Creating the Classic Event Publisher recovery data sets
Overview of configuring to publish information

A service called the publication service receives validated change-capture
information from the correlation service. The publication service matches the
change-capture information to publications, creates XML messages containing the
change-capture information, and writes the messages to WebSphere MQ message
queues. A publication tells the publication service the following information:
v The owner and name of a source logical table from which you want to publish
changed data
v Which data you want to publish from the source logical table
v The format of the messages that will contain the changes
v Which WebSphere MQ message queue you want to publish the changes to
The following steps provide an overview of how to configure DB2® Information

Integrator Classic Event Publisher to publish information:
1. Configure WebSphere MQ objects.
The publication service needs to work with one WebSphere MQ queue
manager and one or more persistent message queues. The type and
number of message queues that you create depends on the number of
target applications and where those applications are running. For example,
if you have one target application running on the same system as the
publication service, you can use a local queue to send messages to the
target application.
A publication service also needs one persistent local queue that can be
used as an in-doubt resolution queue. The publication service populates this
Chapter 1. Overview of setting up and starting Classic Event Publisher 3

queue with messages that detail its progress. If a publication fails for any
reason, the publication service looks in the in-doubt resolution queue for
information about the last unit of work that was in a message that was
committed to a message queue.
For more information about setting up WebSphere MQ objects, see the DB2
Information Integrator Planning Guide for Classic Event Publishing.
2. Configure the publication service.
For the steps required to configure the publication service, see Configuring
the correlation service and publication service.
3. Configure publications.
For the steps required to configure publications, see Creating publications.
Overview of starting Classic Event Publisher

When you are ready to start capturing changes from your source logical tables and
publishing them to WebSphere MQ, you first start the publishing process and then
the change-capture agents. This order ensures that you do not lose any captured
data.
The following steps provide an overview of how you start capturing and
publishing data with Classic Event Publisher.
1. Be sure that WebSphere MQ is running.
2. Start the correlation service, the publication service, and the publications.
For the steps required to start publishing, see Starting the process of
publishing.
3. Start the change-capture agents.
For the steps required to start change-capture agents, see the following
topics:
1. Activating change capture in a CA-IDMS Central Version
2. Activating change capture for an IMS database/segment
3. Activating change-capture for VSAM

|
| Chapter 2. Preparing data and configuring change-capture

| agents for CA-IDMS
| The following topics explain how to configure change-capture agents for CA-IDMS
| source databases:
| v Setup procedures for CA-IDMS sources
| v Enabling IDMS change-capture
| v Activating change capture in a CA-IDMS Central Version
| v Relinking the CA-IDMS database I/O module IDMSDBIO
| v Relinking the presspack support module
| v Setting up a server to access a CA-IDMS Central Version
|
| Setup procedures for CA-IDMS sources
| The following pages describe this process using a sample CA-IDMS database called
| Employee Demo Database. This database is part of the CA-IDMS installation. The
| steps outlined in this chapter are the same steps used to enable change-capture for
| your own CA-IDMS databases.
| The process includes the following steps:

| v Punch schema and subschema.
| v Map CA-IDMS schema/subschema using the Data Mapper to create logical
| tables.
| v Loading the metadata catalog with the logical tables.
| Note: It is assumed that DB2 II Classic Event Publisher has been installed on the
| mainframe and the Data Mapper is installed on a workstation.
| The process is described in detail in the next section.
| Note: For additional information about developing and deploying applications

| with DB2 II Classic Event Publisher, see the DB2 Information Integrator
| Operations Guide for Classic Event Publishing
|
| Enabling CA-IDMS change-capture
| Your CA-IDMS installation should have a sample database called Employee Demo
| Database. The schema named EMPSCHM and subschema named EMPSS01
| identify this demo database. You can use the process described in this section to
| bring your own CA-IDMS databases online.
| Note: In all the jobs that follow, you need to customize the JCL for your site. This
| customization includes concatenating CA-IDMS-specific libraries provided
| by the vendor. Templates for these libraries are included in the JCL. You
| need to uncomment the libraries and provide the appropriate high-level
| qualifiers.

| Punching the schema and subschema
| The SCACSAMP data set on the mainframe contains a member called CACIDPCH.
| This member contains sample JCL that you can use to punch the schema and
| subschema.
| To punch the schema and subschema:

| 1. Customize the JCL in member CACIDPCH to run in your environment.
| 2. Submit the JCL.
| By default, this job creates two members in the SCACSAMP data set called
| CACIDSCH and CACIDSUB. These newly-created members contain the schema
| and subschema for the Employee Demo Database.
| Mapping the CA-IDMS schema and subschema

| The SCACSAMP data set on the mainframe contains the schema and subschema
| that are created after you submit the CACIDPCH member and the job successfully
| completes. This schema and subschema describe the Employee Demo Database.
| For more detailed information on data mapping, see the IBM DB2 Information
| Integrator Data Mapper Guide for Classic Federation and Classic Event Publishing.
| To map the CA-IDMS schema and subschema:

| 1. Upload the CACIDSCH and CACIDSUB members from the SCACSAMP data
| set to the directory of your choice on the workstation where the Data Mapper
| is installed.
| As you upload these members, you must rename them with the following
| filenames:
| v cacidsch.sch
| v cacidsub.sub
| 2. From the Windows server, click Start --> IBM Data Mapper.
| 3. Select File --> Open Repository, select the Sample.mdb repository in the xadata
| directory, and click Open.
| 4. Select Edit --> Create a new Data Catalog.
| 5. Type the following information in the window:
| v Name: CUSTOMER SAMPLE - IDMS
| v Type: IDMS
| v Select the Capture check box to mark the tables for monitoring.
| 6. Click OK.
| 7. Select File --> Load CA-IDMS Schema for Reference. The Load CA-IDMS
| Schema File window appears.
| 8. From the Open window, select the schema that you uploaded from the
| mainframe (cacidsch.sch). You are prompted to load the subschema as well.
| The Load Complete message window appears. Click Yes and the Load
| CA-IDMS Schema File window appears so that you can select the subschema
| (cacidsub.sub). After the subschema is successfully loaded, the Load Complete
| message window appears. Click OK to complete the import process.
| 9. Highlight the IDMS data catalog and select Window --> List Tables. The
| IDMS Tables for Data Catalog window appears. Because this is a new data
| catalog, the list of tables is empty.
| 10. Select Edit --> Create a new Table.

| Complete the following steps to create a logical table for the CA-IDMS
| EMPLOYEE record:
| a. Leave the Name field blank. The logical table is assigned the default name
| of EMPLOYEE when you select the EMPLOYEE record in the Record
| Name field.
| b. Select CAC from the Owner field.
| c. Type the database name of sample employee database (EMPDEMO) or the
| database of the file you are mapping.
| d. Select EMPLOYEE from the Record Name field.
| e. Click OK.
| You are now ready to import the field definitions for the EMPLOYEE record
| from the currently-loaded schema.
| 11. Select File --> Import External File. The Import From Schema message
| window asks whether you would like to import from the existing schema.
| Click Yes. The Import - CA-IDMS Record Select window appears.
| 12. Ensure that the EMPLOYEE record appears to the right of the Select Records
| for Import field and click Continue. The Import Copybook window appears.
| The CA-IDMS Element definitions contained in the schema for the record
| appear in the window. These definitions are converted to SQL column
| definitions.
| 13. Click Import. The Columns for CA-IDMS Table EMPLOYEE window appears.
| 14. Close the Columns for IDMS Table EMPLOYEE window.
| 15. Close the IDMS Tables for Data Catalog CUSTOMER SAMPLE - IDMS
| window.
| At this point, you should be back to the list of data catalogs window entitled
| Sample.mdb.
| 16. Ensure the data catalog CUSTOMER SAMPLE - IDMS is highlighted and
| select File --> Generate USE Statements.
| 17. Select a file name for the generated statements to be stored on the
| workstation, for example: idms.use and click OK.
| After generation is complete, you can view the USE grammar in Windows
| Notepad or click Yes when the Data Catalog USE Generation Results window
| appears. Your completed USE grammar will look similar to the following example.
| The ALTER TABLE statement at the end notifies DB2 II Classic Event Publisher to
| capture changes for a logical table definition.
| DROP TABLE CAC.EMPLOYEE;
| USE TABLE CAC.EMPLOYEE DBTYPE IDMS EMPSCHM
| SUBSCHEMA IS EMPSS01 VERSION IS 100
| DBNAME IS EMPDEMO
| PATH IS ( EMPLOYEE )
| (
| /* COBOL Name EMP-ID-0415 */
| EMP_ID_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-ID-0415
| USE AS CHAR(4),
| /* COBOL Name EMP-FIRST-NAME-0415 */
| EMP_FIRST_NAME_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-FIRST-NAME-0415
| USE AS CHAR(10),
| /* COBOL Name EMP-LAST-NAME-0415 */
| EMP_LAST_NAME_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-LAST-NAME-0415
| USE AS CHAR(15),
| /* COBOL Name EMP-STREET-0415 */
Chapter 2. Preparing data and configuring change-capture agents for CA-IDMS 7

| EMP_STREET_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-STREET-0415
| USE AS CHAR(20),
| /* COBOL Name EMP-CITY-0415 */
| EMP_CITY_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-CITY-0415
| USE AS CHAR(15),
| /* COBOL Name EMP-STATE-0415 */
| EMP_STATE_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-STATE-0415
| USE AS CHAR(2),
| /* COBOL Name EMP-ZIP-FIRST-FIVE-0415 */
| EMP_ZIP_FIRST_FIVE_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-ZIP-FIRST-FIVE-0415
| USE AS CHAR(5),
| /* COBOL Name EMP-ZIP-LAST-FOUR-0415 */
| EMP_ZIP_LAST_FOUR_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-ZIP-LAST-FOUR-0415
| USE AS CHAR(4),
| /* COBOL Name EMP-PHONE-0415 */
| EMP_PHONE_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE EMP-PHONE-0415
| USE AS CHAR(10),
| /* COBOL Name STATUS-0415 */
| STATUS_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE STATUS-0415
| USE AS CHAR(2),
| /* COBOL Name SS-NUMBER-0415 */
| SS_NUMBER_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE SS-NUMBER-0415
| USE AS CHAR(9),
| /* COBOL Name START-YEAR-0415 */
| START_YEAR_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE START-YEAR-0415
| USE AS CHAR(4),
| /* COBOL Name START-MONTH-0415 */
| START_MONTH_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE START-MONTH-0415
| USE AS CHAR(2),
| /* COBOL Name START-DAY-0415 */
| START_DAY_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE START-DAY-0415
| USE AS CHAR(2),
| /* COBOL Name TERMINATION-YEAR-0415 */
| TERMINATION_YEAR_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE TERMINATION-YEAR-0415
| USE AS CHAR(4),
| /* COBOL Name TERMINATION-MONTH-0415 */
| TERMINATION_MONTH_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE TERMINATION-MONTH-0415
| USE AS CHAR(2),
| /* COBOL Name TERMINATION-DAY-0415 */
| TERMINATION_DAY_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE TERMINATION-DAY-0415
| USE AS CHAR(2),
| /* COBOL Name BIRTH-YEAR-0415 */
| BIRTH_YEAR_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE BIRTH-YEAR-0415
| USE AS CHAR(4),
| /* COBOL Name BIRTH-MONTH-0415 */
| BIRTH_MONTH_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE BIRTH-MONTH-0415
| USE AS CHAR(2),
| /* COBOL Name BIRTH-DAY-0415 */
| BIRTH_DAY_0415 SOURCE DEFINITION ENTRY
| EMPLOYEE BIRTH-DAY-0415

| USE AS CHAR(2)
| );
| ALTER TABLE CAC.EMPLOYEE DATA CAPTURE CHANGES;
| Loading the data server metadata catalog

| To load the catalog with the tables that you created in the previous section:
| 1. Upload the generated USE grammar (idms.use) to the SCACSAMP data set on
| the mainframe.
| 2. If you have not already allocated catalogs, run CACCATLG to allocate them.
| In the SCACSAMP data set, there is a member called CACCATLG that contains
| JCL to allocate the metadata catalog that is used by the system.
| a. Customize the JCL to run in your environment and submit.
| b. After this job completes, ensure that the data server procedure in the
| PROCLIB (default member name CACCS) points to the newly-created
| catalogs using the CACCAT and CACINDX DD statements.
| Ensure that the CACCAT and CACINDX DD statements are not commented
| in the JCL.
| 3. Load the catalog.
| In the SCACSAMP data set, there is a member called CACMETAU that
| contains JCL to load the metadata catalog using the USE grammar as input.
| Customize the JCL to run in your environment and submit.
| a. Ensure that the symbolic GRAMMAR = is pointing to the appropriate USE
| grammar member (GRAMMAR=IDMSUSE).
| b. Uncomment, and set the CA-IDMS symbolic, the STEPLIB DDs that point to
| your CA-IDMS libraries and the DDLPUNCH DD.
| c. Ensure that the CACCAT and CACINDX DDs refer to the catalogs created
| using the CACCATLG JCL.
| After you successfully run this job, the metadata catalog is loaded with the
| logical tables created in the Data Mapper.
| You can expect areturn code of 4. The DROP TABLE fails because the table
| does not exist yet.
|
| Activating change-capture in a CA-IDMS Central Version
| Activating change-capture in an IDMS Central Version requires updating the IDMS
| database I/O module to install the database exit IDMSJNL2, and modifying the
| IDMS Central Version JCL to ensure proper communication with the correlation
| service.
| The installation of the IDMS exit is a link-edit job which needs to be done only
| once during installation and is not repeated. If you created a special loadlib to
| contain the IDMSDBIO module with the exit activated, activating change-capture
| in each new Central Version requires updating the STEPLIB DD for the Central
| Version to point to the special loadlib. For detailed instructions, see the section
| ″Relinking the CA-IDMS database I/O module IDMSDBIO.″
| Once IDMSDBIO has been relinked, the CA-IDMS Central Versions must be
| restarted to pick up the new IDMSDBIO module.

| The correlation service monitors change messages from the CA-IDMS active and
| recovery agents. To determine whether an active agent can remain active at
| correlation service shutdown, the server needs to know whether the CA-IDMS
| Central Version itself is still active.
| Since the active agent running in CA-IDMS cannot notify the correlation service at
| shutdown, a jobstep must be added to the CA-IDMS Central Version JCL to notify
| the correlation service that CA-IDMS has terminated. The sample SCACSAMP
| member CACIDTRM must be added to the end of the Central Version JCL.
| The z/OS agent must be correctly set based on the Central Version number
| associated with the CA-IDMS Central Version. For example, if the Central Version
| number is 55, the parm must be specified as AGENT=’IDMS_055’. When an IDMS
| Central Version completes initialization, it issues CA-IDMS message DC201001,
| which identifes the Central Version number for that system.
| After making the necessary changes to the Central Version JCL, you can verify the
| installation by starting the Central Version and looking for the operator message
| CACH001I XSYNC AGENT ’IDMS_nnn’ INSTALLED FOR SERVER ’nnnnnnnn’
| in the Central Version JES messages. This message will only appear when the first
| journalled event takes place within the Central Version itself. To ensure a
| journalled event has occurred, you can update a record in the CA-IDMS Central
| Version using the data server product or any existing update application you have
| communicating with the Central Version.
| Once the active agent is installed, starting the Central Version without a correlation
| service will cause the message
| XSYNC SERVER ’(servername)’ NOT FOUND, REPLY ’R’ OR ’A’
| RECOVERY/ACTIVE FOR AGENT ’agentname’
| to appear on the operator console. This message indicates that database changes
| are taking place and there is no correlation service available to receive the changes.
| Though this message requires operator action, the CA-IDMS Central Version itself
| will not be halted to wait for the reply. In most cases, the operator should reply ’R’
| to this message to force the agent into recovery mode so any changes made to the
| database since it was started can be processed by the recovery agent.
| The response to this message is cached in memory until a correlation service is

| started. At that time, the agent is placed in either active or recovery mode based
| on the operator reply. As an additional safeguard, the response of ’A’ will be
| ignored by the correlation service if both of the following conditions are true:
| v The correlation service is warm started.
| v The restart dataset the correlation service processes already has the agent in
| recovery mode.
| To verify that the termination message is working correctly, the CA-IDMS Central
| Version must be running in active mode and communicating successfully with the
| correlation service. Once that has been verified, stopping the CA-IDMS Central
| Version results in a 0 return code from the CACIDTRM jobstep, and the correlation
| service issues the message:
| CACG114I SHUTDOWN RECEIVED FROM ACTIVE AGENT ’IDMS_nnn’

| Again, this will only only occur if the change-capture agent is in active mode.
| Otherwise, all active messages (including the shutdown message) are disabled, as
| recovery is necessary.
| Modifying the Central Version JCL

| When a CA-IDMS Central Version is started without a correlation service running,
| the change-capture agent running the Central Version records a restart point to a
| dataset. To enable DB2 II Classic Event Publisher to record this information, you
| must allocate an 80-byte lreel file, CACRCV, in the Central Version startup JCL.
| You must also add a jobstep to the Central Version JCL to inform the correlation
| service that the Central Version has been shut down. This allows the correlation
| service to be stopped without forcing the CA-IDMS agent into recovery mode.
| Member CACIDTRM contains a sample of the JCL that you need to add to the
| IDMS JCL.
| Modifying automatic journaling

| It is also typical for your CA-IDMS system to be setup to automatically archive
| journals when they become full. You may want to change this behavior to allow a
| certain number of active journals to remain unarchived so that they can be used by
| the CA-IDMS recovery change-capture agent to prevent having to run the
| CA-IDMS recovery change-capture agent multiple times. The number of
| unarchived journals that you need to retain is based on the size of the journal files,
| the frequency at which journals are filled up (i.e., the volume of changes in your
| CA-IDMS system) and how quickly you can detect and respond to an CA-IDMS
| Event Publisher recovery situation.
| To modify your automatic archiving procedures, you can run the recovery agent as
| part of your archiving procedure. The recovery agent counts the number of full
| CA-IDMS online journals. You can use the returned value to prevent journal
| archiving from taking place unless there are a specified number of full
| (unarchived) journals available for recovery purposes.
| Because this modification will reduce the number of archived journals available,
| you may want to increase the number of online journal files that the CA-IDMS
| Central Version uses to prevent CA-IDMS from halting due to the unavailability of
| an archived journal.
| You might also need to change your end-of-day procedures to make sure all full
| journal files are archived.
| Configuring a named server environment

| If you have multiple Central Versions running on the same LPAR and wish to run
| multiple versions of the correlation service, you must use the named server option.
| To switch an existing correlation service for CA-IDMS to a named server:
| 1. Add a NAME= parameter to the SERVICE INFO ENTRY of the correlation service
| (such as NAME=IDMSSRVR).
| 2. Update the CACE1OPT source file and add in the server name. The source
| code for the CACE1OPT module is located in the SCACSAMP library.
| 3. Re-assemble CACE1OPT and link it into the CA-IDMS database module
| IDMSDBIO.
| 4. Change the CA-IDMS recovery agent JCL by adding a SERVER= parameter to the
| execution parameter (such as SERVER=IDMSSRVR).

|
| Relinking the CA-IDMS database I/O module IDMSDBIO
| To access IDMS for change-capture, you need to relink the IDMS Database I/O
| module, IDMSDBIO. The SCACSAMP member CACIDLDB creates a backup copy
| of the existing IDMSDBIO module to the member name @BKPDBIO (if the
| member name does not already exist) in the same library. This module will be
| included in the link step. Sample JCL to relink the module IDMSDBIO is in the
| SCACSAMP member CACIDLDB.
| The module CACECA1D contains a CSECT named IDMSJNL2 which is referenced

| in IDMSDBIO as a weak external. By including CACECA1D, the IDMSJNL2
| external is resolved and the exit is active. If you already have an IDMSJNL2 exit
| active in your IDMSDBIO module, this link may not replace the active exit, and
| you need to determine whether the existing exit can be replaced by the DB2 II
| Classic Event Publisher exit, or if stacking the two exits is required.
| To replace your exit, add the link-edit control card:

| REPLACE IDMSJNL2
| before the INCLUDE SYSLIB(@BKPDBIO) card.
| Stacking the exit requires renaming your exit CSECT from IDMSJNL2 to
| IDM2JNL2 as part of the link process. If IDM2JNL2 is resolved by the DB2 II
| Classic Event Publisher exit, it will automatically call your exit whenever it
| receives control from IDMS.
| Note: These are only general instructions for stacking the exit. The actual steps
| involved in completing this process depends on how well you know the
| linkage-editor and whether or not your exit source can be changed and
| rebuilt.
| After relinking the IDMSDBIO module, you must stop and restart IDMS before the
| exit is activated. Once activated, the exit remains essentially dormant until a DB2 II
| Classic Event Publisher correlation service is started with IDMS tables mapped and
| ALTERed for change-capture.
|
| Relinking the presspack support module
| If the tables that you are monitoring use the Presspack support module to
| compress data, relink the Presspack support module CACPPK to include the IDMS
| interface module so that the correlation service can decompress the data that is
| stored in the Central Version journals. Sample JCL for the relink can be found in
| the SCACSAMP member CACIDLPP.
| Note: If you are using other compression/decompression modules or DC tables

| used by the Presspack support module, be sure to include these authorized
| libraries in the STEPLIB of the correlation service.
| If the Presspack support module fails to decompress a record, the following

| message is written to the log:
| Presspack RC=nn
| The following list shows the return codes from IDMS R14.0
| 00—Decompression successful

| 04—GETSTG failure
| 08—Call from system mode module
| 12—DCT load failure
| 16—DCT not valid
| 20—Record or table not compressed by CA-IDMS Presspack
| 24—Load of IDMSPRES failed
| >100—Error during decompression (most likely, the wrong DCT was specified);
| PRESSTO return code = return code minus 100.
|
| Setting up a server to access a CA-IDMS Central Version
| The following JCL changes are required to access an IDMS Central Version:
| 1. Add the IDMS.LOADLIB to the STEPLIB concatenation.
| 2. Add a SYSCTL DD statement and allocate the SYSCTL file used by the Central
| Version you need access to.
| Note: APF authorization is required. Certain DB2 Information Integrator Classic

| Event Publisher functions, such as Cross Memory services (used by the
| IDMS active change-capture agent), require the server’s STEPLIB to be
| APF-authorized. The CA-IDMS.LOADLIB is not usually APF-authorized,
| and some utility programs in that library will fail if they are run from an
| APF-authorized STEPLIB concatenation.
| To run DB2 Information Integrator Classic Event Publisher, you must create
| a separate authorized copy of the CA-IDMS.LOADLIB. If you are doing
| change capture on CA-IDMS records using Presspack compression, you also
| must authorize the library containing DCTABLE modules and include it in
| the server STEPLIB concatenation.
|

Chapter 3. Preparing data and configuring change-capture
agents for IMS
The following topics explain how to configure change-capture agents for IMS
source databases:
v Supported environments and program types
v Enabling IMS change capture
v Installing the IMS active change-capture agent
v Adding the IMS logger exit to an existing exit
v Augmenting a DBD to generate IMS data capture log records
Supported environments and program types

The following table identifies the IMS environments and database types that are
currently supported for change capture.
Table 1. Supported IMS environments and database types
IMS Environment Databases Supported
DB Batch Full-function
TM Batch None
DB/DC Full-function DEDB
DBCTL Full-function DEBD
DCCTL None
You can also capture updates made by CICS applications, DB2 Information
Integrator Classic Federation for z/OS, or ODBA clients using DRA.
Data capture is only supported when the batch job allocates a non-dummy
IEFRDER DD statement.
Enabling IMS change capture

Your IMS system should have the DI21PART database installed as part of the base
IMS system. Provided in the SCACSAMP data set is the DBD and two COBOL
copybooks, describing the IMS database and the segments you can use to validate
the implementation of DB2 II Classic Event Publisher . You can follow a similar
process to configure Classic Event Publisher for use with your own IMS databases.
Note: In all the jobs that follow, you will need to customize the JCL as appropriate
for your site. This includes concatenating IMS-specific libraries provided by
IBM®. Templates for these libraries are included in the JCL. You will need to
uncomment them and provide the appropriate high-level qualifiers.
Mapping the sample IMS DBD and copybooks

The SCACSAMP data set on the mainframe contains the DBD and COBOL
copybooks describing the DI21PART database. The DBD is contained in a member

called CACIMPAR and the two COBOL copybooks are in members CACIMROT
(PARTROOT segment) and CACIMSTO (STOKSTAT segment). You will need these
files to complete the following steps.
For more detailed information on data mapping, see the DB2 Information Integrator
Data Mapper Guide.
1. FTP the CACIMPAR, CACIMROT, and CACIMSTO members from the
SCACSAMP data set to a directory of your choice on the workstation where
Data Mapper is installed. As you FTP these members, rename them with the
following extensions:
v cacimpar.dbd
v cacimrot.fd
v cacimsto.fd
2. From the Windows® Start menu, select DB2 Information Integrator Data
Mapper.
3. From the File menu, select Open Repository and select the Sample.mdb
repository under the xadata directory.
4. From the Edit menu, select Create a new Data Catalog. The following screen
appears:
5. Enter the following information in the dialog box:

v Name: Parts Catalog - IMS
v Type: IMS
v Change Capture: check the check box
6. Click OK.
7. From the File menu, select Load DL/I DBD for Reference.

The Load DBD File dialog box appears.
8. Select the DBD you obtained by FTP from the mainframe (cacimpar.dbd) and
click OK.
The DL/I DBD window appears.
9. From the Window menu, select List Tables.

The IMS Table for <Data Catalog Name> dialog box appears.
Since this is a new Data Catalog, the list of tables will be empty.
Chapter 3. Preparing data and configuring change-capture agents for IMS 17

10. From the Edit menu, select Create a new Table.
The following information creates a logical table that includes the IMS root
segment PARTROOT as defined by the DBD.
You do not need to fill in the Name field, as it is automatically populated
from the Leaf Seg field.
a. Select CAC from the Owner drop down list.
b. Select PARTROOT from the Index Root drop down list.
c. Select PARTROOT from the Leaf Seg drop down list.
PARTROOT is referred to as the leaf segment because it acts as the leaf
segment as defined by this logical table.
For Classic Event Publisher you do not need to specify IMSID, PSB name
or PCB prefix information.
d. Click OK.
You are now ready to import the definitions from the CACIMROT copybook
you obtained by FTP from SCACSAMP data set.
11. From the File menu, select Import External File and select the CACIMROT
copybook that you stored on the workstation.

After the Import Copybook dialog box appears, the CACIMROT copybook is
loaded and ready to Import. (But don’t click Import until Step 13.)
12. Make sure the correct segment in the Seg. Name drop down is selected. Make
sure the PARTROOT segment is selected as it is the segment for which you
are loading the copybook.
13. Click Import. This imports the COBOL definitions from the CACIMROT
copybook into the table CAC.PARTROOT. The columns for the table are
created:
You have completed creating the logical table mapping for the PARTROOT
segment. The following steps walk you through creating the logical table for the
STOKSTAT segment.
1. Click on the window titled ″IMS Tables for Data Catalog Parts Sample for IMS″
to regain focus.

2. From the Edit menu, select Create a New Table.
The following information creates a logical table that includes the IMS
STOKSTAT segment as defined by the DBD.
You do not need to fill in the Name field, as it is automatically populated from
the Leaf Seg field.
3. Select CAC from the Owner drop down list.
4. Select PARTROOT from the Index Root drop down list.
5. Select STOKSTAT from the Leaf Seg drop down list.
STOKSTAT is referred to as the leaf segment because it acts as the leaf segment
as defined by this logical table.
For Classic Event Publisher you do not need to specify IMSID, PSB name or
PCB prefix information.
6. Click OK.
You are now ready to import the definitions from the CACIMROT copybook you
obtained by FTP from SCACSAMP data set. Follow the instructions outlined above
in steps 11, 12 and 13. When you have completed these steps, the window should
look as follows:

1. Select the DESCRIPT column (number 3) and hit the Delete key or select
″Delete the Selected Column″ from the Edit menu. The DESCRIPT column is
not part of the PARTROOT key and is not captured when changes occur to the
STOKSTAT segment.
2. From the File menu, select Import External File and select the next segment
CACIMSTO copybook that you stored on the workstation. After the Import
Copybook dialog box appears, the CACIMSTO copybook is loaded and ready
to Import.
Make sure the correct segment in the seg. name drop down is selected. Make
sure the STOKSTAT segment is selected as it is the segment for which you are
loading the copybook. Also, make sure the Append to Existing Columns check
box is checked.
3. Click Import. This concatenates the COBOL definitions from the CACIMSTO
copybook into the table CAC.STOKSTAT after the CACIMROT definitions. You
have now defined a logical table which includes a root and child segment.
4. Click Sample.mdb window to bring it in focus.

5. Ensure the Data Catalog Parts Catalog - IMS is highlighted and select Generate
USE Statements from the File menu.
6. Select a file name for the generated statements to be stored on the workstation,
for example: parts.use and click OK.
After generation is complete you can view the USE GRAMMAR from Windows
Notepad or click Yes when the Data Catalog USE Generation Results dialog box
appears. Your completed USE GRAMMAR will look similar to the following
example:
DROP TABLE CAC.PARTROOT;
USE TABLE CAC.PARTROOT DBTYPE IMS
DI21PART INDEXROOT PARTROOT PARTROOT
SCHEDULEPSB DFSSAM03
(
/* COBOL Name PARTCOD */
PARTCOD SOURCE DEFINITION ENTRY PARTROOT
DATAMAP OFFSET 0 LENGTH 2 DATATYPE C
USE AS CHAR(2),
/* COBOL Name PARTNO */
PARTNO SOURCE DEFINITION ENTRY PARTROOT
USE AS CHAR(15),
/* COBOL Name DESCRIPT */
DESCRIPT SOURCE DEFINITION ENTRY PARTROOT
USE AS CHAR(20)
);
ALTER TABLE CAC.PARTROOT DATA CAPTURE CHANGES;
DROP TABLE CAC.STOKSTAT;

USE TABLE CAC.STOKSTAT DBTYPE IMS
DI21PART INDEXROOT PARTROOT STOKSTAT
SCHEDULEPSB DFSSAM03
(
/* COBOL Name PARTCOD */
PARTCOD SOURCE DEFINITION ENTRY STOKSTAT
...
Loading the metadata catalogs

To load the metadata catalogs with the table you created in the previous section:
1. FTP the generated USE GRAMMAR (parts.use), to the SCACSAMP data set on
the mainframe.
2. Run CACCATLG to allocate the metadata catalogs.
Note: If the catalogs has already been allocated previously, you can skip this
step.
In the SCACSAMP data set, there is a member called CACCATLG. This
member contains JCL to allocate the metadata catalogs that are used by the
data server.
a. Customize the JCL to run in your environment and submit.
b. After this job completes, ensure that the data server procedure in the
PROCLIB points to the newly created catalogs using the CACCAT and
CACINDX DD statements.
Note: Ensure that the CACCAT and CACINDX DD statements are

uncommented in the JCL.
3. Load the catalogs.

In the SCACSAMP data set, there is a member called CACMETAU. This
member contains JCL to load the metadata catalogs using the USE GRAMMAR
as input.
Customize JCL to run in your environment and submit.
a. Make sure the symbolic, GRAMMAR =, is pointing to the appropriate USE
GRAMMAR member (GRAMMAR=PARTSUSE).
b. Uncomment and set the IMS symbolic and the DBDLIB DD that points to
your IMS DBD library.
c. Ensure the CACCAT and CACINDX DDs refer to the catalogs created using
the CACCATLG JCL.
After this job has been run successfully, the catalogs are loaded with the
logical tables created in the Data Mapper.
A return code of 4 is expected. The DROP TABLE fails since the table does
not exist yet.
Installing the IMS active change-capture agent

The IMS active change-capture agent is implemented as the IMS Logger Exit. The
IMS Logger Exit has a hard-coded name of DFSFLGX0. IMS automatically invokes
the IMS Logger Exit during IMS log file initialization processing if a module
named DFSFLGX0 is found in the STEPLIB concatenation or the link-pack area.
One of the easiest ways to install the IMS active change-capture agent is to copy
module DFSFLGX0 from the Classic Event Publisher distribution libraries into the
IMS RESLIB. Another method is to concatenate the Classic Event Publisher load
library into your IMS batch jobs and started task procedures for the online DB/DC
or DBCTL regions.
Another modification to the IMS region JCL provides for recovery information.
When an IMS region is started without a correlation service running, the
change-capture agent running in the region records a restart point to a data set. To
enable Classic Event Publisher to record this information, an 80-byte lrecl data set
must be allocated and referenced by a CACRCV DD statement. The CACRCV DD
statement must be added to the DB/DC or DBCTL started task JCL or into IMS
batch job JCL. A unique data set name must be created for each IMS job that a
change-capture agent will be active in.
After making the necessary changes to the IMS region JCL, you can verify the
installation by starting the DB/DC or DBCTL region and looking for the following
operator message in the IMS region JES messages:
CACH001I EVENT PUBLISHER AGENT ’IMS_xxxx’ INSTALLED FOR SERVER ’(noname)’
After the active agent is installed, starting the DB/DC or DBCTL region without a
correlation service will cause this message to appear on the operator console:
CACH002A EVENT PUBLISHER SERVER ’(noname)’ NOT FOUND BY AGENT ’IMS_xxxx’, REPLY
’R’ OR ’A’ RECOVERY/ACTIVE
This message indicates that database changes are taking place and there is no
correlation service available to receive the changes. Though this message requires
operator action, the region itself will not be halted to wait for the reply. In most
cases, the operator should reply ’R’ to this message to force the agent into recovery
mode so any changes made to the database since it was started can be processed
by the recovery agent.

The response to this message is cached in memory until a correlation service is
started. At that time, the agent is placed in either active or recovery mode based
on the operator reply. As an additional safeguard, the response of ’A’ will be
ignored by the correlation service if both of the following conditions are true:
v The correlation service is warm started.
v The restart data set the correlation service processes already has the agent in
recovery mode.
To verify that the termination message is working correctly, the DB/DC or DBCTL
region must be running in active mode and communicating successfully with the
correlation service. After that has been verified, stop the IMS region. The
correlation service should issue the message:
CACG114I SHUTDOWN RECEIVED FROM ACTIVE AGENT ’IMS_xxxx’
Again, this will only occur if the change-capture agent is in active mode.
Otherwise, all active messages (including the shutdown message) are disabled, as
recovery is necessary.
Advantages and disadvantages of the IMS logger exit

installation options
Each approach has its advantages and disadvantages. Generally you will decide
which approach to take based upon how pervasive the use of Classic Event
Publisher will be at your site.
If you are implementing a large-scale deployment, then placing the IMS Logger
Exit in the IMS RESLIB is the easiest installation method. You have a large-scale
deployment when either/or:
v You are planning to augment the majority of your IMS databases for change
capture.
v You are augmenting an IMS database for change capture that is updated by the
majority of your IMS applications.
If you are planning a smaller-scale implementation that only monitors a small

number of IMS databases updated by a small number of IMS applications, you
may want to modify these IMS batch jobs and the DB/DC or DBCTL subsystems’
started task procedures to reference the authorized Classic Event Publisher load
library.
In a large-scale deployment, you need to update each IMS batch job and DB/DC
or DBCTL subsystems’ started task JCL to include a recovery data set and
(optionally) install IMS Log File Tracking. In a small-scale implementation, the
number of IMS batch jobs and started task procedures that need to be updated are
reduced. However, if you forget to update one of your IMS applications that
updates a monitored database, these changes are lost and the correlation service
has no knowledge that this has occurred.
If you install the IMS active change-capture agent in the IMS RESLIB and are only
performing a small-scale implementation, then the correlation service still tracks all
IMS control regions that are referencing the IMS RESLIB where the IMS active
change-capture agent is installed, even though many of these IMS applications do
not update databases that are being monitored by Classic Event Publisher .
Likewise, if these IMS active change-capture agents go into recovery mode, you
have to recover these failed agents, even though no IMS changes are being
captured, making more work for you.

Adding the IMS logger exit to an existing exit
The IMS Logger Exit is somewhat an esoteric IMS system exit. IBM does not
supply a sample for this exit, so normally this exit is not used. In case you have
implemented your own IMS Logger Exit or are using an exit from another
company, the supplied version of the IMS Logger Exit does contain support for
invoking an existing IMS Logger Exit.
The SCACSAMP member CACIMLEX is a sample relink job that will create a
backup of your Logger Exit, and then relink our version of the exit with yours.
Your version of the IMS Logger Exit must be named DFSFLGX0 for the call to
succeed.
Augmenting a DBD to generate IMS data capture log records

IMS was enhanced to generate IMS Data Capture log records for use by IBM’s
DPropNR for asynchronous replication purposes. Internally, IMS uses type 50
undo/redo log records for its own recovery purposes. Unfortunately, these log
records do not contain enough information to be effectively used for change
capture purposes. IBM realized this and enhanced IMS to generate IMS Data
Capture log records that do contain all of the information necessary.
To have IMS generate IMS Data Capture records, the DBD that specifies the
information to be captured must be augmented. These DBD modifications only
affect the actual DBD definitions (stored in the DBD/ACB library) and do not
affect the physical database.
You use the EXIT= keyword to specify IMS Data Capture information. The EXIT
keyword is supported for the DBD control statement and the SEGM control
statement. Supplying an EXIT keyword on the DBD statement defines default
values for all segments in the DBD. Specifying an EXIT keyword on the SEGM
statement allows you to override the default values. This gives you great flexibility
about the types and amounts of information that is captured.
The format of the EXIT keyword is:

EXIT=(Exit-Name,KEY|NOKEY,DATA|NODATA,PATH|NOPATH,
(CASCADE|NOCASCADE,KEY|NOKEY,DATA|NODATA,PATH|NOPATH),
LOG|NOLOG)
The following table identifies the use of each of these parameters:

Table 2. Parameters of the EXIT keyword
Keyword Purpose
Exit-Name In this parameter, you specify:
v the name of the DPropNR synchronous data capture exit, if there
is one,
v * to indicate that there is no exit, or
v NONE to deactivate an exit routine on a SEGM statement
Classic Event Publisher for IMS does not use data capture exits, but
co-exists if your site is using DPropNR, or if you have implemented
your own exits at your site. If you do not have any data capture
exits, set this parameter to *.

Table 2. Parameters of the EXIT keyword (continued)
Keyword Purpose
KEY|NOKEY The value KEY indicates that you want the IMS Data Capture log
records to contain physical path concatenated key information for a
segment that has been deleted, inserted or updated. The default
value is KEY.
DATA|NODATA The value DATA indicates that you want physical segment data
included in the IMS Data Capture log records for a segment that has
been deleted, inserted or updated. The default value is DATA.
PATH|NOPATH The value PATH indicates that you want physical segment data
included in the IMS Data Capture log records for the parents of a
segment that has been deleted, inserted or updated. The default
value is NOPATH.
CASCADE|NOCASCADE Specifying the CASCADE parameter indicates that you want IMS Data
Capture log records to contain cascade delete information for a
segment that has been deleted that has child segments. When you
specify this parameter, you can specify the next three parameters
(KEY|NOKEY, DATA|NODATA, PATH|NOPATH) to identify what kind of
information you want included in the IMS Data Capture log record
for a segment when its parent is deleted.
KEY|NOKEY The value KEY indicates that you want the child segment
concatenated key information included in the IMS Data Capture log
record. The default value is KEY.
DATA|NODATA The value DATA indicates that you want the physical segment data
included in the IMS Data Capture log record for the deleted child
segment. The default value is DATA.
PATH|NOPATH The value PATH indicates that you want physical segment data
included in the IMS Data Capture log records for the parents of the
child segment that has been deleted. The default is NOPATH.
LOG|NOLOG The value LOG indicates that you want IMS Data Capture log records
to be generated to the IMS log files. If you set the Exit-Name
parameter to *, the default value for this parameter is LOG. You can
specify NOLOG on individual SEGM statements, if these segments do
not contain data that is to be captured. You can also specify NOKEY,
NODATA for segments that you do not want data captured for.
The recommended EXIT options for root segments are NOKEY, DATA, and NOPATH. The
recommended EXIT options for child segments are KEY, DATA, and NOPATH. Also,
NOCASCADE is recommended as an option. If possible, design the application that is
processing the changes to parent segments to handle the implied deletion of any
″child″ information.
In addition to specifying EXIT information in the DBD, you can also supply
VERSION information on the DBD control statement. Unless you have a specific
reason to do otherwise, allow IMS to generate the default DBD version identifier,
which is the date/time the DBD was assembled.
When the correlation service, during commit processing, processes an IMS Data
Capture record, it compares the version information contained in the record against
the version information in the DBD load module. If the version information does
not match, the correlation service logs an error message and terminates. By using
the date/time stamp of DBD assembly you are sure that the DBDs that IMS is
accessing are the same ones that the correlation service is using for reference
purposes.

Chapter 4. Preparing data and configuring change-capture
agents for VSAM
The following topics explain how to configure change-capture agents for changes
made to VSAM files through CICS:
v Prerequisites for VSAM monitoring
v Setup procedures for CICS monitoring for VSAM changes
v Configuring CICS resource definitions
v Mapping VSAM data
v Loading the metadata catalogs
v Configuring change-capture agents for VSAM
Prerequisites for VSAM monitoring

VSAM changes are captured by monitoring the CICS transactions that update
them. To monitor CICS transactions, you must:
v have enabled logging, and created a user log (DFHJ01), log of log (DFHLGLOG),
system log (DFHLOG), and system secondary log (DFHSHUNT), and
v have an application that inserts, updates, or deletes data in a VSAM file through
CICS.
If you have not enabled logging for CICS, see the CICS Transaction Server for z/OS
V2.3: Installation Guidefor instructions on enabling it.
If you do not yet have an application that interacts with a VSAM file through
CICS, you can use the sample COBOL application (FILEA) that comes with CICS.
See the CICS Transaction Server for z/OS V2.3: Installation Guide for information
about this sample application.
Setup procedures for CICS monitoring for VSAM changes

This chapter describes setting up CICS monitoring for VSAM changes using a
sample VSAM file called Employee Demo Database. This database is part of the
VSAM installation. The steps outlines in this chapter are the same steps used to
enable change capture for your own VSAM files and databases that are updated
through CICS.
The process is as follows:

v Map VSAM data using the Data Mapper to create logical tables,
v Configure CICS Resource Definitions,
v Load the Classic Event Publisher metadata catalog with logical tables, and
v Activate a VSAM change-capture agent.
Note: It is assumed that Classic Event Publisher has been installed on the
mainframe and Data Mapper is installed on a workstation.

Configuring CICS resource definitions
The metadata utility requires a connection to CICS to validate the table and collect
information about it. This is accomplish using a VTAM® LU62 connection from the
metadata utility to CICS. To set up this connection, perform the steps documented
in the following sections.
VTAM resource definitions

A VTAM APPL definition is required to communicate with CICS and to create a
VTAM mode table.
Sample member CACCAPPL in the SCACSAMP data set contains two sample VTAM
APPL definitions. CACCICS1 is not required for Classic Event Publisher for VSAM,
and can be removed. CACCICS2 is used by the metadata utility. The following is the
sample member:
*
* SAMPLE APPL ID DEFINITIONS FOR CICS INTERFACE
*
CACCAPPL VBUILD TYPE=APPL
CACCICS1 APPL ACBNAME=CACCICS1,
APPC=YES,
AUTOSES=1,
MODETAB=CACCMODE,
DLOGMOD=MTLU62,
AUTH=(ACQ),
EAS=100,PARSESS=YES,
SONSCIP=YES,
DMINWNL=0,
DMINWNR=1,
DSESLIM=100
CACCICS2 APPL ACBNAME=CACCICS2,
APPC=YES,
AUTOSES=1,
MODETAB=CACCMODE,
DLOGMOD=MTLU62,
AUTH=(ACQ),
EAS=1,PARSESS=YES,
SONSCIP=YES,
DMINWNL=0,
DMINWNR=1,
DSESLIM=1
Create a Logon Mode Table entry. The member CACCMODE in the SCACSAMP data set
contains the macro definitions to define it. Assemble and catalogue this member in
VTAM’s VTAMLIB. The following is the member’s content:
CACCMODE MODETAB
MTLU62 MODEENT LOGMODE=MTLU62,
TYPE=0,
FMPROF=X’13’,
TSPROF=X’07’,
PRIPROT=X’B0’,
SECPROT=X’B0’,
COMPROT=X’D0B1’,
RUSIZES=X’8989’,
PSERVIC=X’060200000000000000000300’
MODEEND
END

CICS resource definitions
You add CICS SIT, transaction, program, connection, and session entries to allow
the metadata utility to communicate with CICS. You also add a file and
journalmodel.
The CICS system initialization table (DFHSIT) definition or initialization overrides

must include ISC=YES to enable intercommunication programs. If this does not
already exist, add it and cycle CICS.
Copy the load modules CACCICAT from the load library to the CICS user load
library.
Install IBM’s Language Environment® (LE) in CICS.
The file CACCDEF in the SCACSAMP data set contains a sample job. Add it to the CICS
transaction, program, connection, session, and file definitions required for Classic
Event Publisher for VSAM. For Classic Event Publisher for VSAM to capture the
before and after images of a file, the RECOVERY setting must be set to ALL in the file
definition for the file, and it must specify a FWDECOVLOG for which the journal to
which the after images for forward recovery are written.
To run the job:
1. After replacing the sample values CICSUID, CICSAPPL, and DFHJ01 with
site-specific values, run the following JCL, which defines a logstream into the
MVS™ LOGGER subsystem:
//STEP1 EXEC PGM=IXCMIAPU
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DATA TYPE(LOGR) REPORT(YES)
DEFINE LOGSTREAM NAME(CICSUID.CICSAPPL.DFHJ01)
HLQ(xxxxxxx) MODEL(NO)
STG_DATACLAS(xxxxxxxx)
LOWOFFLOAD(0) HIGHOFFLOAD(80)
RETPD(n) AUTODELETE(YES)
DASDONLY(YES) DIAG(NO)
MAXBUFSIZE(65532)
/*
2. Update the job card for your site specifications.
3. Update the STEPLIB for the correct CICS library.
4. Update the DFHCSD DD for the correct CSD file.
5. Add the following user Journalmodel definition at the end:
DEFINE JOURNALMODEL (DFHJ01)
GROUP(CACVSAM)
DESCRIPTION (USER LOG STREAM)
JOURNALNAME(DFHJ01)
TYPE(MVS)
STREAMNAME (&USERID..&APPLID..&JNAME)
Note: The entries &USERID, &APPLID, and &JNAME can be modified or left
as they are.
6. Remove the program definition for CACCIVS, the EXV1 transaction, the EXC1
connection, and the EXS1 session.
7. If you are using an SMS Managed Storage for the VSAM file, run the following
job to alter LOG and LOGSTREAMID parameters in the VSAM file.
Chapter 4. Preparing data and configuring change-capture agents for VSAM 29

Use the following JCL, replacing **hilev** and **vrm** with the names used
for the Classic Event Publisher for VSAM installation, and set LOG to ALL and
specify a LOGSTREAMID.
//IDCAMS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ALTER **hilev**.**vrm**.VSAM.EMPLOYEE -
LOG(ALL) LOGSTREAMID(CICSUID.CICSAPPL.DFHJ01)
If you are using a non-SMS volume, perform the following steps:
a. Set the RECOVERY setting to ALL in the CACEMP file definition.
b. Specify the FWDRECOVLOG to 01 in CACEMP file definition.
8. After successful completion of the job, install the new definitions with the
following CICS transaction:
CEDA INSTALL GROUP(CACVSAM)
9. Next, add the CACVSAM group to your start-up group with the following CICS
transaction:
CEDA ADD GR(CACVSAM) LIST(xxxxxxxx)
where xxxxxxxx is the name of the start-up group from your SIT table.
Mapping VSAM data

Your VSAM installation should have a sample VSAM cluster. This VSAM cluster
contains 34 records of employee information. This is the database for which you
will describe how to setup monitoring. The same process described below can be
used to map and set up monitoring for your own VSAM files.
Note: In all the jobs that follow, you will need to customize the JCL as appropriate
for your site.
Mapping the sample VSAM copybook

The SCACSAMP data set on the mainframe contains a sample COBOL copybook
describing the employee VSAM cluster created during the installation process. The
member name is CACEMPFD. You need this sample copybook to complete the
following steps.
For more detailed information on data mapping, see the DB2 Information Integrator
Data Mapper Guide.
To map the sample VSAM copybook:
1. FTP the CACEMPFD member from the SCACSAMP data set to the workstation
where the Data Mapper is installed. Name the file on the workstation
cacemp.fd.
2. Start DB2 Information Integrator Data Mapper.
3. From the File menu, select Open Repository.
4. Select the Sample.mdb repository under the xadata directory.
5. From the Edit menu, select Create a new Data Catalog.

The Create Data Catalog dialog box appears.
6. Enter the following information in the dialog box:

v Name: Employee Sample - CICS VSAM
v Type: VSAM
v Check the Change Capture check box to modify the tables for monitoring.
7. Click OK.
8. From the Window menu, select List Tables.
Since this is a new Data Catalog, the list of tables will be empty.
9. From the Edit menu, select Create a new Table.

The Create VSAM Table dialog box appears.
10. In the Create VSAM Table dialog box:

a. Enter EMworkstationICS in the Name field.
b. Enter CAC in the Owner field.
c. Click the radio button labeled DD and enter the name of the CICS VSAM
data, CACEMP.
d. Enter CACCICS2 as the local Applid.
e. Enter the Applid for the CICS Applid.
f. Enter MTLU62 for the Logmode.
g. Enter EXV2 for the Transaction ID.
h. Enter a Remote Network Name, if required at your site.
11. Click OK.
You are now ready to import the definitions from the cacemp.fd copybook you
obtained by FTP from the SCACSAMP data set.
12. From the File menu, select Import External File and select the cacemp.fd
copybook that you stored on the workstation and click OK.

After the Import Copybook dialog box appears, the cacemp.fd copybook is
loaded and ready to Import.
13. Click Import.

This imports the COBOL definitions from the cacemp.fd copybook into the
table CAC.EMPLCICS, converting them into SQL data types.
14. Close the Columns for VSAM Table EMPLCICS dialog box.
15. Close the VSAM Tables for Data Catalog Employee Sample - CICS VSAM
dialog box.
At this point, you should be back to the list of Data Catalogs dialog box
named Sample.mdb.
16. Ensure the Data Catalog Employee Sample -- VSAM is highlighted and select
Generate USE Statements from the File menu.
17. Select a file name for the generated statements to be stored on the
workstation, such as empcics.use, and click OK.
After generation is complete you can view the metadata grammar (USE Grammar)
from the Windows Notepad or click Yes when the Data Catalog USE Generation
Results prompt appears. The following is an example of what your completed USE

GRAMMAR might look like.
Loading the metadata catalogs

To load the catalogs with the table you created in the previous section:
1. FTP the generated metadata grammar (metadata GRAMMAR) empcics.useto
the SCACSAMP data set on the mainframe.
2. If the catalogs have not been allocated, run CACCATLG to allocate them.
In the SCACSAMP data set, there is a member called CACCATLG. This member
contains JCL to allocate the metadata catalogs that are used by the system.
a. Customize the JCL to run in your environment and submit.
b. After this job completes, ensure that the Server Procedure in the PROCLIB
points to the newly-created catalogs using the CACCAT and CACINDX DD
statements.
Note: Make sure that the CACCAT and CACINDX DD statements are
uncommented in the JCL.
3. Load the catalogs.
In the SCACSAMP data set, there is a member called CACMETAU. This member
contains JCL to load the metadata catalogs using the metadata Grammar as
input.
4. Customize JCL to run in your environment and submit.
a. Make sure the symbolic GRAMMAR= is pointing to the appropriate metadata
Grammar member (GRAMMAR=EMPLmetadata).
b. Ensure the CACCAT and CACINDX DDs refer to the catalogs created using the
CACCATLG JCL.
After this job has been run successfully, the catalogs have been loaded with the
logical tables created in the Data Mapper.
A return code of 4 is expected. The DROP TABLE fails since the table does not exist
yet.

Configuring change-capture agents for VSAM
A VSAM change-capture agent is defined as a SERVICE INFO ENTRY to a
correlation service. This usually is a new service in a correlation service. In the
SCACCONF library, edit member CACCSCF.
The following is a sample SERVICE INFO ENTRY for the VSAM change-capture
agent:
SERVICE INFO ENTRY = CACECA1V VSAMECA 2 1 1 1 4 5M 5S \
APPLID=CICSUID STARTUP CICSUID.CICSAPPL.DFHLOG \
CICSUID.CICSAPPL.DFHJ01 CICSUID.CICSAPPL.DFHJ02 CICSUID.CICSVR.DFHLGLOG
To create a VSAM change-capture agent:
1. Uncomment the SIE for the change-capture agent (VSAMECA):
2. Specify the APPLID, STARTUP time and CICS system, user, and log of log
streams in the SIE.

Chapter 5. Configuring correlation services, publication
services, and publications
The following topics explain how to configure correlation services, publication
services, and publications:
v Copying the correlation service JCL
v Configuring the correlation service and publication service
v Configuring the maximum size of messages
v Configuring Cross Memory services
v Creating publications
v Creating the Classic Event Publisher recovery data sets
Copying the correlation service JCL

The SCACSAMP data set contains sample JCL to start the server as a started task.
To copy the correlation service JCL:

1. Copy the CACCS member from the SCACSAMP data set to your PROCLIB.
2. Customize the member to run in your environment.
Configuring the correlation service and publication service

The configuration member CACCSCF is stored in the SCACCONF data set and
contains a Service Info Entry (SIE) that defines the various services. Within the SIE
are various fields that define the service, the number of tasks started at correlation
service start up, the minimum and maximum number of tasks allowed, timeout
values, and trace options. Service Info Entries are used in configuration files to
inform the Region Controller task that a service is to be activated and how that
service is to be controlled.
Multiple SIE parameters are required to activate multiple instances of a given

service if different sub-parameter values are needed. A single SIE parameter is
used if only a single instance is needed (or multiple instances using the same
sub-parameter values). A given service’s restrictions and allowable combinations of
multiple instances are discussed in that service’s specific descriptions.
Mutually-exclusive services are also noted in these descriptions.
The SIE parameter consists of ten sub-parameters, each delimited by at least one
space. The format of the first nine of these subfields is consistent across all
services. The format for the tenth subfield is service-dependent.
The following table shows sample SIEs for the correlation service and the
publication service.
Table 3. Sample Service Info Entries for the correlation service and the publication service
Type of Sample SIEs
service
Correlation SERVICE INFO ENTRY = CACECA2 XM1/XSYN/XSYN/16 2 1 1 16 4 10MS 30S \
service TCP/111.111.111.111/SOCKET#,CSA=1K,CSARLSE=3,INT=1,WARMSTART

Table 3. Sample Service Info Entries for the correlation service and the publication
service (continued)
Type of Sample SIEs
service
Publication SERVICE INFO ENTRY = CACPUB PUB1 2 1 1 1 4 5M 5M mqi/QM_P39D/Queue1
service
The order of SIEs for the correlation service and the publication service matters.
The entry for the correlation service must come before the entry for the publication
service. This order is particularly important on shutdown, when services are
stopped in LIFO (reverse) order. The publication service must stop first so that it
can send the proper quiesce command to the correlation service. If the publication
service does not stop first, the correlation service might go into recovery mode on
an otherwise normal shutdown. For this reason, if the publication service is
configured to start before its corresponding correlation service, the publication
service will fail on startup when it fails to detect that the correlation service exists.
The parameters for the SIEs are explained below:

Parameter One: Task Name
For correlation services, the token CACECA2 is the task name and the
name of the correlation service load module. Leave this value as is.
For publication services, the token CACPUB is the task name and the
name of the publication service load module. Leave this value as is.
Parameter Two: Service Name
For correlation services, the service name token defines the protocol and
queue name for receiving raw data changes from active and recovery
agents. In most cases, the protocol name should be XM1 for Cross Memory
services. The subtoken XSYN/XSYN identifies the Cross Memory data
space and queue name and can be modified to suit any particular site
standards if applicable. The final subtoken 16 identifies the size (in
megabytes) of the change capture data space queue. This value can range
from 1 to 2048 and defaults to 8 if not specified. The size of the queue
depends on the number of expected active agents and the burst volume of
changes from each agent. A value of 16 is recommended to help ensure
queue space during peak periods.
Important: You must define a unique data space/queue name for each
correlation service that will be running at any one time.
For publication services, the service name can be a string 16 characters

long.
Parameter Three: Service Start Class
For both correlation services and publication services, leave this value set
to 2.
Parameter Four: Minimum Tasks
to 1. A value of 0 is acceptable if you want to manually start the service
with an operator command, but changing the value is not recommended.
Parameter Five: Maximum Tasks

to 1.
Parameter Six: Maximum Connections per Task
For correlation services, this value should be the maximum number of
active and recovery agents that the correlation service will service, plus
four. The additional connections are used by the publication service and
reporting utility.
Parameter Seven: Trace Output Level
Leave this value set to 4 unless you are asked to change it by IBM
technical support for problem diagnostics.
Parameter Eight: Response Timeout
This value determines the length of time that the server will listen for a
response to requests before timing out.
Parameter Nine: Idle Timeout
This value sets a polling frequency for recovery restart and rules
confirmation messages. A value of 30 seconds is recommended.
Parameter Ten: Service Specific Information
For correlation services, the first token in the service-specific information
defines the queue for communication with recovery agents and the
publication service. Generally, this token defines a TCP/IP connection
string to which the publication service connects for receiving change
messages. The format of a TCP/IP connection string is:
TCP/ip address or hostname/port number
Examples:
TCP/192.123.456.11/5555
TCP/OS390/5555
For publication services, the tenth parameter specifies the WebSphere MQ

message queue to use as the restart queue. The format of the parameter is
as follows:
mqi/queue manager/queue name
queue manager is the name of the local queue manager that manages the
message queue. queue name is the name of the local message queue to use
as the restart queue. If your correlation service is running remotely from
your publication service, you can follow the name with a comma-delimited
communication string to describe how the publication service is to
communicate with the correlation service.
Additional service information for correlation services that you can specify:
CSA=nK -- The number of kilobytes that each server is to allocate for CSA space.
In most cases, 1K should be enough to manage change capture on at least 50
tables.
CSARLSE=n--The number of seconds to wait before attempting to release CSA

storage at shutdown. A value of 0 leaves CSA allocated for reuse when the
correlation service is restarted. The default value of CSARLSE is 0, which prevents
Chapter 5. Configuring correlation services, publication services, and publications 39

CSA from being released. If CSARLSE is not 0, the server will release CSA only if
no other correlation services are still active in the system.
INT=n--The number of changes to process for a committed unit of recovery before

checking for incoming change data from active or recovery agents. This parameter
prevents large transactions from blocking the incoming raw data queue while
sending change messages to the publication service. A value of 0 will not interrupt
processing of committed messages to look for incoming raw data messages. 0 is
the default.
NOSTAE--NOSTAE disables abend detection in the correlation service. Do not

specify this value unless requested by IBM technical support for diagnostics.
NAME--Names the correlation service. If you leave this option out, the correlation
service will be started unnamed. See the DB2 Information Integrator Planning Guide
for Classic Event Publishing for more information about named servers.
COLDSTART/WARMSTART--Specifies whether to coldstart or warmstart the

server. A cold start discards all recovery information and places all known agents
in active mode. A warm start retains the state of all known change-capture agents
at the time the correlation service was last shutdown.
WARMSTART is the default action.
If you set the SIE to perform a coldstart, make sure that you reset the SIE after you
cold start the server so that you do not inadvertently cold start the server in the
future.
Configuring the maximum size of messages

The publication service draws memory buffers from the message pool (the size of
which is determined by the MESSAGE POOL SIZE parameter in the configuration
file) and constructs messages within these buffers. When the publication service is
sending messages of type TRANS, a large transaction can exceed the size of the
buffer in which it is being converted to messages. In such cases, it is useful to
allow the publication service to segment the transaction. The publication service
constructs two or more messages for the transaction and puts messages on the
queue in succession when each becomes a certain size.
Use the MAX TRANSPORT MESSAGE SIZE parameter in your configuration file
to specify in bytes the largest size that a message can be before the publication
service writes it to a message queue. For example, consider the following entry in
a configuration file:
MAX TRANSPORT MESSAGE SIZE = 262144
When the publication service constructs a message for a large transaction in the
message pool, whenever the publication service finds that the size of the message
reaches 256 KB, the publication service writes the current message to the
appropriate message queue and starts building another message to contain the
subsequent DML of the transaction. If this next message becomes 256 KB in size
before the end of the transaction is reached, the publication service writes this
message to the message queue and begins constructing another message. This
process continues until the publication service reaches the end of the transaction.

Segments are numbered sequentially by the publication service so that the
application that receives them can be sure that they are in sequence. The message
attribute isLast is set to 1 in the final message so that receiving applications can
tell when the transaction is finished.
The maximum value of MAX TRANSPORT MESSAGE SIZE is 10 percent of the

parameter MESSAGE POOL SIZE.
The minimum value is 64 KB, expressed as 65536.
The default value is 128 KB, expressed as 131072.
Configuring Cross Memory services

When configuring Cross Memory services, you must configure each correlation
service with a unique data space/queue name. You define Cross Memory services
with four tokens: protocol, data space, queue name, and data space queue size.
If you use the same combination of data space and queue name for more than one
correlation service definition, then change-capture agents will send captured
changes to the least-busy server, which might be the correct server. Names are
intentionally shared in a DB2 Information Integrator Classic Federation enterprise
server environment for load balancing and because serialization is not an issue.
But, in an Classic Event Publisher environment, serialization is essential.
Unless you have a specific reason for sharing data spaces between multiple
correlation services, use a unique data space name for each server. If you choose to
share data spaces between servers by using a common data space name, make sure
that the queue name is unique for each server.
If you configure more than one correlation service in a single data space, then the
first correlation service that is started will set the size of the data space.
Creating publications
After you configure your correlation service and your publication service, you
must configure publications to indicate where changes to mapped tables will be
published and how. You do so in the same configuration file in which you
configured your correlation service and your publication service. (If your
correlation service and publication service are remote from each other and
therefore use two different configuration files, configure your publications in the
publication service’s configuration file.)
IMS example
The following example publication uses an IMS source:

PUB ALIAS=ims1,
MSGTYPE=TRANS,
TABLE=CAC.STOKSTAT,
TOPIC=Schema1/IMS_update,
QUEUE=MQI/CSQ1/one,
BEFORE_VALUES = YES
VSAM example
The following example publication uses a VSAM source:

PUB ALIAS=vsam1,
MSGTYPE=TRANS,
TABLE=CAC.EMPCICS,
TOPIC=Schema1/VSAM_update,
QUEUE=MQI/CSQ1/one,
BEFORE_VALUES = YES
Publications are composed of the following parts:

Alias parameter
An alias defines the unique name for a publication within a Data Server.
Topic parameter (optional)
Include a topic in your publication if you want to publish it to WebSphere
Business Integrator Event Broker. Topics tell the WBI Event Broker how to
route the messages for the publication.
Queue parameter
Queues are the WebSphere MQ queues where messages are put. The
format of this parameter is MQI/queue_manager/queue_name, where MQI is
the designator for WebSphere MQ, queue_manager is the name of the queue
manager that the publication service is working with, and queue_name is
the name of the queue on which messages for the publication are put.
Message output parameters
Message output parameters define how the messages are constructed. The
table below lists these parameters and describes them.
Table 4. Message output parameters
Message output parameter Default Possible values
value
MSGTYPE TRANS
TRANS
A message is published for each
committed transaction that affects the
source table. The message contains all
of the changes made to the source table
by the transaction.
ROWOP
A message is published for each
committed row operation on the source
table.
TABLE none The Table string is used to identify the mapped
table name from which changes will be
published. There can be only one table per
publication. This table is specified in the format :
ownerName.tableName (for example,
QAVSAM.EMPLOYEES). The example above
refers to a table, QAVSAM.EMPLOYEES, that
was mapped into the Classic Event Publisher
catalog and was altered for data capture
changes.

Table 4. Message output parameters (continued)
Message output parameter Default Possible values
value
BEFORE_VALUES NO
NO When a row is updated, only the
current values for all columns are
included in the message.
YES When a row is updated, the previous
values and the current values for all
columns are included in the message.
This parameter is effective for UPDATE
operations only.
CHANGED_COLS_ONLY YES This parameter is not currently supported. Do
not change its value.
ALL_CHANGED_ROWS NO This parameter is not currently supported. Do
not change its value.
Creating the Classic Event Publisher recovery data sets

To create the Classic Event Publisher recovery data sets referenced in the
correlation service:
1. Run the SCACSAMP member, CACGDGA, to create GDG files and allocate the
first generation recovery data sets.
2. The CACGDGA member contains JCL to allocate the Classic Event Publisher
recovery data sets used by the correlation service.
a. Customize the JCL to run in your environment and submit it.
b. After this job completes, ensure that the correlation service procedure in the
PROCLIB points to the newly created data sets using the CACRCVD and
CACRCVX DD statements.
c. Ensure that the correlation service has the proper authority to allocate the
next generation of the recovery files.

Chapter 6. Starting the processes of capturing and publishing
The following topics explain how to start capturing and publishing data:
v Starting the process of publishing
v Activating change capture for CA-IDMS
v Activating change capture for an IMS database/segment
v Activating change capture for VSAM
v Monitoring correlation services and publication services
Starting the process of publishing

Before starting to publish changes that are made to your sources, ensure that the
WebSphere MQ queue manager is running and then start the correlation service
and the publication service.
If the correlation service and publication service are configured in the same file,
you either issue a console command to start the correlation service JCL procedure,
or submit a batch job. The console command to start the correlation service is:
S procname
where procname is the 1-8 character proclib member name to be started. When you
issue commands from the SDSF product, prefix all operator commands with the
forward slash ( / ) character.
If the correlation service and publication service are configured in separate files,
you can issue a console command to start the correlation service JCL procedure
and another console command to start the publication service JCL procedure. The
console command is described above. You can also choose to submit a batch job for
each.
| Activating change-capture for CA-IDMS
| Setting up the IDMSJNL2 exit

| The CA-IDMS change-capture agent is implemented as a database exit named
| IDMSJNL2. You must link edit the IDMSJNL2 exit into the IDMSDBIO module and
| restart the IDMS Centeral Version for the exit to take effect.
| Because IDMSJNL2 is a general purpose exit, you might be using your own
| version of the exit, and might want to incorporate your exit along with the DB2
| Information Integrator Classic Event Publisher version of the exit. For these cases,
| DB2 Information Integrator Classic Event Publisher supports stacking the exits.
| To incorporate your version of the exit:

| 1. Change your exit to have an internal CSECT name of IDM2JNL2 instead of
| IDMSJNL2. You can do this by either changing your exit source and
| re-assembling the exit, or by using the linkage-editor to rename the CSECT.
| Renaming using the linkage-editor can be an error-prone process and is not
| recommended unless you do not have the program source.

| 2. Link your renamed exit to the IDMSDBIO module along with the DB2
| Information Integrator Classic Event Publisher exit.
| The DB2 Information Integrator Classic Event Publisher exit contains a

| weak-external for the name IDM2JNL2. If this was resolved by link-editing your
| renamed exit, all calls to the DB2 Information Integrator Classic Event Publisher
| version of the exit are passed on to your exit as though DB2 Information Integrator
| Classic Event Publisher were not part of the IDMSDBIO module at all.
| Before starting a change-capture agent

| Before you start a change-capture agent, you must start a correlation service. If you
| do not start a correlation service before starting a change-capture agent, then the
| change-capture agent will be put into recovery mode immediately after the
| correlation service is started.
| Starting an active change-capture agent

| The change-capture agent is a CA-IDMS database exit that is automatically
| installed when you relink the CA-IDMS database I/O module IDMSDBIO as
| described in the IBM DB2 Information Integrator Installation Guide for Classic
| Federation and Classic Event Publishing. After you restart the Central Version, the exit
| is activated. To verify that the exit has been installed successfully, look in the
| CA-IDMS JES log for the following message:
| CACH001I EVENT PUBLISHER AGENT ’IDMS_nnn ’ INSTALLED FOR SERVER ’xxxxxxxx’
| This message appears after the first journaled record is written.
Activating change capture for an IMS database/segment

Change capture is implemented using two IMS features. The IMS active
change-capture agent is implemented as an IMS Logger Exit. This allows the IMS
system to be monitored for changes in near real-time.
Although IMS performs its recovery processing based on the normal contents of
the IMS log files, Classic Event Publisher does not use the “raw” log records that
IMS uses to capture changes. Classic Event Publisher does use the same log
records, in addition to some additional IMS sync-point log records, to track the
state of an in-flight Unit of Recovery (UOR), but does not use the type 50
(undo/redo) and other low-level change notification records that IMS uses for
recovery purposes.
Instead, Classic Event Publisher uses type 99 Data Capture log records to identify
changes to a monitored IMS database because these records contain more
information and are easier to deal with than the “raw” recovery records used by
IMS.
Data Capture log records are generated at the database or segment level and
require augmentation of your DBD definitions. This augmentation does not affect
the physical database definition; it adds additional information to the DBD and
ACB load module control blocks.
Augmentation consists of adding the EXIT= keyword parameter on the DBD or

individual SEGM statements in your DBD definition. You can supply default
capture values at the DBD level and override or even suppress data capture
altogether at the SEGM level.

After you augment your DBD, perform these steps:
v Run a DBDGEN for the updated DBD.
v Run the ACBGEN utility to update all PSBs that reference the DBD.
You can then put the updated DBD and PSB members into your production ACB
libraries. If you perform this augmentation using the IMS Online Change facility,
either Classic Event Publisher will go into recovery mode or you will need to
recycle the correlation service to pick up changes to an existing monitored DBD or
to add a new DBD to be monitored. As part of Classic Event Publisher installation
and customization, you update the correlation service’s JCL and add a DBDLIB
statement that references your DBD library or a copy of the DBD load modules
that are being monitored for changes.
Activating change capture for VSAM

If you have a change-capture agent for VSAM defined in the same configuration
file as your correlation service, that agents starts when you start the correlation
service. After the server is initialized, you will see the following message on the
system log:
CACH105I CICS VSAM CAPTURE: Vv.r.m mmddyyyy READY
This is followed by a message that indicates the time that processing began:
CACH106I START PROCESSING AT mm/dd/yyyy hh:mm:ss
Monitoring correlation services and publication services

After you start your correlation service and publication service, you can use MTO
commands to display reports on their activities.
Command for monitoring correlation services
cmd,name of correlation service,report
This command displays a report on the activity of the correlation service
and all change-capture agents that send it change-capture data.
The following shows an example of the results of this command.
CAC00200I CMD,XM1/IMSX/IMSX/200,REPORT
CACG150I CORRELATION SERVICE ACTIVITY REPORT
*************** Transactions ***************
Agent Processed Sent to Rules Confirmed Pending State
----------- ---------- ------------- --------- ------- -----
VSAVSAMECA 0000002 0000002 0000002 0000000 Active
CACG151I END OF REPORT, AGENT TOTAL=1

CACG152I PENDINGQ(0) MSGQ(0) UNCONFIRMED(0)
Command for monitoring publication services
Command to report activity: cmd,name of publication service,report
This command publishes a report of the number of change messages
received, the number of commit messages received, the number of commits
that are confirmed received from the correlation service, the number of
commit messages rejected by the publication service. Here is a sample
report:
Chapter 6. Starting the processes of capturing and publishing 47

CACJ001I DISTRIBUTION SERVER ACTIVITY REPORT
--------------------------------------------
Change Message(s) Received = 13
Commit Message(s) Received = 2
Commit Message(s) Confirmed = 2
Commit Message(s) Rejected = 0

Chapter 7. Recovering from errors
The following topics explain how to start publishing again if Classic Event
Publisher should go down:
v Introduction to recovery mode
v Starting a recovery change-capture agent for CA-IDMS
v Preparing for recovery mode when using IMS change-capture agents
v Recovering from errors when using IMS change-capture agents
v Starting recovery change-capture agents for VSAM
v Stopping recovery change-capture agents for VSAM
Introduction to recovery mode

When live data capture is prevented, the system moves into recovery mode.
Recovery mode ensures that no changes are lost.
Recovery is performed differently on the various change-capture agents. Recovery

occurs when an agent fails. Some reasons for an agent to fail include:
v Starting a database without a correlation service
v Shutting down the correlation service without first stopping the database
v Change-capture agent messaging failure
v Correlation service failure
v Rejection of a message by the publication service
v Rejection of a message by a WebSphere MQ message queue
These failures might not be recoverable if they are driven by change data that will
produce the same error if recovery is attempted. For example, if the data captured
and forwarded to the publication service caused the publication service to reject
the message, then the publication service will reject that message every time that
the message is resent.
The correlation service is responsible for detecting failure and returning messages
stating that the system entered recovery mode. At this point, the recovery
change-capture agent should start or be started. Depending upon the
configuration, recovery might start automatically, or might require you to run a job
or otherwise start the recovery agent manually.
When the recovery change-capture agent is started, it performs the following

actions:
1. It retrieves restart information from the correlation service.
2. It starts reading recovery source information from the native data source
log/journal.
3. It sends raw change data and syncpoint records (COMMIT and ROLLBACK) to
the correlation service.
When the recovery of data catches up with the active server, with some databases
you need to restart the database to move back into active mode with no changes
lost. However, often, it is not practical to stop the monitored database to complete
the recovery process. For these situations, Classic Event Publisher provides

methods to exit recovery mode and resume the active capture of changes from the
database system. Check the chapter of the DB2 Information Integrator Operations
Guide for Classic Event Publishing for your database for the steps that you must
take.
You can use the THROTTLE parameter to keep the recovery change-capture agent
from overtaking the correlation service. For more information about this parameter,
see the chapter of the DB2 Information Integrator Operations Guide for Classic Event
Publishing for your database.
| Starting a recovery change-capture agent for CA-IDMS

| The recovery change-capture agent for CA-IDMS is a program that reads CA-IDMS
| journal files and forwards previously journaled changes to the DB2 Information
| Integrator Classic Event Publisher correlation service. This agent can be started as a
| batch job or through automated installation procedures when the active agent
| enters recovery mode.
| Unlike the active agent, which captures changes as they are written to the journal,
| the recovery agent can process historical changes which were lost by the active
| agent due to the lack of an active correlation service or some other system failure.
| This agent can also use throttling to control the rate at which changes are sent to
| the correlation service so other active and recovery agents can continue to operate
| normally without risk of overrunning the message queue.
| The z/OS parameter controls the processing of the recovery agent. The format of
| the parameter is:
| PARM=’CV,Optkeyword=vvvv,...’
| ’LOCAL,Optkeyword=vvvv,...’
| ’ARCHIVE,Optkeyword=vvvv,...’
|
| ’REPORT,Optkeyword=vvvv,...’
| ’MONITOR,Optkeyword=vvvv,...’
| ’COUNT’
| Where:
| v CV defines recovery from one or more CA-IDMS disk journal files written by an
| CA-IDMS Central Version. In CV mode, the Central Version can either be
| running or stopped.
| v LOCAL defines recovery from a single tape or disk journal file written by a local
| mode CA-IDMS application.
| v ARCHIVE defines recovery from an archived Central Version journal file. Do
| not use the AGENT optional keyword with PARM=’ARCHIVE’.
| v REPORT requests a report of the current recovery sequence and timestamp for
| the requested agent. The AGENT keyword is required with the REPORT option.
| v MONITOR indicates whether the recovery agent will do a single check for
| recovery state, or will run as a continuous monitor for automatic recovery.
| v COUNT indicates to count the number of full recovery logs and skip automatic
| archiving if the minimum number of full journals is not available.
| v Optkeyword=vvvv is one or more optional keyword parameters, which can be
| included in the parameter string to control recovery processing.
| The following are the optional keywords for the CV, LOCAL, and REPORT parameters.
| v ACTIVATE={Y | N}. Specifies whether or not to enable the active agent on
| successful completion of processing. Specifying ‘Y’ informs the correlation

| service that all recovery messages have been sent and that the active
| change-capture agent may begin forwarding messages again after the final
| recovery message has been processed.
| Using ACTIVATE with the CV parameter is not recommended unless you need
| to disable automatic activation when continuous-mode processing ends due to
| the shutdown of an CA-IDMS Central Version.
| If this parameter is unspecified, the agent remains in recovery mode at
| termination unless continuous mode CV processing detects the shutdown of an
| CA-IDMS Central Version.
| v AGENT=agentname. Identifies the active change-capture agent name when you
| set PARM=LOCAL or the Central Version number is 0. For local agents, this
| name must be ’IDMS_jjjjjjjj’ where jjjjjjjj is the original z/OS job or started task
| name that performed the database update. For Central Version 0 systems, the
| name is ’IDMS_ssssssss’ where ssssssss is the Central Version started task name.
| For Central Version disk and tape archive files, the Central Version number
| carried in journal ‘TIME’ records is used to automatically determine the agent
| name. This name is always ‘IDMS_nnn’ where nnn is the Central Version
| number.
| PARM=’LOCAL,AGENT=IDMS_IDMJUPDT’
| You must specify this value to use the REPORT option.
| v RESTARTWAIT=nn{M|S}. Defines the wait interval in minutes or seconds for
| continuous run operation (PARM=CV). Each time the recovery agent catches up
| with the last record written by an active CA-IDMS Central Version, the recovery
| agent suspends processing for the specified interval before querying the active
| journal for new change records.
| If M or S is not specified, the value supplied is assumed to be in seconds. If the
| parameter is not specified or is specified as 0, the agent runs in non-continuous
| mode and terminates when it catches up with the current position in the active
| journal file.
| PARM=’CV,RESTARTWAIT=5S’
| v THROTTLE=nnnn. Defines a throttle value to prevent the recovery agent from
| overrunning the correlation service with change messages. The throttle value
| defines the maximum number of messages to be queued to the correlation
| service at any point in time. This ensures available space in the message queue
| for any active change-capture agents communicating with the correlation service.
| If this value is not specified, the throttle value defaults to 512. A value of 0
| disables throttling of messages.
| PARM=’CV,THROTTLE=1024’
| v TIMEOUT=nn{M|S}. Defines a timeout value when throttling is used.
| Throttling relies on the correlation service responding to requests that messages
| are received. In the event that the correlation service is unable to respond within
| the specified TIMEOUT value, the recovery server terminates with an error.
| If this value is not specified, the throttle value defaults to 5 minutes.
| PARM=’CV,THROTTLE=1024,TIMEOUT=1M’
| v SERVER=name—Specifies the name of the named correlation service that you
| want this change-capture agent to communicate with. .
| Parameter example
| An example parameter string to recover from Central Version disk files in
| continuous mode is:
| EXEC PGM=CACEC1DR,PARM=’CV,RESTARTWAIT=2S’
Chapter 7. Recovering from errors 51

| Execution JCL
| //JOBNAME JOB (ACCT,INFO),’CA-IDMS RECOVERY’,CLASS=A,MSGCLASS=X,
| // NOTIFY=&SYSUID
| //CACEC1DR EXEC PGM=CACEC1DR,
| // PARM=’CV,RESTARTWAIT=5S,TIMEOUT=5M’
| //STEPLIB DD DISP=SHR,DSN=CAC.LOADLIB
| //CTRANSDD DISP=SHR,DSN=SYS2.SASC.C650.LINKLIB
| //** CV JOURNAL DATASETS AS DEFINED IN THE DMCL SOURCE
| //** FOR CV 120.
| //J1JRNL DD DISP=SHR,DSN=CAI.CA-IDMS.J1JRNL
| //SYSPRINT DD SYSOUT=*
| //SYSTERMDD SYSOUT=*
| //
| Journal files in execution JCL

| CA-IDMS journals are read from the JnJRNL DD statements allocated in the
| recovery execution JCL. When Central Version mode is used (PARM=’CV,...’),
| multiple journal files can be included so that all journal files allocated in the
| Central Version startup JCL can be processed by the recovery change-capture
| agent.
| When allocating multiple files for Central Version mode, the order of dataset
| allocations to JnJRNL must match the processing order as defined in the CREATE
| DISK JOURNAL statements in the DMCL.
Preparing for recovery mode when using IMS change-capture agents

There are two steps that you can take to make it easier to switch from recovery
mode back to active mode when you are capturing changes from IMS databases.
Do these steps before you start your IMS change-capture agents.
1. Update the IMS JCL to include a reference to a recovery data set for each IMS
active change-capture agent that is running in your Classic Event Publisher
configuration.
Recommendation: Add a reference to a recovery data set in each IMS job or

started task that the IMS change-capture agent is installed
in. Otherwise, if you run the IMS job or start-task without a
correlation server active, you will need to manually create a
recovery data set and provide IMS restart information to
recover the changes that were lost.
2. Implement the log file tracking utility.
The IMS Log Tracking Utility is a job-step that you must add to an IMS
DB/DC or DBCTL subsystem’s log archive JCL to register the archived IMS log
file in the IMS log file tracking data set. For IMS batch jobs, additional job-steps
must be added after each job-step that updates IMS data that is monitored by
an IMS active change-capture agent. Member name CACIMSLT in SCACSAMP
contains sample JCL used to execute the IMS Log Tracking Utility.
The IMS Log Tracking Utility is command-line driven and uses fixed DD
names to identify the primary and secondary log files to be registered and the
name of the IMS log file tracking data set to be updated.
Use the command-line parameters in the following table to control the actions
of the IMS Log Tracking Utility.

Table 5. IMS Log Tracking Utility Command-Line Parameters
Keyword Value Description
DUALLOGS Y|N Specifies whether the IMS Log File Tracking Utility collects information about a
secondary IMS log file.
Y The IMS control region is using dual logging.
N The IMS control region is using single logging.
The default value is N.

PARM=’DUALLOGS=N’
ECHO Y|N Specifies whether the IMS Log File Tracking Utility issues informational WTO
messages.
Y Issue informational WTO messages.
N Do not issue informational WTO messages.
The default value is Y.

PARM=’DUALLOGS=N,ECHO=N’
MAXLOGS Number Specifies the maximum number of IMS log file entries that are to be maintained
in the IMS log file tracking data set. Specifying a value of 0, or not supplying a
MAXLOGS value causes the IMS Log File Tracking Utility to maintain an
unlimited number of IMS log file entries.
Normally, IMS log files have a certain lifetime associated with them. Generally,
the IMS log files are defined as generation data sets that have a fixed number of
generations that are retained. In these situations, supply a MAXLOGS value that
matches the number of generations being retained.
If you have specified that dual logging is being used for this IMS active
change-capture agent, the IMS Log File Tracking Utility automatically doubles
the MAXLOGS values supplied by you, because it assumes that the same
number of secondary IMS log files are retained.
PARM=’DUALLOGS=N,ECHO=N,MAXFILES=5’
For more information about recovery mode for when you are capturing data from
IMS databases, see IBM DB2 Information Integrator Planning Guide for Classic Event
Publishing.
Recovering from errors when using IMS change-capture agents

If WTO messages issued by IMS change-capture agents or by the correlation
service tell you that one or more change-capture agents are in recovery mode,
perform the following steps to return to active mode:
1. Read the output from the IMS Active Agent Status Job to identify any
change-capture agents that started before the correlation service was started
and that are now in recovery mode.
2. Tell the correlation service about the change-capture agents identified in step 1
that are not reported by the correlation service as being in recovery mode. Do
so by creating a custom input control file and run the IMS recovery
change-capture agent in ″set″ mode.
3. Identify the log files required for recovering data.
4. Recover the necessary log files.
5. Return the change-capture agents to active mode.
Chapter 7. Recovering from errors 53

For more information about these steps, see IBM DB2 Information Integrator
Operations Guide for Classic Event Publishing.
Starting recovery change-capture agents for VSAM

A VSAM change-capture agent switches from active to recovery mode if one of the
following events occurs:
v You stop the correlation service.
v You stop the change-capture agent.
v An application error causes the correlation service to stop.
A starting point is written in the correlation service’s restart data store, so the
recovery change-capture agent can locate a starting position in the log stream files.
After switching to recovery mode, the change-capture agent queries the correlation
service for the restart point and starts reading the log streams at that point. After
the end of the log streams is reached, the change-capture agent sets itself to active
mode.
Set retention period and AUTODELETE specifications of the system, user, and log
of log streams so that the data remains in the log stream for the longest period of
recovery that you want. If the retention period and AUTODELETE specifications
are met, CICS purges completed units of work on the system log file when CICS
terminates.
Stopping recovery change-agents for VSAM

There are two methods for stopping recovery change-agents for VSAM.
v If you started a recovery agent by stopping the correlation service, restart the
correlation service in either COLDSTART mode or WARMSTART mode.
– COLDSTART mode:
To switch a change-capture agent back to active mode without capturing
lost data changes:
1. Modify the Service Info Entry for the correlation service that you want
to cold start, changing the entry WARMSTART to COLDSTART.
2. Restart the correlation service with the following command:
START,SERVICE=<name> where <name> is the value of the second
parameter in the Service Info Entry for the correlation service.
3. Change the Service Info Entry by changing the COLDSTART value back to
WARMSTART.
– WARMSTART mode:
Use the following command: START,SERVICE=name where name is the value of
the second parameter in the Service Info Entry for the correlation service.
v If you started a recovery change-capture agent by stopping an active
change-capture agent or if a recovery change-capture agent started because of an
application error, restart the change-capture agent with the following command:
START,SERVICE=name where name is the value of the second parameter in the
Service Info Entry for the correlation service.

DB2 Information Integrator documentation
This topic provides information about the documentation that is available for DB2
Information Integrator. The tables in this topic provide the official document title,
form number, and location of each PDF book. To order a printed book, you must
know either the official book title or the document form number. Titles, file names,
and the locations of the DB2 Information Integrator release notes and installation
requirements are also provided in this topic.
This topic contains the following sections:

v Accessing DB2 Information Integrator documentation
v Documentation for replication function on z/OS
v Documentation for event publishing function for DB2 Universal Database on
z/OS
v Documentation for event publishing function for IMS and VSAM on z/OS
v Documentation for event publishing and replication function on Linux, UNIX,
and Windows
v Documentation for federated function on z/OS
v Documentation for federated function on Linux, UNIX, and Windows
v Documentation for enterprise search on Linux, UNIX, and Windows
v Release notes and installation requirements
Accessing DB2 Information Integrator documentation

All DB2 Information Integrator books and release notes are available in PDF files
from the DB2 Information Integrator Support Web site at
www.ibm.com/software/data/integration/db2ii/support.html.
To access the latest DB2 Information Integrator product documentation, from the
DB2 Information Integrator Support Web site, click on the Product Information
link, as shown in Figure 1 on page 56.

Figure 1. Accessing the Product Information link from DB2 Information Integrator Support Web site
You can access the latest DB2 Information Integrator documentation, in all
supported languages, from the Product Information link:
v DB2 Information Integrator product documentation in PDF files
v Fix pack product documentation, including release notes
v Instructions for downloading and installing the DB2 Information Center for
Linux, UNIX, and Windows
v Links to the DB2 Information Center online
Scroll though the list to find the product documentation for the version of DB2
Information Integrator that you are using.

The DB2 Information Integrator Support Web site also provides support
documentation, IBM Redbooks, white papers, product downloads, links to user
groups, and news about DB2 Information Integrator.
You can also view and print the DB2 Information Integrator PDF books from the
DB2 PDF Documentation CD.
To view or print the PDF documentation:

1. From the root directory of the DB2 PDF Documentation CD, open the index.htm
file.
2. Click the language that you want to use.
3. Click the link for the document that you want to view.
Documentation about replication function on z/OS

Table 6. DB2 Information Integrator documentation about replication function on z/OS
Form
Name number Location
ASNCLP Program Reference for Replication N/A DB2 Information Integrator
and Event Publishing Support Web site
Introduction to Replication and Event GC18-7567 DB2 Information Integrator
Publishing Support Web site
Migrating to SQL Replication N/A DB2 Information Integrator
Support Web site
Replication and Event Publishing Guide and SC18-7568 v DB2 PDF Documentation CD
Reference
v DB2 Information Integrator
Support Web site
Replication Installation and Customization SC18-9127 DB2 Information Integrator
Guide for z/OS Support Web site
SQL Replication Guide and Reference SC27-1121 v DB2 PDF Documentation CD
Support Web site
Tuning for Replication and Event Publishing N/A DB2 Information Integrator
Performance Support Web site
Tuning for SQL Replication Performance N/A DB2 Information Integrator
Support Web site
Release Notes for IBM DB2 Information N/A v In the DB2 Information
Integrator Standard Edition, Advanced Edition, Center, Product Overviews >
and Replication for z/OS Information Integration >
overview > Problems,
workarounds, and
documentation updates
Installation launchpad
Support Web site
v The DB2 Information Integrator
product CD
DB2 Information Integrator documentation 57

Documentation about event publishing function for DB2 Universal
Database on z/OS
Table 7. DB2 Information Integrator documentation about event publishing function for DB2
Universal Database on z/OS
Form
ASNCLP Program Reference for Replication N/A DB2 Information Integrator
and Event Publishing Support Web site
Introduction to Replication and Event GC18-7567 v DB2 PDF Documentation CD
Publishing
Support Web site
Reference
Support Web site
Integrator Standard Edition, Advanced Edition, Center, Product Overviews >
and Replication for z/OS Information Integration >
workarounds, and
Support Web site
product CD
Documentation about event publishing function for IMS and VSAM on

z/OS
Table 8. DB2 Information Integrator documentation about event publishing function for IMS
and VSAM on z/OS
Form
Client Guide for Classic Federation and Event SC18-9160 DB2 Information Integrator
Publisher for z/OS Support Web site
Data Mapper Guide for Classic Federation and SC18-9163 DB2 Information Integrator
Event Publisher for z/OS Support Web site
Getting Started with Event Publisher for z/OS GC18-9186 DB2 Information Integrator
Support Web site
Installation Guide for Classic Federation and GC18-9301 DB2 Information Integrator
Operations Guide for Event Publisher for z/OS SC18-9157 DB2 Information Integrator
Support Web site

Table 8. DB2 Information Integrator documentation about event publishing function for IMS
and VSAM on z/OS (continued)
Form
Planning Guide for Event Publisher for z/OS SC18-9158 DB2 Information Integrator
Support Web site
Reference for Classic Federation and Event SC18-9156 DB2 Information Integrator
System Messages for Classic Federation and SC18-9162 DB2 Information Integrator
Release Notes for IBM DB2 Information N/A DB2 Information Integrator
Integrator Event Publisher for IMS for z/OS Support Web site
Integrator Event Publisher for VSAM for z/OS Support Web site
Documentation about event publishing and replication function on

Table 9. DB2 Information Integrator documentation about event publishing and replication
function on Linux, UNIX, and Windows
Name Form number Location
ASNCLP Program Reference for Replication and N/A DB2 Information Integrator
Event Publishing Support Web site
Installation Guide for Linux, UNIX, and GC18-7036 v DB2 PDF Documentation CD
Windows
Support Web site
Introduction to Replication and Event GC18-7567 v DB2 PDF Documentation CD
Publishing
Support Web site
Migrating to SQL Replication N/A DB2 Information Integrator
Support Web site
Reference
Support Web site
SQL Replication Guide and Reference SC27-1121 DB2 Information Integrator
Support Web site
Tuning for SQL Replication Performance N/A DB2 Information Integrator
Support Web site

Table 9. DB2 Information Integrator documentation about event publishing and replication
function on Linux, UNIX, and Windows (continued)
Integrator Standard Edition, Advanced Edition, Center, Product Overviews
and Replication for z/OS > Information Integration >
workarounds, and
Support Web site
v The DB2 Information
Integrator product CD
Documentation about federated function on z/OS

Table 10. DB2 Information Integrator documentation about federated function on z/OS
Client Guide for Classic Federation and Event SC18-9160 DB2 Information Integrator
Data Mapper Guide for Classic Federation and SC18-9163 DB2 Information Integrator
Getting Started with Classic Federation for z/OS GC18-9155 DB2 Information Integrator
Support Web site
Installation Guide for Classic Federation and GC18-9301 DB2 Information Integrator
Reference for Classic Federation and Event SC18-9156 DB2 Information Integrator
System Messages for Classic Federation and SC18-9162 DB2 Information Integrator
Transaction Services Guide for Classic SC18-9161 DB2 Information Integrator
Federation for z/OS Support Web site
Integrator Classic Federation for z/OS Support Web site
Documentation about federated function on Linux, UNIX, and Windows

Table 11. DB2 Information Integrator documentation about federated function on Linux, UNIX,
and Windows
Form
Application Developer’s Guide SC18-7359 v DB2 PDF Documentation CD
Support Web site

Table 11. DB2 Information Integrator documentation about federated function on Linux, UNIX,
and Windows (continued)
Form
C++ API Reference for Developing Wrappers SC18-9172 v DB2 PDF Documentation CD
Support Web site
Data Source Configuration Guide N/A v DB2 PDF Documentation CD
Support Web site
Federated Systems Guide SC18-7364 v DB2 PDF Documentation CD
Support Web site
Guide to Configuring the Content Connector for N/A DB2 Information Integrator
VeniceBridge Support Web site
Installation Guide for Linux, UNIX, and GC18-7036 v DB2 PDF Documentation CD
Windows
Support Web site
Java API Reference for Developing Wrappers SC18-9173 v DB2 PDF Documentation CD
Support Web site
Migration Guide SC18-7360 v DB2 PDF Documentation CD
Support Web site
Wrapper Developer’s Guide SC18-9174 v DB2 PDF Documentation CD
Support Web site
Integrator Standard Edition, Advanced Edition, Center, Product Overviews
and Replication for z/OS > Information Integration >
workarounds, and
Support Web site
v The DB2 Information
Integrator product CD

Documentation about enterprise search function on Linux, UNIX, and
Windows
Table 12. DB2 Information Integrator documentation about enterprise search function on
Administering Enterprise Search SC18-9283 DB2 Information
Integrator Support Web
site
Installation Guide for Enterprise Search GC18-9282 DB2 Information
site
Programming Guide and API Reference for SC18-9284 DB2 Information
Enterprise Search Integrator Support Web
site
Release Notes for Enterprise Search N/A DB2 Information
site
Release notes and installation requirements

Release notes provide information that is specific to the release and fix pack level
for your product and include the latest corrections to the documentation for each
release.
Installation requirements provide information that is specific to the release of your

product.
Table 13. DB2 Information Integrator Release Notes and Installation Requirements
Name File name Location
Installation Requirements for IBM Prereqs v The DB2 Information Integrator
DB2 Information Integrator Event product CD
Publishing Edition, Replication
Edition, Standard Edition, Advanced
Installation Launchpad
Edition, Advanced Edition Unlimited,
Developer Edition, and Replication for
z/OS
Release Notes for IBM DB2 ReleaseNotes v In the DB2 Information Center,
Information Integrator Standard Product Overviews > Information
Edition, Advanced Edition, and Integration > DB2 Information
Replication for z/OS Integrator overview > Problems,
workarounds, and documentation
updates
v DB2 Information Integrator Support
Web site
product CD
Release Notes for IBM DB2 N/A DB2 Information Integrator Support
Information Integrator Event Web site
Publisher for IMS for z/OS

Table 13. DB2 Information Integrator Release Notes and Installation
Requirements (continued)
Name File name Location
Information Integrator Event Web site
Publisher for VSAM for z/OS
Information Integrator Classic Web site
Federation for z/OS
Release Notes for Enterprise Search N/A DB2 Information Integrator Support
Web site
To view the installation requirements and release notes that are on the product CD:
v On Windows operating systems, enter:
x:\doc\%L
x is the Windows CD drive letter and %L is the locale of the documentation that
you want to use, for example, en_US.
v On UNIX operating systems, enter:
/cdrom/doc/%L/
cdrom refers to the UNIX mount point of the CD and %L is the locale of the
documentation that you want to use, for example, en_US.

Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
all countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country/region or send inquiries, in
writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other
country/region where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions; therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product, and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information that has been exchanged, should contact:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
U.S.A.
Such information may be available, subject to appropriate terms and conditions,

including in some cases payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems, and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements, or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility, or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious, and any similarity to the names and addresses used by an actual
business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs, in source language, which

illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work must
include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights
reserved.
Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, other countries, or both:
IBM
CICS
DB2
IMS
Language Environment
MVS
VTAM
WebSphere
z/OS
The following terms are trademarks or registered trademarks of other companies:
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
Intel, Intel Inside (logos), MMX and Pentium are trademarks of Intel Corporation
in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product or service names may be trademarks or service marks of

others.
Notices 67
Index
A correlation service (continued)
response time out 39
Minimum tasks, correlation service 38
ABEND detection, disabling 40 Service Info Entry 37

Automatic journaling
modifying 11
shutting down without stopping
database 49
N
Named servers
starting a database without 49
configuring 40
tracing 39
C WARMSTART 40
CA-IDMS 11
NOSTAE 40
CA-IDMS CSA storage 39
configuring a named server
environment 11
enabling change-capture 5 E O
loading System Catalog 9 overview
Environments
mapping schema/subschema 6 capturing information 2
supported by IMS for change
modifying Central Version JCL 11 publishing information 3
capture 15
punching scheme/subschema 6
starting a recovery Change Capture
Agent 50
I P
starting an active change-capture Presspack Support Module
agent 52 Idle time out, correlation service 39
relinking 12
CA-IDMS Central Version IDMS
Program types
modifying JCL 11 activating change-capture 9
supported by IMS for change
Catalogs, loading enabling XSync access 13
capture 15
IMS 22 modifying automatic journaling 11
Protocol
Central Version. relinking database I/O module 12
defining for correlation service 38
See IDMS Central Version relinking Presspack Support
Punching schema/subschema 6
Change capture Module 12
activating stacking the I/O module exit 12
for IDMS 9 IDMSJNL2 exit
enabling setting up 45 Q
for an IMS database/segment 46 IMS Queue name, defining for correlation
for CA-IDMS 5 activating change capture for a service 38
type of IMS log records used 46 database/segment 46
Change Capture Agent adding logger exit to existing exit 25
messaging failure 49 Change Capture Agent
installation 23
R
recovery mode 49, 50 Recovery Change Capture Agent.
starting 49 Data Capture records 25
See Change Capture Agent, recovery
change-capture agent log file tracking 24
Recovery data sets
recovery mode mapping data 15
creating 43
restoring active status 50 supported environments and program
Recovery mode 49, 50
starting 50 types 15
Response time out, correlation
starting type of log records used for change
service 39
CA-IDMS 52 capture 46
Rules Server
COLDSTART a correlation service 40 Installation
message rejection 49
Connections, maximum for a correlation IMS Change Capture Agent 23
service 39
correlation service
COLDSTART 40 L S
configuration 37 schema
Logger exit
configuring mapping CA-IDMS 6
adding to existing exit in IMS 25
CA-IDMS named servers 11 Service Info Entry
named servers 40 correlation service 37
TCP/IP 39 SIE.
creating recovery data sets 43 M See Service Info Entry.
CSA storage 39 Mapping data Subschema
defining protocol 38 IMS 15 mapping CA-IDMS 6
defining queue name 38 Maximum connections, correlation
disabling ABEND detection 40 service 39
idle time out 39 Maximum tasks, correlation service 39
maximum connections 39 metadata catalog
minimum/maximum tasks 38 loading for CA-IDMS 9

T
TCP/IP
configuring
for correlation service 39
THROTTLE parameter 50
Tracing
correlation service 39
W
Warm starting
after a Change Capture Agent runs
without a correlation service 10, 24
correlation service 40

Contacting IBM
To contact IBM customer service in the United States or Canada, call
1-800-IBM-SERV (1-800-426-7378).
To learn about available service options, call one of the following numbers:
v In the United States: 1-888-426-4343
v In Canada: 1-800-465-9600
To locate an IBM office in your country or region, see the IBM Directory of
Worldwide Contacts on the Web at www.ibm.com/planetwide.
Product information
Information about DB2 Information Integrator is available by telephone or on the
Web.
If you live in the United States, you can call one of the following numbers:
v To order products or to obtain general information: 1-800-IBM-CALL
(1-800-426-2255)
v To order publications: 1-800-879-2755
On the Web, go to www.ibm.com/software/data/integration/db2ii/support.html.

This site contains the latest information about:
v The technical library
v Ordering books
v Client downloads
v Newsgroups
v Fix packs
v News
v Links to Web resources
Comments on the documentation

Your feedback helps IBM to provide quality information. Please send any
comments that you have about this book or other DB2 Information Integrator
documentation. You can use any of the following methods to provide comments:
v Send your comments using the online readers’ comment form at
www.ibm.com/software/data/rcf.
v Send your comments by e-mail to comments@us.ibm.com. Include the name of
the product, the version number of the product, and the name and part number
of the book (if applicable). If you are commenting on specific text, please include
the location of the text (for example, a title, a table number, or a page number).


Printed in USA
GC18-9186-02

C 1891862

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

C 1891862

Uploaded by

Copyright:

Available Formats

IBM DB2 Information Integrator

Getting Started with Classic Event

Getting Started with Classic Event

© Copyright IBM Corp. 2003, 2004 iii

iv DB2 II Getting Started with Classic Event Publishing

Introduction to Classic Event Publisher

Each buyer (retailer or distributor) wants to maximize profit. These organizations

© Copyright IBM Corp. 2003, 2004 1

Overview of configuring to capture information

The following steps provide an overview of how to configure Classic Event

2 DB2 II Getting Started with Classic Event Publishing

Overview of configuring to publish information

The following steps provide an overview of how to configure DB2® Information

Chapter 1. Overview of setting up and starting Classic Event Publisher 3

Overview of starting Classic Event Publisher

4 DB2 II Getting Started with Classic Event Publishing

| Chapter 2. Preparing data and configuring change-capture

| The process includes the following steps:

| The process is described in detail in the next section.

| Note: For additional information about developing and deploying applications

© Copyright IBM Corp. 2003, 2004 5

| To punch the schema and subschema:

| Mapping the CA-IDMS schema and subschema

| To map the CA-IDMS schema and subschema:

6 DB2 II Getting Started with Classic Event Publishing

Chapter 2. Preparing data and configuring change-capture agents for CA-IDMS 7

8 DB2 II Getting Started with Classic Event Publishing

| Loading the data server metadata catalog

Chapter 2. Preparing data and configuring change-capture agents for CA-IDMS 9

| The response to this message is cached in memory until a correlation service is

10 DB2 II Getting Started with Classic Event Publishing

| Modifying the Central Version JCL

| Modifying automatic journaling

| Configuring a named server environment

Chapter 2. Preparing data and configuring change-capture agents for CA-IDMS 11

| The module CACECA1D contains a CSECT named IDMSJNL2 which is referenced

| To replace your exit, add the link-edit control card:

| before the INCLUDE SYSLIB(@BKPDBIO) card.

| Note: If you are using other compression/decompression modules or DC tables

| If the Presspack support module fails to decompress a record, the following

12 DB2 II Getting Started with Classic Event Publishing

| 08—Call from system mode module

| 12—DCT load failure

| 16—DCT not valid

| 20—Record or table not compressed by CA-IDMS Presspack

| 24—Load of IDMSPRES failed

| Note: APF authorization is required. Certain DB2 Information Integrator Classic

Chapter 2. Preparing data and configuring change-capture agents for CA-IDMS 13

Supported environments and program types

Enabling IMS change capture

Mapping the sample IMS DBD and copybooks

© Copyright IBM Corp. 2003, 2004 15

5. Enter the following information in the dialog box:

16 DB2 II Getting Started with Classic Event Publishing

9. From the Window menu, select List Tables.

Chapter 3. Preparing data and configuring change-capture agents for IMS 17

18 DB2 II Getting Started with Classic Event Publishing

Chapter 3. Preparing data and configuring change-capture agents for IMS 19

20 DB2 II Getting Started with Classic Event Publishing

4. Click Sample.mdb window to bring it in focus.

DROP TABLE CAC.STOKSTAT;

Loading the metadata catalogs