Data Capture exit routine

You can write a Data Capture exit routine that receives control whenever a segment, for which the exit routine is defined, is updated. Your exit routine processes the data after the DL/I call completes but before control is returned to the application program.

This topic contains Product-sensitive Programming Interface information.

When an application program updates an IMS™ database with a DL/I insert, replace, or delete call, the original and updated data, as applicable, are passed and made available to a Data Capture exit routine. The DL/I call is considered complete and the PCB status is set when the exit routine is called. The following figure shows how control passes among the application, the full-function or DEDB database, and the exit routine.

Figure 1. Calling order with data capture

Graphic shows calling order with Data Capture exit routine.

You might want to capture changed data so that you can replicate that data to a Db2 for z/OS® database as shown in the previous figure.

As an alternative to capturing data synchronously, you can also propagate captured data asynchronously by using either of the following methods:

Use the logging option on the EXIT= parameter of DBDGEN.
Use IMS DataPropagator and specify that the data is to be propagated asynchronously.

The following table describes data capture support for IMS environments for both full-function and DEDB databases.

Table 1. Data capture support for IMS environments
	CICS® DB/CTL	CICS Batch	IMS Batch	IMS IFP	IMS BMP	IMS MPP
Data Capture Exit EXIT=`exit_name`	No	Yes¹	Yes	Yes	Yes	Yes
Asynchronous Data Capture EXIT= *, LOG	Yes	Yes¹	Yes	Yes	Yes	Yes
Note: ¹BATCH is a pure IMS batch environment that is available with CICS DB/CTL (no CICS code executing).

Subsections:

About this routine
Communicating with IMS
Extended Program Communication Block (XPCB)
Extended Segment Data Block (XSDB)
Writing the routine in supported languages
Storage requirements for Data Capture
Storage failure
Data security and integrity

About this routine

The main purpose of capturing updated data and making it available to an exit routine is to propagate the IMS data to the relational environment of Db2 for z/OS. You can write your own exit routine, use a separate product, use IBM® IMS DataPropagator for z/OS, or write a IMS DataPropagator-supported exit routine. If you write your own exit routine, you can code it to perform tasks other than data propagation. The sample Data Capture exit routine provided at the end of this topic only propagates data.

Restriction: This exit routine cannot be used with CICS, because it conflicts with CICS architecture. (Asynchronous Data Capture does work with DBCTL.) Even though the exit routine works with captured IMS data, CICS cannot use it.

Attributes of the routine

Start of change Regardless of its function, you must write the routine in assembly language, C language, COBOL, or PL/I. Routines written in high-level languages running under Language Environment® for z/OS are not supported. Sample exit routines are provided in COBOL and PL/I. End of change

Running Data Capture exit routines under Language Environment for z/OS might result in performance problems unless the dependent region that is running the application that causes the Data Capture exit routine to execute is pre-initialized in the Language Environment for z/OS. This can be done with the preinitialization list. Otherwise, every execution of the application in a dependent region causes the Language Environment for z/OS to be initialized each time the application is invoked and stopped each time the application terminates.

Binding the routine

If you bind the exit routine as either RENT or REUSE, it remains in storage until the region terminates as if the exit routine was preloaded. However, non-REUSE exit routines must be loaded each time, because they are deleted from storage after each call.

Loading the routine

IMS loads the exit routine the first time IMS calls it; preloading the exit routine is not necessary. However, runtime library routines used by high-level languages should be preloaded. After abnormal termination in an IMS Fast Path region (IFP) or in a message processing region (MPP), the exit routine is deleted and must be reloaded. The exit routine must be reloaded when:

A pseudo or standard abend of the application that is running in the region occurs (regardless of whether the region itself abends along with the application).
The data capture routine gets an XPCB return code of 16.

Specifying data options

In addition to the necessary control information, you can have the following data passed to your exit routine. The data is chained together using pointers.

Physical concatenated key: The fully concatenated key of each segment in the physical hierarchy, including the updated segment. For logical relationships and secondary indexes, this key differs from the key in the PCB feedback area.
Physical segment data: The physical segment updated by the application program, without any PSB field sensitivity.
Data before a replace: The data as it looked before it was updated. Your exit routine must determine what fields the application program changed.
Path data: The physical path data from the root segment to the parent of the updated segment.
Cascade delete data: The data deleted by IMS when an application program deleted a segment that is higher in the hierarchy.

The data is in the same format that was returned to the application program, excluding PSB field sensitivity. For logical children, the segment data follows the logical parent concatenated key. For segments with compression/edit exit routines defined for them, the data is in its expanded or encoded form. For variable-length segments, the first two bytes contain the length ('LL') for the segment.

Additional guidelines

The Data Capture exit routine is called whenever a segment is updated that has the exit routine defined, regardless of the execution environment. The exit routine uses the INQY ENVIRON call to identify the execution environment (batch or online) and determine what functions are available.

The exit routine can issue any DL/I calls allowed by the PSB using the AIB Interface (AIBTDLI). However, any updates that the exit routine makes are not captured and do not call an exit routine.

The Data Capture exit routine is treated as an extension of the application program; IMS attributes SQL or DL/I calls made by the exit routine to the application program. The exit routine and the application run under the same unit of work. SQL and DL/I updates made by the exit routine are committed or aborted along with the application program at sync-point time with the same integrity as the application. The exit routine must follow the same rules as the application program whether the routine makes IMS or Db2 for z/OS requests.

For data propagation, all DL/I updates must be passed to the exit routine to determine whether to propagate the change to Db2 for z/OS or not. Both the IMS data and Db2 for z/OS data must be available and on the same z/OS system for either update to occur.

Start of change The Data Capture exit routine is called based on specification in the DBD rather than in the PSB. Unless otherwise defined, the exit routine is always called: when implemented for any segment or database, all activity in that segment or database causes IMS to call the exit routine, regardless of which PSB is active. In this scenario, any performance impact that the exit routine causes occurs across the entire system. However, if you do not require the Data Capture exit routine to be called for the activity of a specific CCTL or ODBM address space, you can specify the job name of the CCTL or ODBM address space on the SUPPDCAPNAME= parameter in the DFSDFxxx member. If a job name of a CCTL or ODBM address space is specified on the SUPPDCAPNAME= parameter, database updates that are invoked by the job are not captured, even if a Data Capture exit routine is specified on the DBD. End of change

Defining the routine for segments

The Data Capture exit routine is specified for a particular segment during DBDGEN. Failure to locate the exit routine during processing results in an application program abend.

DBDGEN supports the parameter, EXIT=, on the DBD and SEGM statements. If specified on the DBD statement, the parameter applies to all segments within the physical database structure. If specified on the SEGM statement, you can override the specification on the DBD, or can limit the parameter so that only selected segments are propagated when updated. As a SEGM parameter, EXIT= does not apply to other segments; physical children do not inherit the parameters of any of their parents.

You can specify multiple exit routine names, each with different data options, on a single DBD or SEGM statement.

Multiple exit routines

A single DL/I call might call your exit routine more than once or it might call more than one exit routine. Multiple exit routines are called when there are:

Multiple exit routines per segment
Path calls
Cascade deletes

Multiple exit routines are called in succession before returning to the application program. The sequence depends on the reason multiple exit routines are called:

Multiple exit routines are defined.
When multiple exit routines are defined for a single physical segment, the routines are called based on DBDGEN definition order. The first exit routine listed in the DBD or SEGM statement is called, followed by each subsequent exit routine defined for that segment.
Multiple segments are updated.
When multiple physical segments are updated in a single call, the routines are called in hierarchical order. IMS calls the exit routines for the segments in the same order that the segments were physically updated:
- Top-down for path inserts and path replaces:
  
  Parents must be inserted before dependents. The exit routine for the parent segment must be called before the dependent segment's exit routine.
- Bottom-up for cascade deletes:
  
  The dependent segment's exit routine is called before the parent's exit routine. The root segment's exit routine is called last. If the dependent segment has several exit routines defined for it, they are all called at this time. Calling the exit routines in bottom-up order allows propagation to Db2 for z/OS without requiring referential integrity.
  
  For each segment type, multiple segment occurrences might be deleted as part of the cascade delete. Each exit routine is called once for each segment occurrence that is deleted. The order the exit is called is the same order in which DL/I deleted the segments.

Using IMS callable services with this routine

This exit is not eligible to use IMS callable services.

Communicating with IMS

Each segment that is passed in a dependent region and has the Data Capture exit routine defined for it has two control blocks available for its use. Both the Extended Program Communication Block (XPCB) and the Extended Segment Data Block (XSDB) reside in private storage and have key 8. They are passed to the exit routine according to the AMODE of the exit: above the 16 MB line for AMODE 31, and below the 16 MB line for AMODE 24.

The order in which the control blocks receive control depends on the type of data updated and passed to the Data Capture exit routine. The following figure shows how control flows between the XPCB and the XSDB.

Figure 2. Control block flow with data capture

