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


Chapter 9 Using Data Object Broker User Exits : Sample Template and Application

Sample Template and Application
Template
The USRX0001 member in the ASM data set contains a template for creating Data Object Broker user exits.
Application
The USRX0000 member in the ASM data set contains a sample application illustrating the use of the user exits feature. The USERMODB member in the JCL data set contains JCL to install this sample application. The sample application implements all the user exits with the exception of the REDOLOG-2 Exit.
The application captures all the intent lists containing updates to a specified table and outputs them to a print file.
This sample implements four user parameters as follows:
 
The first four characters of the DDNAME to be used for the output data sets. No default; if ZDDNAME is not present, the exits are disabled.
The maximum number of intent‑list entries matching the selection criteria before a checkpoint is forced. Must be a number between 5 and 9999. Default: 100.
The name of the table to be used for selection criteria. Must be a valid table name. Default: spaces, so no intents are captured.
Modification of these values except for the table name is not permitted after initialization. Use of the MODIFY DOBNAME,PARM=userparm=value is not permitted.
The sample implements two user commands as follows:
 
After the next intent list is passed through the REDOLOG-1 user exit, a checkpoint is forced, the current output data set is closed, and a new one is allocated and opened by the checkpoint exits.
After the next intent list is passed through the REDOLOG-1 user exit, the name of the table to be monitored is changed, a checkpoint is forced, the current output data set is closed, and a new one is allocated and opened by the checkpoint exits. If no value is specified, the table name is reset to spaces.
The DDNAME used for the output data set is XXXXnnnn where XXXX is the value specified by the ZDDNAME parameter and nnnn is a number starting at 0001 and incremented by 1 each time a data set is closed and reallocated.
Sample Exit Brief Descriptions
Initialization Exit
The Initialization exit (USRX0000) obtains a working storage area (mapped by WORKSPAC DSECT) for use by all the other supplied exits, initializes it, and stores its address in field UXSPACE@ of the User Exit Parameter list. It then sets up the addresses of all the other supplied user exits in the User Exit Parameter list, sets default values in the working storage area and attaches a subtask to perform the OPEN, CLOSE, and OFFLOAD functions (refer to SYSOTCB Subtask).
Cache Complete Exit
The Cache Complete exit checks to see if an offload of captured intents is in progress. If it is, Cache Complete waits for the SYSOTCB subtask to signal that it is complete. Then, if a spin of the output data set is required, it posts the SYSOTCB subtask to close the current output data set, and then it posts the SYSOTCB subtask again to allocate and open a new output data set.
Checkpoint Start Exit
The Checkpoint Start exit checks to see if any captured intents are to be off-loaded. If they are, it posts the SYSOTCB task to start the offload process and sets a flag to indicate to the Cache Complete exit that an offload is in progress.
Command Exit
The Command exit implements the ZSPIN and ZTABLE commands as detailed in Template.
File Management Checkpoint Exit
The File Management Checkpoint exit swaps the intent‑list collection buffers, if required, and sets pointers for the checkpoint user exits to offload captured intent lists. Checks are made to see if any activity such as a spin is required and if so, sets flags to control the checkpoint user exits accordingly.
Initialization Complete Exit
This exit checks that the value supplied for ZSTORE does not exceed the number of transactions per checkpoint. If it does, it is reset to the number of transactions per checkpoint. Storage is obtained for two buffers capable of holding intents for the number of intents specified by ZSTORE and various pointers are initialized in the common working storage.
Open Exit
The Open user exit checks to see if there is a value for ZDDNAME. If none is supplied, all the exits are disabled by turning on the high‑order bits in their addresses in the User Exit Parameter list. If a value is supplied, the SYSOTCB subtask is posted to open the first output data set.
Parameter Exit
The Parameter user exit implements the user parameters described in Template.
Recovery Exit
The Recovery user exit captures any intents matching the selection criteria in one of the buffers obtained by the Initialization Complete exit and marks them as recovered intents. A check is made to stop these intents from overflowing the available storage. This should happen only if the parameter values were changed since the Data Object Broker shut down abnormally (for a normal shut down no intents would be recovered) or if monitoring is being done on initialization of a different table name than at the time of the failure.
Redolog-1 Exit
The REDOLOG-1 user exits captures intents matching the selection criteria in one of the buffers obtained by the Initialization Complete exit and marks them as normal intents. If a checkpoint is required due to the current buffer being full or any other activity such as a spin being requested, it schedules this by setting the appropriate return code.
Termination Exit
The Termination Exit posts the SYSOTCB subtask to shut down, and when this is complete, it detaches SYSOTCB.
SYSOTCB Subtask
Because of the restriction of the operating system that data sets must be opened and closed by the same task, a subtask is attached by the Initialization exit. It also performs the formatting and writing of any captured intent lists to the output data set, so that this process can overlap the writing of Cache data set by CHPTTASK.
The subtask initializes and then waits for one of the user exits to post it to perform a function. When the function is complete, the subtask posts an ECB to release the waiting user exit. The following functions are implemented:
 
