The Event Replicator Server gives control to its subscription user exit after a record to be replicated has been processed according to the applicable subscription definitions. For each combination of subscription and file, the user exit to be called can be specified using the SFSEXIT parameter.
The same or different user exits can be specified for different subscriptions or files. If no user exit is specified, each replicated record is delivered according to the other parameters specified in the subscription, in particular the formats used for decompression.
The output parameters of the exit are preset such that if the exit does not modify them, Event Replicator Server processing is the same as if the user exit was not specified. A sample subscription record user exit, UEXREPT1, is provided in the source library that accompanies the Event Replicator for Adabas.
 |
Warning: Sample user exits and programs are not supported under any maintenance contract agreement. |
The subscription user exit can:
Filter the selected record (suppressing its shipment to the target application), or
Modify the record (for example, remove, insert, or transform data in the record).
The remainder of this document covers the following topics:
The subscription user exit is called:
During Event Replicator Server session start,
For every replicated data record that matches a subscription and file combination for which the exit has been specified, and
During normal Event Replicator Server session termination.
When called during Event Replicator Server session start, the exit may acquire resources that it needs throughout the session and perform other one-time operations. When called during Event Replicator Server session termination, the exit should release the resources acquired during the session.
When called for a data record that is being replicated, the exit is given information about the record and the surrounding transaction, including the following:
The subscription name (URBTSNAM) and version indicator (URBTUSRV).
The transaction sequence number within the subscription (URBTTSNR).
The 28-byte communication ID of the user who performed the transaction (URBTGUID).
The originating database ID (URBTDBID).
The file number and ISN of the record (URBRFNR and URBRISN).
The record sequence number within the transaction (URBRRSNR).
The type of update operation (insert, update, delete) on the record (URBRTYP).
If present, the before image of the record (URBDDATA/URBDLEND pointed to by URBPABI), decompressed according to the corresponding format defined in the subscription (SFBBI/SGFORMATBI or SFBKEY/SGFORMATKEY parameters).
The type (data storage or primary key) of before image (URBDTYP), if a before image is present. The before image consists only of the primary key of the record if a primary key has been defined for the file and the key was updated or deleted.
If present, the after image of the record (URBDDATA/URBDLEND pointed to by URBPAAI), decompressed according to the corresponding format defined in the subscription (SFBAI/SGFORMATAI parameter).
The user exit may do any of the following with the data record passed to it:
Filter the record (i.e., suppress its shipment to the destination(s) defined in the subscription). This is done by setting URBXRETC to URBXRFLT.
Modify the record contents in place. The before image of the record is located at URBD.URBDDATA off the address given in URBPABI. The after image is located at URBD.URBDDATA off the address given in URBPAAI.
Make either record image shorter, by setting the new length in URBD.URBDLEND. The exit must not make a record image longer. To send longer data to the destination(s) than is extracted during decompression, extra space can be provided by adding appropriate format elements (e.g., '20X') to the formats used for decompression.
Suppress the delivery of the before and/or after image while keeping the delivery of the control information for the record (URBR) intact. To suppress the delivery of either record image, set the associated record length in URBDLEND to zero.
Set up to 8 bytes of error code information in the URBXERRC field. If error code information is set, no record data (URBD) will be delivered to the destination(s) for this record.
The exit should not set any response data in other fields of the URB* control blocks, as such data will be ignored and lost.
The call to the user exit is made using the standard mainframe subroutine linkage. At entry to the user exit, the general registers are set as follows:
Register 1 contains the address of the URBP parameter address list.
Register 13 contains the address of a standard 72-byte register save area.
Register 14 contains the return address.
Register 15 contains the user exit entry point address.
The exit is called in AMODE 31 and primary address space mode.
On exit, the contents of register 15 are immaterial. The exit sets fields in the URBX and data in the URBDs to give instructions to the Event Replicator Server regarding how to further process the input record.
The exit must restore registers 2-13 to their previous values prior to returning control to the Event Replicator Server. It must return control in the same PSW key, program state and mask, and address space control mode active on entry.
The diagram below provides an overview of the subscription user exit input parameters.
MACRO
URBP
URBP DSECT
*---------------------------------------------------------------------*
* URBP -- Subscription user exit parameter list *
* *
* DSECT URBP is used by the Event Replicator for Adabas. *
* *
* DSECT URBP describes the parameter address list passed *
* to the Reptor subscription user exit. *
*---------------------------------------------------------------------*
* *
* During Reptor session start, the user exit is called once *
* with the Initialize function. *
* *
* While the Reptor is running, the exit is called with the *
* Process-record function for every record that is being *
* replicated. The exit may filter the record (suppress its *
* shipment to the destination(s)) or modify its contents. *
* *
* During Reptor shutdown (normal termination only), the exit *
* is called once with the Terminate function. *
* *
*---------------------------------------------------------------------*
* *
* The subscription user exit is called using a *
* standard BALR 14,15 interface, as follows: *
* *
* On entry, *
* R1 -> URBP parameter address list *
* R13 -> Standard 72-byte register save area *
* R14 -> Return point *
* R15 -> User exit entry point *
* *
* On exit, *
* information may be returned in the first parameter *
* *
*---------------------------------------------------------------------*
URBPURBX DS A Addr of URBX parameter block
*
* Only for the Process-record function (URBXFUNC=URBXFREC):
*
URBPURBT DS A Addr of URBT
URBPURBR DS A Addr of URBR
URBPABI DS A Addr of URBD of before image
* Zero if no before image
URBPAAI DS A Addr of URBD of after image
* Zero if no after image
*
* The user exit may change the before/after image record contents
* at URBD.URBDDATA and may decrease their lengths at URBD.URBDLEND.
* However, it must not increase the record data lengths. If the
* exit sets a length to zero, the corresponding record image will
* not be shipped to the destination(s).
*
* The last supplied address in the URBP parameter address list is
* marked with the high bit set.
*
URBPL EQU *-URBP DSECT length
MEND
MACRO
URBX
URBX DSECT
*---------------------------------------------------------------------*
* URBX -- Subscription user exit parameter block *
* *
* DSECT URBX is used by the Event Replicator for Adabas. *
* *
* DSECT URBX describes the first parameter passed to the *
* Reptor subscription user exit. *
*---------------------------------------------------------------------*
URBXEYE DS CL4 (in) URBX eye-catcher 'URBX'
URBXLEN DS F (in) Length of URBX
*
URBXVERS DS CL2 (in) Version indicator for exit parameters:
URBXVER1 EQU C'01' First version
* Future releases may allow a new layout
* of the subscription user exit parameters
* (URBP and URBX DSECTs). In this case
* URBXVERS will be set to a different
* value.
URBXVERH DS CL2 (in) Version indicator for URB* DSECTs,
* corresponding to URBHVERS
*
URBXUSER DS A (in/out) Word for use by user exit:
* Initially (Initialize function), zero
* Then, value set by exit in previous call
*
URBXFUNC DS X (in) Function code:
URBXFINI EQU X'01' Initialize
URBXFTRM EQU X'02' Terminate
URBXFREC EQU X'03' Process record
*
URBXRETC DS X (out) Return code:
URBXRSHP EQU X'00' Ship record (default setting)
URBXRFLT EQU X'01' Filter record (other nonzero
* values cause filtering, too)
*
URBXJNAM DS CL8 (in) Reptor job name
*
URBXERRC DS CL8 (out) Other error code information:
* Passed to destination in URBR.URBRERRC
* (default setting is blanks)
*
DS XL60 Reserved area
DS 0D
URBXL EQU *-URBX DSECT length
MEND
Using your subscription user exit and the SFILE SFREPLICATEDELETE=UPDATE parameter setting, you can control how physical delete transactions are handled on your target database.
If a subscription definition's SFILE includes the specification SFREPLICATEDELETE=UPDATE and an input record for the DBID/file is for a delete, the before and after images of the input record are passed to your subscription user exit. This allows your subscription user exit to determine the processing of replicated physical delete transactions on your target database. Your subscription user exit can decide if the physical delete transaction should be:
physically deleted from your target database
converted to an update
ignored and not sent at all.
When a physical delete transaction is detected on the replicated database, an after image URBD is created along with a before image URBD and both are sent to the subscription user exit. The after image is only created if the SFREPLICATEDELETE=UPDATE setting is specified and if the before image is a copy of data storage (no key image is specified). Subscription definitions with SFREPLICATEDELETE=UPDATE should not have a primary key defined to the file. If a primary key is not defined, then the before image of the URBD will be a copy of data storage. If a key image is received when SFREPLICATEDELETE=UPDATE is specified, no after image is created and the subscription user exit can only request that the physical delete transaction be processed as a physical delete or ignored (it cannot be converted to an update).
Note:
If SAGTARG is specified as the destination class of the
subscription, you can still flag a field as being the primary key in the GFFT
data. This is because filtering is done before the subscription user exit is
called, so the SAGTARG filtering will be performed on the physical delete
transaction and not on an update transaction created from the delete.
When SFREPLICATEDELETE=UPDATE is specified, your subscription user exit must indicate how delete transactions should be handled:
If you decide that you want physical delete transactions to be physically deleted from your target database, your subscription user exit must produce a return code indicating this. Event Replicator for Adabas will then release the after image URBDs and the delete transactions will be processed as normal physical deletes.
If you decide that you want physical delete transactions to be converted to update transactions, your subscription user exit is responsible for changing fields in the after image URBD and returning a response code indicating that the deletes should be sent as updates.
If you decide that you want physical delete transactions to be ignored (not sent), your subscription user exit must produce a return code indicating this. Event Replicator for Adabas will then release the after image URBDs and perform no further processing for the physical delete transaction.