A decision tree is shown with one box at the top of the tree, representing XPCB. There are three lines branching off the top box (XPCB) in the tree each representing control block flow for: a) segment data; b) data before a replace; and c) path data. If segment data is passed to the Data Capture exit routine it will flow first from register 1 into XPCB and then flow directly into XSDB. If data before a replace is passed to the Data Capture exit routine, it will flow first from register 1 into XPCB and then flow directly into XSDB. If path data is passed to the Data Capture exit routine, it will flow first from register 1 into XPCB and then into first XSDB, next into subsequent XSDBs, and finally into last XSDB.

Contents of registers on entry

On entry, the exit routine must save all registers using the provided save area. The registers contain the following:

Register	Contents
1	Address of the XPCB address
13	Address of save area
14	Return address to IMS
15	Entry point of exit routine

Contents of registers on exit

Before returning to IMS, the exit routine must restore all registers. Return and reason codes are placed in the XPCB.

Return and reason codes

The XPCB contains fields for the exit routine to communicate its status to IMS. These fields are initialized to binary zeros. The return code set by the exit routine defines the type of condition encountered; the higher the number, the more severe the error. You can also assign a reason code to return codes of 8 or greater. The reason code is for your use; IMS uses only the return code.

The following table outlines the return and reason codes that the exit routine returns and places in the XPCB. If the return code placed in the XPCB is invalid, an abend occurs and an invalid return code indicator is set.

Table 2. XPCB return codes
Return code	Description	Action	DFS3314 message
0	Good return.	Normal completion of exit routine.	No
4	Indicates the exit routine wants to ignore the DL/I call.	Exit routine is not called for any additional segments for this DL/I call.	No
8	Exit routine encountered an error during the DL/I call and wants to return to the application.	DL/I call is terminated without calling any other exit routines and control is returned to application program.	Yes
12	This copy of the exit routine is not to be called again. (Used with a dummy exit routine.)	Exit routine is deleted from storage.	Yes
16	Abend the exit routine and the application program.	Application program is abended with a U3314.	Yes
20	Do not make further calls to this routine, or any other Data Capture routines, for this region.	Terminate data capture for this region.	Yes

After an abend in an IFP or MPP region with return code 12 or 20, the interface control blocks are reinitialized and the exit work area is reset. The exit routine can then be called again.

Extended Program Communication Block (XPCB)

The XPCB identifies the segment and call functions, provides the address of a work area, and contains additional information that is passed to the exit routine. Every XPCB identifies the physical function performed by DL/I (insert, replace, or delete) and points to the updated data that is passed to the exit routine. The following two tables describe the contents of the XPCB.

For reentrant exit routines, the address of a 256-byte work area is passed in the XPCB. The exit routine can use the work area to save information. One work area exists for each exit routine, and it is initialized to binary zeros the first time the exit routine is given control.

Table 3. XPCB by offset
Offset	Field name	Offset	Field name	Offset	Field name
0	Eye catcher	4	Version	6	Release
8	User_Exit_Name	16	Exit_Return_Code	18	Exit_Reason_Code
20	Database_Name	28	DBD_Version_Ptr	32	Segment_Name
40	Call_Function	44	Physical_Function	48	reserved
52	DB_PCB_Ptr	56	DB_PCB_Name	64	INQY_Output_Ptr
68	IO_PCB_Ptr	72	Environment_Flags	73	reserved
74	Conc_Key_Length	76	Conc_Key_Ptr	80	Data_XSDB_Ptr
84	Before_XSDB_Ptr	88	Path_XSDB_Ptr	92	Set_Rols_Token
96	Next_Twin_Ptr	100	Cmd_Codes_Ptr	104	Exit_Work_Ptr
108	Null_Ptr	112	reserved	116	Call_Timestamp