Sample Output
The sample output shows an intent list captured from an application that clears parameter set P1,P2,P3,P4 from table EXIT_SAMPLE and then inserts a number of rows into this table. This table is defined as shown in Sample Table Definition. The implemented user parameters are set as follows:

 
ZDDNAME=SAMP
ZTABLE=EXIT_SAMPLE
ZSTORE=9999
ZCLASS=*

 
Sample Job Log

 
09.23.07 JOB08272 ---- THURSDAY, 21 JUN 2007 ----
09.23.07 JOB08272 IRR010I USERID USER2 IS ASSIGNED TO THIS JOB.
09.23.07 JOB08272 ICH70001I USER2 LAST ACCESS AT 09:21:32 ON THURSDAY, JUNE 21, 2007
09.23.07 JOB08272 $HASP373 DC50ADOB STARTED - INIT 17 - CLASS D - SYS STAR
09.23.08 JOB08272 - --TIMINGS (MINS.)-- -----PAGING COUNTS----
09.23.08 JOB08272 -STEPNAME PROCSTEP RC EXCP CONN TCB SRB CLOCK SERV WORKLOAD PAGE SWAP VIO SWAPS
09.23.08 JOB08272 -DELDUMP 00 49 25 .00 .00 .0 260 BATCH 0 0 0 0
09.23.08 JOB08272 -PARMS 00 52 26 .00 .00 .0 154 BATCH 0 0 0 0
09.23.09 JOB08272 -REDOPRT 00 72 44 .00 .00 .0 591 BATCH 0 0 0 0
09.23.09 JOB08272 USER EXIT SUBTASK ATTACHED
09.23.09 JOB08272 S6BKS312I USER EXITS HAVE BEEN ACTIVATED
09.23.09 JOB08272 S6BKS010I-DCA DATA OBJECT BROKER VERSION 5.0.123.
09.23.09 JOB08272 S6BKS011I-DCA TASK NAME DC50ADOB ASID 0158
09.23.09 JOB08272 S6BKS012I-DCA APPLID S6DCDOBA NODENAME S6DCDOBA
09.23.09 JOB08272 S6BKS030I-DCA SYSTEM NON-SWAPPABLE
09.23.10 JOB08272 S6BDB067I-DCA RESIDENT PAGES REQUESTED = 080000, AVAILABLE = 080000
09.23.10 JOB08272 S6BKQ001I-DCA RTUQTASK INITIALIZATION COMPLETED SUCCESSFULLY
09.23.11 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.REDOLOG
09.23.11 JOB08272 S6BDB035I-DCA REDOLOG CI SIZE = 04096
09.23.11 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.CACHE1
09.23.11 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.CACHE2
09.23.11 JOB08272 S6BKA033I-DCA APPL INITIALIZATION OK (COPY 01)
09.23.11 JOB08272 S6BDB092I-DCA ACTIVATING SEGMENT=000 NAME=CRA.SEG0
09.23.11 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG0.PAGE1
09.23.11 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG0.PAGE2
09.23.12 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG0.PAGE3
09.23.12 JOB08272 S6BDB092I-DCA ACTIVATING SEGMENT=001 NAME=CRA.SEG1
09.23.12 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG1.PAGE1
09.23.12 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG1.PAGE2
09.23.13 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG1.PAGE3
09.23.13 JOB08272 S6BDB092I-DCA ACTIVATING SEGMENT=002 NAME=CRA.SEG2
09.23.13 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG2.PAGE1
09.23.13 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG2.PAGE2
09.23.13 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG2.PAGE3
09.23.14 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG2.PAGE4
09.23.14 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG2.PAGE5
09.23.15 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG2.PAGE6
09.23.15 JOB08272 S6BDB092I-DCA ACTIVATING SEGMENT=003 NAME=CRA.SEG3
09.23.15 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG3.PAGE1
09.23.15 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG3.PAGE2
09.23.16 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.SEG3.PAGE3
09.23.16 JOB08272 S6BDB092I-DCA ACTIVATING SEGMENT=099 NAME=CRA.S99
09.23.16 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.S99.PAGE1
09.23.16 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.S99.PAGE2
09.23.17 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.S99.PAGE3
09.23.17 JOB08272 S6BDB002I-DCA FILE INITIALIZATION OK
09.23.17 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.JRNL1
09.23.18 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.JRNL2
09.23.18 JOB08272 S6BKX068W-DCA CHTRANLIMIT SET BASED ON SPACE AVAILABLE IN THE REDOLOG DATA SE
09.23.18 JOB08272 S6BKX057W-DCA PAGE LIMIT REDUCED - EXCEEDS 15% OF RESIDENT PAGES
09.23.18 JOB08272 S6BKX060I-DCA CHECKPOINT MAXIMUM PAGES = 012000, TRANSACTIONS = 008999
09.23.18 JOB08272 VALUE OF ZSTORE RESET TO CHTRANLIMIT VALUE
09.23.18 JOB08272 S6BKS090I-DCA REDO SUBTASK DETACH (STAGE 2)
09.23.18 JOB08272 S6BKP001I-DCA OPER INITIALIZATION COMPLETED
09.23.18 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.RESOURCE
09.23.18 JOB08272 S6BDB090I-DCA OPEN S6B.DC.R50.CRA.REDOLOG.PENDING
09.23.22 JOB08272 S6BCM900I OPENPORT FOR COMMUNICATION IDENTIFIER "S6DCDOBA" HAS SUCCEEDED
09.23.22 JOB08272 S6BKC035L-DCA INITIATING PEER CONNECTION TO S6DCDOBB:S6DCDOBB
09.23.22 JOB08272 S6BRA008I TCP/IP RELAY started; Accepting connections on socket port 10021
09.23.22 JOB08272 S6BRA013E Connection to node "S6DCDOBB" refused
09.23.23 JOB08272 S6BKS050I-DCA SYSTEM READY 2007JUN21 09:23

 
Sample Recovered Intents
This is an output data set showing recovered intents captured by the Recovery user exit after the Data Object Broker was deliberately aborted.
Recovered Intent

 
00000000 00580001 000002E4 40000001 804ED200 000002E4 C5E7C9E3 6DE2C1D4 D7D3C540 *.°.....U ...Ã+K....UEXIT_SAMPLE *
00000020 40404040 E3C4E240 00400000 00000000 00000000 00000000 00000000 00000000 * TDS . ......................*
00000040 00000000 00000000 00000000 02D7F102 D7F202D7 F302D7F4 F000 *.............P1.P2.P3.P40. *

 
Recovered Intent

 
00000000 0001D900 0002EB00 020042C9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 D7F202D7 *..R...õ...¡I.EXIT_SAMPLE.P1.P2.P*
00000020 F302D7F4 00290101 24E3C8C9 E240C9E2 40C140D9 D6E640D6 C640C4C1 E3C140C9 *3.P4.‰..„THIS IS A ROW OF DATA I*
00000040 D540E3C8 C9E240E3 C1C240D3 C5009DC9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 *N THIS TAB LE.ÎI.EXIT_SAMPLE.P1.*
00000060 D7F202D7 F302D7F4 00840102 7FE3C8C9 E240C9E2 40E3C8C5 40E2C5C3 D6D5C440 *P2.P3.P4.d.."THIS IS THE SECOND *
00000080 D9D6E640 D6C640C4 C1E3C140 C9D540E3 C8C9E240 E3C1C2D3 C54B40C9 E340C9E2 *ROW OF DATA IN THIS TABLE. IT IS*
000000A0 40D7C1C4 C4C5C440 E6C9E3C8 40E3C8C5 40C3C8C1 D9C1C3E3 C5D940E7 40E3D640 * PADDED WITH THE CHARACTER X TO *
000000C0 E2C8D6E6 40C140E3 E6D640C2 E8E3C540 D3C5D5C7 E3C840C6 C9C5D3C4 4BE7E7E7 *SHOW A TWO BYTE LENGTH FIELD.XXX*
000000E0 E7E7E7E7 E7E7E7E7 E7E7E7E7 *XXXXXXXXXXXX *

 
Recovered Intent

 
00000000 0001D900 0002F000 020042C9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 D7F202D7 *..R...0...¡I.EXIT_SAMPLE.P1.P2.P*
00000020 F302D7F4 00290103 24E3C8C9 E240C9E2 40C140D9 D6E640D6 C640C4C1 E3C140C9 *3.P4.‰..„THIS IS A ROW OF DATA I*
00000040 D540E3C8 C9E240E3 C1C240D3 C5009DC9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 *N THIS TAB LE.ÎI.EXIT_SAMPLE.P1.*
00000060 D7F202D7 F302D7F4 00840104 7FE3C8C9 E240C9E2 40E3C8C5 40E2C5C3 D6D5C440 *P2.P3.P4.d.."THIS IS THE SECOND *
00000080 D9D6E640 D6C640C4 C1E3C140 C9D540E3 C8C9E240 E3C1C2D3 C54B40C9 E340C9E2 *ROW OF DATA IN THIS TABLE. IT IS*
000000A0 40D7C1C4 C4C5C440 E6C9E3C8 40E3C8C5 40C3C8C1 D9C1C3E3 C5D940E7 40E3D640 * PADDED WITH THE CHARACTER X TO *
000000C0 E2C8D6E6 40C140E3 E6D640C2 E8E3C540 D3C5D5C7 E3C840C6 C9C5D3C4 4BE7E7E7 *SHOW A TWO BYTE LENGTH FIELD.XXX*
000000E0 E7E7E7E7 E7E7E7E7 E7E7E7E7 *XXXXXXXXXXXX *

 
This is followed by similar entries for other inserts.
Sample Normal Intents
This is an output data set showing normal intents captured by the Redolog-1 user exit.
Normal Intent

 
00000000 00580001 000002E4 40000001 804ED200 000002E4 C5E7C9E3 6DE2C1D4 D7D3C540 *.°.....U ...Ã+K....UEXIT_SAMPLE *
00000020 40404040 E3C4E240 00400000 00000000 00000000 00000000 00000000 00000000 * TDS . ......................*
00000040 00000000 00000000 00000000 02D7F102 D7F202D7 F302D7F4 F000 *.............P1.P2.P3.P40. *

 
Normal Intent

 
00000000 0001D900 0002EB00 020042C9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 D7F202D7 *..R...õ...¡I.EXIT_SAMPLE.P1.P2.P*
00000020 F302D7F4 00290101 24E3C8C9 E240C9E2 40C140D9 D6E640D6 C640C4C1 E3C140C9 *3.P4.‰..„THIS IS A ROW OF DATA I*
00000040 D540E3C8 C9E240E3 C1C240D3 C5009DC9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 *N THIS TAB LE.ÎI.EXIT_SAMPLE.P1.*
00000060 D7F202D7 F302D7F4 00840102 7FE3C8C9 E240C9E2 40E3C8C5 40E2C5C3 D6D5C440 *P2.P3.P4.d.."THIS IS THE SECOND *
00000080 D9D6E640 D6C640C4 C1E3C140 C9D540E3 C8C9E240 E3C1C2D3 C54B40C9 E340C9E2 *ROW OF DATA IN THIS TABLE. IT IS*
000000A0 40D7C1C4 C4C5C440 E6C9E3C8 40E3C8C5 40C3C8C1 D9C1C3E3 C5D940E7 40E3D640 * PADDED WITH THE CHARACTER X TO *
000000C0 E2C8D6E6 40C140E3 E6D640C2 E8E3C540 D3C5D5C7 E3C840C6 C9C5D3C4 4BE7E7E7 *SHOW A TWO BYTE LENGTH FIELD.XXX*
000000E0 E7E7E7E7 E7E7E7E7 E7E7E7E7 *XXXXXXXXXXXX *

 
Normal Intent

 
00000000 0001D900 0002F000 020042C9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 D7F202D7 *..R...0...¡I.EXIT_SAMPLE.P1.P2.P*
00000020 F302D7F4 00290103 24E3C8C9 E240C9E2 40C140D9 D6E640D6 C640C4C1 E3C140C9 *3.P4.‰..„THIS IS A ROW OF DATA I*
00000040 D540E3C8 C9E240E3 C1C240D3 C5009DC9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 *N THIS TAB LE.ÎI.EXIT_SAMPLE.P1.*
00000060 D7F202D7 F302D7F4 00840104 7FE3C8C9 E240C9E2 40E3C8C5 40E2C5C3 D6D5C440 *P2.P3.P4.d.."THIS IS THE SECOND *
00000080 D9D6E640 D6C640C4 C1E3C140 C9D540E3 C8C9E240 E3C1C2D3 C54B40C9 E340C9E2 *ROW OF DATA IN THIS TABLE. IT IS*
000000A0 40D7C1C4 C4C5C440 E6C9E3C8 40E3C8C5 40C3C8C1 D9C1C3E3 C5D940E7 40E3D640 * PADDED WITH THE CHARACTER X TO *
000000C0 E2C8D6E6 40C140E3 E6D640C2 E8E3C540 D3C5D5C7 E3C840C6 C9C5D3C4 4BE7E7E7 *SHOW A TWO BYTE LENGTH FIELD.XXX*
000000E0 E7E7E7E7 E7E7E7E7 E7E7E7E7 *XXXXXXXXXXXX *

 
Normal Intent

 
00000000 0001D900 0002F500 020042C9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 D7F202D7 *..R...5...¡I.EXIT_SAMPLE.P1.P2.P*
00000020 F302D7F4 00290105 24E3C8C9 E240C9E2 40C140D9 D6E640D6 C640C4C1 E3C140C9 *3.P4.‰..„THIS IS A ROW OF DATA I*
00000040 D540E3C8 C9E240E3 C1C240D3 C5009DC9 0BC5E7C9 E36DE2C1 D4D7D3C5 02D7F102 *N THIS TAB LE.ÎI.EXIT_SAMPLE.P1.*
00000060 D7F202D7 F302D7F4 00840106 7FE3C8C9 E240C9E2 40E3C8C5 40E2C5C3 D6D5C440 *P2.P3.P4.d.."THIS IS THE SECOND *
00000080 D9D6E640 D6C640C4 C1E3C140 C9D540E3 C8C9E240 E3C1C2D3 C54B40C9 E340C9E2 *ROW OF DATA IN THIS TABLE. IT IS*
000000A0 40D7C1C4 C4C5C440 E6C9E3C8 40E3C8C5 40C3C8C1 D9C1C3E3 C5D940E7 40E3D640 * PADDED WITH THE CHARACTER X TO *
000000C0 E2C8D6E6 40C140E3 E6D640C2 E8E3C540 D3C5D5C7 E3C840C6 C9C5D3C4 4BE7E7E7 *SHOW A TWO BYTE LENGTH FIELD.XXX*
000000E0 E7E7E7E7 E7E7E7E7 E7E7E7E7 *XXXXXXXXXXXX *

 
This is followed by similar entries for other inserts.

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