Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 9 Using Data Object Broker User Exits : User Exits

User Exits
Initialization Exit
An Initialization exit called USRX0000 must be present, to set the pointers for all user exits that are to be called.The Initialization exit does this by turning off the high-order bit for the address for that user exit.
If USRX0000 is present in the load library and the Data Object Broker Parameter USEREXIT is set to Y, then the exits are initialized.
The Data Object Broker terminates with an error message if USRX0000 is present in the load library and the Data Object Broker Parameter USEREXIT is set to N, or USRX0000 is not present in the load library and the Data Object Broker Parameter USEREXIT is set to Y.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Cache Complete Exit
The Cache Complete exit is called after the last Cache buffer has been built and before the write request is issued. You can use this exit to ensure that all intent list user processing is complete. Invoking the exit routine before the last Cache buffer is written ensures that the transactions for the checkpoint are recovered in the event of an abnormal termination of the Data Object Broker.
For important information about event timing, refer to the Warning.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Checkpoint Start Exit
Pending page image updates are written serially to one of the Cache data sets before the asynchronous processing of the page image data sets and journals. Before the Cache write is initiated, the Checkpoint Start exit is invoked.
If the custom processing collects intents during redolog processing with the intention of processing the intent lists at checkpoint time, this is the time to initiate the processing.
There is a window for a possible timing error if intents are not done their required processing before the last Cache buffer is processed. If a Data Object Broker termination occurs during this window, user exit processing is passed some intents twice. You must ensure that recovery intents are processed once and only once.
This happens because, during restart recovery, each recovered intent list is presented to the Recovery exit. If the Checkpoint Start or Cache Complete exit recorded any captured intents and the Data Object Broker terminates before the “last Cache” I/O is complete, upon restart these intents are passed to the Recovery exit for processing.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
 