Table 4. XPCB alphabetically
Field name	Offset	Data type	Length	Field description
Before_XSDB_Ptr	84	Pointer	4	Address of XSDB for data before it was replaced. Zero if not a physical replace or if data not captured.
Call_Function	40	Character	4	Call used by application to update segment: ISRT, DLET, REPL, FLD (field), or CASC (cascade).
Call_Timestamp	116	Character	8	Time stamp of completion of DL/I call. Obtained from Store Clock instruction.
Cmd_Codes_Ptr	100	Pointer	4	Address of command codes. This field points to a data area that has the same format as the COMMAND_CODES in the CAPD block format.
Conc_Key_Length	74	Fixed	2	Length of the segment concatenated key for physical path. Zero if data not captured. Key is optional.
Conc_Key_Ptr	76	Pointer	4	Address of the segment concatenated key for physical path. Zero if data not captured. Key is optional.
Database_Name	20	Character	8	Name of physical database that contains the updated segment.
Data_XSDB_Ptr	80	Pointer	4	Address of XSDB for segment data. Zero if data not captured.
DBD_Version_Ptr	28	Pointer	4	Address of variable length character string to identify the DBD used for update. First 2 bytes contain length of string, followed by string itself. String is from DBD VERSION= parameter if it was used for DBDGEN. Otherwise, string is date/time of DBDGEN.
DB_PCB_Ptr	52	Pointer	4	Address of database PCB used for DL/I call.
DB_PCB_Name	56	Character	8	The 8-byte name of database PCB used for DL/I call. Null if name not assigned during PSBGEN with the label or PCBNAME= parameter.
Environment_Flags	72	Flag byte	1	Flag bits describing execution environment.
Exit_Return_Code	16	Fixed	2	Return code from exit routine.
Exit_Reason_Code	18	Fixed	2	Reason code from exit routine.
Exit_Work_Ptr	104	Pointer	4	Address of 256-byte work area.
Eye catcher	0	Character	4	'XPCB'
INQY_Output_Ptr	64	Pointer	4	Address of output of an INQY ENVIRON call.
IO_PCB_Ptr	68	Pointer	4	Address of I/O PCB.
Next_Twin_Ptr	96	Pointer	4	Address of XSDB for the data of the twin that follows the segment being inserted. Zero if not a twin or if no other twins exist for the non-unique segment.
Null_Ptr	108	Pointer	4	Zero address for use as null address for languages that do not recognize a zero address as null (such as PL/I).
Path_XSDB_Ptr	88	Pointer	4	Address of XSDB for physical root when path data option requested. XSDBs for path data are chained together, in descending hierarchical order, from physical root to parent of updated segment. Last XSDB has a zero pointer.
Physical_Function	44	Character	4	Physical call function performed: ISRT, DLET, or REPL.
Release	6	Character	2	XPCB release indicator. Along with version, identifies the level of the control block. The current release is R3.
Segment_Name	32	Character	8	Physical segment name of segment updated.
Sets_Rols_Token	92	Hexadecimal data	4	Token that is used to identify the processing scope between the SETS and ROLS calls.
User_Exit_Name	8	Character	8	Entry point name of exit routine.
Version	4	Character	2	XPCB version indicator. Along with release, identifies the level of the control block. The current version is V1.

Extended Segment Data Block (XSDB)

The XPCB points to the first XSDB. For path data, subsequent XSDBs are chained together. The XSDB points to the updated data that is passed to the exit routine. It contains additional information that is also passed. The following two tables describe the contents of the XSDB.

Table 5. XSDB by offset
Offset	Field name	Offset	Field name	Offset	Field name
0	Eye catcher	4	Version	6	Release
8	Next_Ptr	12	Database_Name	20	Segment_Name
28	Physical_Path	29	CMD_CODE_R	30	reserved
32	Segment_Level	34	Key_Length	36	Key_Ptr
40	LP_Key_Length	42	Segment_Length	44	Segment_Ptr
48	reserved

Table 6. XSDB alphabetically
Field name	Offset	Data type	Length	Field description
CMD_CODE_R	29	Flag byte	1	Subset pointer command codes R1 through R8. Each bit represents whether or not the corresponding command code number was specified on the SSA.
Database_Name	12	Character	8	Name of physical database that contains the updated segment.
Eye catcher	0	Character	4	'XSDB'
Key_Length	34	Fixed	2	Length of key for segment. Zero if segment not keyed.
Key_Ptr	36	Pointer	4	Address of key for segment. Zero if segment not keyed.
LP_Key_Length	40	Fixed	2	Length of the concatenated key of a logical parent segment included in segment data for logical children.
Next_Ptr	8	Pointer	4	Address of next XSDB in chain for path data. Zero for last XSDB in chain.
Physical_Path	28	Character	1	Access by physical path (Y/N)
Release	6	Character	2	XSDB release indicator. Along with version, identifies level of control block. The current release is R2.
Segment_Ptr	44	Pointer	4	Address of physical segment data.
Segment_Length	42	Fixed	2	Length of physical segment data.
Segment_Level	32	Fixed	2	Level of segment in physical database.
Segment_Name	20	Character	8	Physical segment name for segment data passed in this block. Different from segment name in XPCB for path data.
Version	4	Character	2	XSDB version indicator. Along with release, identifies level of control block. The current version is V1.

Writing the routine in supported languages

Although the Data Capture exit routine can be written in assembler language, C, COBOL, or PL/I, you must follow certain guidelines depending on which language you use.

Assembler

The exit routine is entered in primary mode, but the access registers can be nonzero.

C does not support variable-length character strings using integer lengths, such as those passed in the XPCB and XSDB. Key and segment data passed to the exit routine is terminated by null (binary zero) values. Any null value in the data itself might result in an invalid string length.

The following declarations and statements are used to locate the XPCB. Declare XPCB_TYPE_PTR as a pointer to the XPCB structure.

XPCB_TYPE_PTR *TPTR;
TPTR = (XPCB_TYPE_PTR *) __sysplist;
XPCB = *TPTR;

The exit routine must be defined as a main program with the PLIST(IMS) and ENV(IMS) options specified. Use the following format to specify these options:

#pragma runopt(env(IMS), plist(IMS))

COBOL

The exit routine operates under a separate run unit from the application program. The method used to establish the run unit depends on the compiler or on the RES/NORES compiler option. For all COBOL programs compiled with newer compilers, and older COBOL programs compiled with resident (RES), the exit routine is given control by LINK. For older COBOL programs compiled with nonresident (NORES), it is given control directly.

Recommendation: Use a compiler with RES and code the exit routine as reentrant (RENT) and AMODE 31. With older compilers and NORES, the routine must be AMODE 24 and it must not be reentrant.

Attention: You can use GOBACK to terminate the exit routine run unit and return to the application program, but do not use STOP RUN and EXIT PROGRAM because they are not supported and might cause unpredictable results or abends.

The procedure division is:

exitname USING XPCB

PL/I

The exit routine must be compiled as a main program. The entry point can be PLICALLA, so that the exit routine can use the assembler interface or use PL/I compile-time option SYSTEM(IMS)

The procedure statement is:

exitname:  PROCEDURE(XPCB_PTR) OPTIONS (MAIN);

Storage requirements for Data Capture

As your application program issues a DL/I call to update the database, the updates are stored as required for use by the Data Capture exit routine or the Asynchronous Data Capture. Because the amount of storage required can be significant for update functions like a cascade delete, a data space is acquired for each dependent region that uses the exit routine. The attributes of the data space vary for online and batch-dependent regions, as illustrated in the following table.

Table 7. Data space characteristics (Data Capture exit routine and Asynchronous Data Capture)
Attribute	Online Dependent Region	Batch Dependent Region
Number of data spaces	1 per dependent region	1
Data space name	SYSDFS01	@SYSDFS1
Storage key	Key 7, not fetch protected to allow access from dependent region in key 8	Key 8
Storage size	By region controller	By region controller. Default size used if space requested violates total size of key 8 data spaces.
Storage obtained	During region initialization	During region initialization if exit routines are defined
Storage owned	By region controller TCB	By batch TCB
Added to access list	Dependent region address space, for access by program controller TCB in message regions. Control regions SAS address space for access by DL/I in an IMS DB/DC system when data capture is required. DEDB capture runs under program controller TCB.	Batch TCB
Deleted from access list	Dependent region always accessed. Deleted from control region SAS access list during thread termination if added to access list by data capture.	Not deleted
Data space cleared	During normal thread termination for message regions if data space storage was referenced.	Not cleared
Data space deleted	At region termination.	At z/OS job termination

You can control the use of data spaces with the SMF IEFUSI Step Initiation exit routine for key 8 batch regions. This exit routine determines the number and size of the data space available for key 8. If you have batch application programs that call the Data Capture exit routine, the data space specified for key 8 must be large enough to accommodate the data space requirements of data capture.

Storage failure

The two types of storage failure for data capture are:

Data space not obtained. This type of error occurs in batch regions when a data space is not specified for each region. Online dependent regions can always obtain data space.
Insufficient storage in the data space. In online dependent regions, storage space is specified by the region controller. Some database functions, such as cascade delete, require more than the space allocated for successful completion. Batch dependent regions can be limited in data space size. You must specify a data space large enough for data capture to complete successfully.

Either type of storage failure terminates the region with a U814 abend.

Data security and integrity

The Data Capture exit routine is an extension of the application program with the same capabilities as the application program; the exit routine and the application have equal authorization and limitations. IMS and Db2 for z/OS resources that the exit routine uses must be authorized in the IMS PSB or DB2® PLAN for the application program. This behavior ensures that the application program can access any IMS or Db2 for z/OS data that is available to the exit routine.

The data and the exit routine operate in unprotected, key-8 storage. The exit routine is able to modify data or control blocks that can affect the successful operation of the application program. The data passed to the exit routine is the physical segment data. With PSB field sensitivity, this data might include data that is unavailable to the application.