IMS Data Capture Exits

Data capture exits enable updates to segments in a DL/I database to be passed to a data capture exit program. Mainframe IMS provides these exits to propagate data to DB2, commonly using the IBM Data Propagator product. Data Propagator takes the data capture exits and uses them to propagate data to DB2. You can also write your own data capture exits to perform propagation or other functions.

This is an emulation of a mainframe feature.

Invocation

Data capture exits are invoked at run time when a change or changes occur on a segment for which the exit routine is defined. You specify a data capture exit in one of two ways:

• In JCL when invoking the DBD, using EXIT=exitname
• In DBD source, using SEGM=exitname

Data capture is enabled by default. Therefore, if the database has exits defined, they are executed automatically.

Important: Be sure that all defined data capture exits are present. However, if your DBD source contains one or more data capture exits that are not needed to support a migrated application or not required for offload testing, you can do one of the following to prevent them from executing:

• Remove all unneeded data capture exits from the DBD source and recompile.
• Recompile using the mfims dbdgen command with the NODCX directive. This prevents Enterprise Server from loading any data capture exit routines specified in the DBD source. Use this option when none of the data capture exit routines in your DBD source are required, for example, during offload testing. This enables you to test without modifying your DBD source. See NODCX for details.

Coding Requirements

Enterprise Server supports the use of IMS data capture exits in COBOL coded using the specifications in the IBM mainframe IMS documentation, except as noted in this documentation; however, Enterprise Server does not support IBM Data Propagator functionality. See the IBM Web site for access to IBM documentation.

Note: We do not require that you compile or assemble all of the exits defined in your DBDs. Simply download the exits required by your application. If the runtime cannot locate a specific exit program, it writes a message to the console log and continues as if the exit were not defined in the DBD.

Use the following as guidelines when coding data capture exits:

• Enterprise Server supports:
  • Data capture exits written in COBOL.
  • A maximum of nine exit routines for any one DBD segment, with no limit on the total number of data capture exits defined for all segments in a DBD.
  • All fields in the XPCB and XSDB parameter blocks, with appropriate actions for all XPCB return codes.
  • Databases that use logical relationships. In these, segment deletes can cascade across a maximum of 32 nested hierarchical relationships and up to a maximum of 99 segment levels.
  • Data capture exit programs that make DL/I calls to any PCB defined in the currently active PSB.
• One IMS application region supports a maximum of 256 active exit routines. This means that you can define any number of exits in the DBDs referenced by PSBs; however, updates to segments cannot cause more than 256 exits to be called. An exit becomes active as its corresponding database segment is updated and calls the exit.
• Data capture exits support the following operands:

  EXIT

  Supported for both DBD and SEGM statements with the following options:

  • KEY
  • DATA
  • PATH
  • CASCADE, including the KEY and DATA sub-options

  Note: Enterprise Server does not support the CASCADE PATH sub-option or the LOG option, meaning that data capture log records are not written to disk and therefore are not available for asynchronous processing.

  VERSION

  Supported for the DBD statement. The XPCB parameter block points to the value of the VERSION operand. The maximum length of the VERSION value is 128 bytes (after any substitution). If no VERSION operand is specified, a default 13-byte date-time stamp is generated. The &SYSDATE and &SYSTIME substitutable variables are also supported.

Run-time Behavior

The following describes the run-time behavior expected for data capture exits:

• Data capture exits are called from all IMS application region types, including BMP and DL/I regions as well as CICS and the IMS Dynamic Database Attach (DDBA) region type.
• We follow standard rules for the calling sequence of exits. This includes calling the exit multiple times, if necessary for path calls, in a top-down order. Exits are called in a bottom-up sequence for cascaded deletes.
• Unlike mainframe IMS, we do not perform before- and after-image segment compare during replace operations. Replace calls always cause the segment to be updated, even if the data was not changed, meaning that we always call data capture exits for a replace call whether or not the data was modified.
• If you compile the data capture exit program for debugging, it is shown by the respective debugger when the exit is called.
• XPCB return codes of 8 or greater are recorded in the Enterprise Server console log.