Command Exit
If your application requires dynamic external influence on the processing, the exits must support user operator commands. To support user commands, the optional Command exit must be enabled. If there are no user commands, the Command user exit should remain inactivated (that is, USREXTPL.UXCMND@ = 0). If present, the Command exit is called when a command received from the operator starts with the character “Z”. The exit is responsible for producing any log notification that results from user commands, such as return code 0 or 4.
A user command must be 5 to 14 alphanumeric characters long starting with a “Z”. The format of the command should be the same as for other keyword Data Object Broker operator commands with a value, such as “ZUSER=value”, or without a value, such as “ZSPIN”.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
The command is ignored and Data Object Broker processing continues.
The command is ignored and Data Object Broker processing continues.
File Management Checkpoint Exit
A checkpoint can be triggered based on volume of processing, a timed event, an operator command, or via the user Redolog-1 and Redolog-2 exits. When preparing for a checkpoint, the File Management routine switches the Cache buffer. When this Cache switching is about to occur, the File Management Checkpoint user exit is invoked.
If the user exits are collecting intents within a checkpoint boundary using alternate buffers, this exit would be the appropriate place to switch to the alternate buffer.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Initialization Complete Exit
After completing phase-1 initialization, the Data Object Broker calls the Initialization Complete exit. During Phase 1, the Data Object Broker obtains the majority of the space it requires, allocates the control data sets, and makes any parameter adjustments necessary, such as the values of checkpoint, transaction, and page limits. The Initialization Complete exit provides the best opportunity for the calculation and acquisition of user storage. The UXSPACE@ field in the USREXTPL is available to store the start address of the user storage block. This is also the time to perform sanity checks on the user parameters that are processed.
If properly managed, it is more efficient to obtain all the required user storage in a single block during initialization rather than repeatedly obtaining and releasing storage during the lifetime of the Data Object Broker.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Open Exit
The Open exit is called at the end of the File Management third‑stage initialization. At this point, the TIBCO Object Service Broker data sets required to start processing are allocated and opened. The Open exit provides the opportunity to open the data sets you require.
For important information about opening and closing data sets, refer to the Warning.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Parameter Exit
If your application requires external influence, you can accommodate this with user runtime parameters. To support user parameters, the optional Parameter exit must be enabled. If there are no user parameters, the Parameter user exit should be left inactivated (that is, USREXTPL.UXPARM@ = 0). The Data Object Broker invokes parameter processing during initialization and when a “PARAMETER=” operator command is received. When the Data Object Broker encounters a parameter keyword starting with the character “Z”, it invokes the user parameter exit if UXPARM@ is a positive non-zero value. The exit routine is responsible for doing any user-parameter reporting required.
A user parameter must be 5 to 16 alphanumeric characters long starting with a “Z”. The format of the parameter should be the same as for other Data Object Broker runtime parameters with a value, for example, “ZUSER=value”.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Invalid user parameter
If the exit routine is called during Data Object Broker initialization, initialization fails with abend U049.
If the exit routine is called as the result of a PARAMETER= command, the parameter is ignored.
Unrecognized Parameter
If the exit routine is called during Data Object Brokernitialization, initialization fails with abend U049.
If the exit routine is called as the result of a PARAMETER= command, the parameter is ignored and Data Object Broker processing continues.
Recovery Exit
During Data Object Broker start-up processing after an abnormal termination of the Data Object Broker, the intent lists saved on the redolog that have not reached checkpoint are reapplied. After each “recovery” intent has been processed, control passes to the Recovery exit.
Refer to Redolog Entries for details of the layout of the redolog entries.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Redolog-1 Exit
After an intent list has been validated by the Data Object Broker, it is written to the redolog. TIBCO Object Service Broker uses an asynchronous write so that I/O processing of the primary and duplex redologs can overlap. TIBCO Object Service Broker calls the Redolog-1 exit after issuing the asynchronous write request.
When the intent is written to the redolog, it could be split into segments depending on the space available in the VSAM Control Interval. In this case, TIBCO Object Service Broker calls the Redolog-1 exit after issuing the asynchronous write request to the redolog for the first block.
The Redolog-1 and Redolog-2 exits are designed to work in series to provide a processing window that overlaps the I/O processing of the redolog. Processing requirements in Redolog-2 are dependent on the processing initiated in Redolog-1.
Refer to Redolog Entries for details of the layout of the redolog entries.
If the Redolog-1 exit is performing selection on the intent list and the current intent is not selected, there can be performance advantages if the Redolog-2 exit is bypassed. To disable the Redolog-2 exit, turn on the high‑order bit for its pointer in the general parameter list (UXREDO2@).
The processing at this point is on the TIBCO Object Service Broker critical path. Any additional processing causes degradation of commit turnaround time. Make sure your application takes this into account.
Registers
 
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Force checkpoint
Processing completed successfully and you must take a checkpoint as soon as possible.
Redolog-2 Exit
As stated under Redolog-1 Exit, the write request of the intent to the redolog is asynchronous. After the check to verify a successful write was satisfied, the Redolog-2 exit is called. If the intent is written over a number of redolog VSAM Control Intervals, TIBCO Object Service Broker calls the Redolog-2 exit only after successfully writing the last Control Interval.
The Redolog-1 and Redolog-2 exits are designed to work in series to provide a processing window that overlaps the I/O processing of the redolog. Processing requirements in Redolog-2 are dependent on the processing initiated in Redolog-1.
Refer to Redolog Entries for details of the layout of the redolog entries.
Registers
 
Calling Register
Return Codes
Upon return from the exit routine the contents of Register 15 determine further processing as follows:
 
Force checkpoint
Processing completed successfully and you must take a checkpoint as soon as possible.
Termination Exit
The Termination exit is called when the File Management and Checkpoint functions are done.
If the user exits have a data set open, this exit provides a point to close them cleanly. For important information about opening and closing data sets, refer to the Warning.
Registers
 
Calling Register
Return Codes
The return code for the Termination exit is ignored.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved