Table identification exit

The table identification exit allows you to reformat the source data, control how many times the exit is called for an operation, and for insert, update, and delete operations control which table mappings and/or subscriptions the change is associated with and the change operation.

Reformatting

The exit can modify the contents of one or more buffers that are passed to the exit but cannot change the size of the buffer that was passed to the exit. In the case of IMS variable length segments, the exit can change the length of a segment, but cannot extend the size of the I/O area to make it larger.

These restrictions mean that the exit is limited to the transformations that can be performed on the original buffer’s contents. Also, if the exit is called multiple times for an operation, the buffers contents from the previous call is passed to the exit, which may make development of the exit more complicated depending on the transformations that were performed in prior calls.

The table identification exit also has access to a set of alternative buffers, which the exit can signal should be used instead of one or more original source buffers. When this option is chosen the exit must identify the amount of data that is contained in these alternative buffers and the operation.

Access to the alternative buffers allows the exit to perform extensive reformatting operation without having to modify the contents of the original buffers that are passed to the exit. The ability to change the original operation to a different insert, update, or delete operation allows the exit to process source updates to record or segments that contain encoded data or repeating data that has been normalized since the physical replace operation may not represent the logical operations that were performed against multiple entities (relational tables) that exist within the physical record whose change was captured.

Call control

Typically, most deployments reference multiple objects (VSAM files or IMS DBD or segments) with varying levels of complexity.

Often, you need to define only a single relational table definition for an object that does not require any data transformation or special processing. In these cases, the exit can set the return code to zero indicating that Classic should process this change as if the exit was not involved.

Often, a source object contains multiple structures (redefines) and typically this requires the creation of multiple relational tables, one for each structure. Without the use of an exit, a view must be defined that contains the filtering logic that allows Classic to identify when the relational table is relevant. In these cases, the view is altered to data capture and included in the subscription instead of the relational table.

When a change is received for an object that has multiple views that are associated with it, Classic evaluates all views to determine which relational table mappings are relevant. Typically, only one view is relevant, so it is more efficient for the table identification exit to perform where qualification and identify the relevant relational table. This approach does not require the creation of views and is more efficient and typically the exit needs to be called only once per operation and will either return code value of 2 (that indicates that processing should continue for the specified table name) or a return code value of 1 that indicates processing is complete (which indicates that further processing is not required from this context).

When processing changes to a source object that contains encoded or repeating data, the exit may need to be called multiple times, each time returning a different alternative buffer and identifying the name of the relational table that matches the buffer that was returned. The exit can indicate that it should be called again (after processing completes for one or more alternative buffers by using a return code of 3 or return a value of 2 that indicates this is the last time that the exit needs to be called after processing completes for the alternative buffer, or that processing is complete and that no further processing is required for this operation by returning a value of 1.

When processing changes, the exit can also inspect the name of the object and return that no further processing is required by returning a value of 1.

Options for identifying the relevant relational tables and subscriptions

When the exit is called from a query processor or during a refresh operation the name of the relational table is static and cannot be changed by the exit. Likewise, the subscription name is “fixed” for a refresh and is not relevant when called from the query processor.

When processing inserts, update or delete operations and the exit returns a value of zero, then Classic uses the VSAM DSN or IMS DBD and SEGM name in the DBMS-specific information structure to determine which relational tables or views are relevant. The exit can change these names before returning control.

The ability of the exit to update the physical object name is primarily intended for use in an IMS environment where there are multiple versions of the same IMS DBD. This allows a single relational table to be defined as opposed to having to create separate relational table mappings for each version of the database.

In a VSAM environment, the exit can change the name of a VSAM file; however, change filtering is performed by the VSAM log reader, so only changes to files that contain a relational table that is referenced by the subscription are sent to the capture service. If there are multiple instances of a VSAM file with the same layout the view override capability should be used – see Reusing table mappings using view overrides for more details on how to use this feature.

When processing changes and the exit returns a value or 2 or 3, then the exit is responsible for updating the schema and table name parameters to identify the name of the relational table or view that is relevant for the change. The exit can also update the subscription name parameter to identify the relevant subscription.

Identification of the subscription name is only necessary in an IMS environment where multiple subscriptions reference the same relational table. If a subscription name is not returned, the change might be staged for multiple subscriptions that are associated with the change stream. In an IMS environment, multiple subscriptions can be services by a single change stream, while in a VSAM deployment each change stream is servicing a single subscription.

Additional information

The following subtopics provide more information that assists you in developing a table identification exit.