Clients can send requests to the Event Replicator Server by sending messages to an Event Replicator input queue.
An input message is composed of a combination of:
a message header defined by the URBH DSECT
one or more input elements defined by the URBI DSECT.
The following requests are defined:
Destination open and close
Initial-state processing
Prior-transaction processing.
Status inquiry on subscription
This document covers the following topics:
The input message starts with a message header defined by the URBH DSECT. Set the elements in the URBH DSECT as described in the following table. Set all other elements in the URBH DSECT to the default value of binary zeroes or blanks according to the element type.
| Element | Setting |
|---|---|
| URBHEYE | Set to ‘URBH’. This value may be specified in either EBCDIC or ASCII. If this field contains ‘URBH’ in ASCII, all character fields in the URBH and URBI(s) will be translated from ASCII to EBCDIC. |
| URBHLEN | Set to the length of the URBH DSECT. This length is given in variable URBHL. |
| URBHVERS | Set to ‘01’. |
| URBHBORD | Set to the binary value of one. On big-endian machines, this will have the value X’0001’. On little endian-machines, this will have the value X’0100’. If this field is contains X’0100’, all binary fields in the URBH and URBI(s) will be byte-swapped before being used by the Event Replicator Server. |
| URBHLENT | Set to the total message length. This includes the length of the URBH plus the length of each subsequent URBI. |
| URBHTIME | Optionally set this variable to the store clock time when the message was sent. The value in this variable within an input message is not referenced by the Event Replicator Server. |
| URBHNAME | Optionally set this variable to the name of the sender. The value in this variable within an input message is not referenced by the Event Replicator Server. |
A destination open or close request will open or close a destination from your application program. Multiple requests can be made using multiple URBIs following a URBH header. The status message (URBS) contains the result of processing.
For a destination open or close request, set the elements in the URBI DSECT as described in the following table. Values may be provided for only these fields. All unused binary fields must be set to zero and all unused character fields must be set to blanks.
| Element | Setting |
|---|---|
| URBIEYE | Set to ‘URBI’. |
| URBILEN | Set to URBIL. |
| URBILENH | Set to URBIL. |
| URBIRT | Set to 'OPND' to request that the destination be opened; set to 'CLSD' to request that the destination be closed. One of these settings is required. |
| URBIDNAM | Supply the definition name of the destination that should be opened or closed. This element is required. |
| URBIRNAM | Optionally supply a response destination name. |
| URBIRTOK | Optionally supply the eight-byte token that allows your client program to recognize different open or close destination requests. |
Status messages for a destination open or close request contain the following information:
| Status Element | Description |
|---|---|
| URBSRT | "OPND" appears if a destination was opened; "CLSD" appears if a destination was closed. |
This example requests a destination named BROUT2 be closed. Destination BROUT1 is used as the response destination. The following topics are included in this section.
The following application code requests that destination BROUT2 be closed:
rr=newMessage(bb.send_buffer) # start a new message beginning with URBH
rr.requestCloseDestination( # followed by URBI
token=TOKEN001,
rnam=BROUT1,
dnam=BROUT2)
bb.send_length=rr.endMessage() # end message with URBHLENT = total message size
# and set length for messaging system
bb.send() # send message
This is the resulting message with URBH and URBI settings generated from the close destination request that is sent to the Event Replicator input queue:
0000 E4D9C2C8 00000040 F0F10001 000000A0 *URBH... 01.....-* 0010 00000010 BBBBBBBB BBBBBBBB 00000000 *................* 0020 C3D3D6E2 C4C5E2E3 00000000 00000000 *CLOSDEST........* 0030 00000000 00000000 00000000 00000000 *................* 0040 E4D9C2C9 00000060 00000060 00000000 *URBI...-...-....* 0050 E3D6D2C5 D5F0F0F1 C2D9D6E4 E3F14040 *TOKEN001BROUT1 * 0060 C3D3E2C4 00000000 40404040 40404040 *CLSD.... * 0070 40404040 40404040 C2D9D6E4 E3F24040 * BROUT2 * 0080 00000000 00000000 00000000 00000000 *................* 0090 00000000 00000000 00000000 00000000 *................*
The following depicts the received message at destination BROUT1 for normal completion of the URBI:
0000 E4D9C2C8 00000040 F0F10001 000000C0 *URBH... 01......* 0010 00000001 BB680AF2 C1C27F60 115C0000 *.......2AB”-.*..* 0020 D9C5D7E3 D6D94040 00000000 00000000 *REPTOR..........* 0030 00000000 00000000 00000000 00000000 *................* 0040 E4D9C2E2 00000080 E3D6D2C5 D5F0F0F1 *URBS....TOKEN001* 0050 C3D3E2C4 C3D3D6E2 BB680AF2 C1C18060 *CLSDCLOSC .2AA.-* 0060 00000000 00000000 40404040 40404040 *........ * 0070 40404040 40404040 40404040 40404040 * * 0080 C2D9D6E4 E3F24040 00000000 00000000 *BROUT2 ........* 0090 00000000 00000000 00000000 00000000 *................* 00A0 00000080 00000000 00004000 00000000 *.......... .....* 00B0 00000000 00000000 00000000 00000000 *................*
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 192
urbhmsnr = 1
urbhtime = 2004-06-22 12:22:34.789927
urbhrpid = 4444
urbhrpni = 0
urbhname = "REPTOR"
URBS element at offset X'0040'
urbseye = "URBS"
urbslen = 128
urbsrtok = "TOKEN001"
urbsrt = "CLSD"
urbsst = "CLOS" Destination closed
urbstime = 2004-06-22 12:22:34.789912
urbsrsp = 0
urbssubc = 0
urbserri = " "
urbsinam = " "
urbssnam = " "
urbsdnam = "BROUT2 "
urbsptim = 0
urbsttim = 0
urbstsnr = 0
urbsdbid = 0
urbsfnr = 0
An initial-state request initiates the initial-state processing in the Event Replicator and the nucleus. During initial-state processing, the nucleus reads the selected records and passes them to the Event Replicator Server. The Event Replicator decompresses the records depending on the subscription format and sends the data to the assigned output destinations.
Records can be selected in one of the following manners:
The complete file can be selected.
Records are selected from the file based on an ISN list.
Records are selected from the file based on specified selection criteria.
Initial-state requests must be supported by initial-state definitions. Initial-state definitions are specified in the Adabas Event Replicator Subsystem or by INITIALSTATE parameters in the Event Replicator Server startup job. For more information about initial-state definitions, read about maintaining initial-state definitions using the Adabas Event Replicator Subsystem. For information about the INITIALSTATE parameter, read Event Replicator Initialization Parameters
For an initial-state request, set the elements in the URBI DSECT as described in the following table. If the initial-state definition includes more than one file-database ID definition for the request (a list of them), the initial-state request must contain a URBI for each file.
| Element | Setting |
|---|---|
| URBIEYE | Set to ‘URBI’. |
| URBILEN | Set to URBIL + URBILEND + length
of filler for alignment |
| URBILENH | Set to URBIL. |
| URBILEND | Set to length(selection criteria
or ISN list). This element should be set to zero ('0') in an
initial-state request where the all records in the file are selected by the
initial-state definition.
|
| URBIRT | Set to 'INST' |
| URBINAM | Supply the initial-state definition name as defined in the Adabas Event Replicator Subsystem or by the INITIALSTATE parameter in the Event Replicator Server startup job. The value of this element must be the same for all URBIs in a message. |
| URBIFNR | Supply the file number of the Adabas input file. |
| URBIDBID | Supply the database ID of the Adabas database containing the input file. |
| URBIRNAM | Supply the name of the response destination definition. |
| URBIRTOK | Optionally supply the eight-byte token that allows your client program to recognize different initial-state requests. If you specify this element, its value must be the same in all URBIs in a message. |
The following three fields should be set if the selection data (URBIDATA) has a different encoding or architecture than the database. The usage is similar to the ACODE, WCODE, and ARC parameters in the record buffer for the Adabas OP command (as described in the Adabas command reference documentation). These fields may be used only if the Event Replicator Server is UES-enabled. They must be zero for status requests and for initial-state requests:
| Element | Description |
|---|---|
| URBIACOD | Alpha field encoding in selection data. |
| URBIARC | Architecture flags for selection data. |
| URBIWCOD | Wide field encoding in selection data. |
If the initial-state definition indicates that an ISN list should be used to select records for processing, the initial-state request must include an ISNLIST with the requested ISNs.
The ISNLIST comes behind the URBI structure. It contains a sequence of individual ISNs (fullword) or an ISN range with three fullwords consisting of:
A range indicator X’FFFFFFFF’
The starting ISN
The ending ISN
An ISN list must conform to the following rules:
The same ISN must not be specified more than once with one exception: in a range the starting and ending ISN can be the same.
An individual ISN may not lie within an ISN range
ISN ranges must not overlap
starting ISN <= ending ISN
Violation of these rules will return to the response destination a URBS status message with response code 131, subcode 16.
Should a requested ISN not be present, the system reacts as follows:
For an individual ISN, the initial-state payload will contain a URBR with response code 113, subcode 0 without record data, even if the ISN is beyond TOPISN or outside of MINISN through MAXISN.
Only existent ISNs will be returned for the ISN range.
If the Event Replicator Server discovers an error in the initial-state request, it sends a URBS status message INST/ERRO to the response destination.
Otherwise, the URBS status message INST/INIT is sent to the response and related output destinations and the initial-state request will be forwarded to the nucleus.
Should any error occur with the nucleus (for example if the file is locked), the Event Replicator Server will terminate the initial-state processing and send a final URBS status message INST/CMPL with the error information to the response and output destinations. In contrast, when no error occurs, the nucleus will send initial-state data wrapped in pseudo transactions.
At the end, the Event Replicator Server will notify the response and related output destinations with a URBS status message INST/CMPL.
This section provides several examples of initial-state requests.
This example requests data based on the initial-state definition named ICOLOR.
The initial-state definition named ICOLOR indicates that file 4 of database 10006 should be used for initial-state processing. The subscription definition COLOR defines the output format and destination that will receive the initial-state data.
ADARPD INITIALSTATE NAME=ICOLOR,IFILE=4,IDBID=10006 * ADARPD SUBSCRIPTION NAME=COLOR,SFILE=4,SFDBID=10006,SFBAI='AA,AB.',SDESTINATION='OUT1'
The following application code submits the initial-state request.
rr=newMessage(bb.send_buffer) # start a new message beginning with URBH
rr.requestInitialState( # followed by URBI
token=TOKENTOK,
rnam=OUT1,
inam=ICOLOR,
dbid=10006,
fnr=4)
bb.send_length=rr.endMessage() # end message with URBHLENT = total message size
# and set length for messaging system
bb.send() # send message
This is the resulting message with URBH and URBI settings generated from the initial-state request that is sent to the Event Replicator input queue:
0000 E4D9C2C8 00000040 F0F10001 000000A0 URBH... 01......
0010 00000000 00000000 00000000 00000000 ................
0020 C1849489 95404040 00000000 00000000 Admin ........
0030 00000000 00000000 00000000 00000000 ................
0040 E4D9C2C9 00000060 00000060 00000000 URBI...-...-....
0050 E3D6D2C5 D5E3D6D2 D6E4E3F1 40404040 TOKENTOKOUT1
0060 C9D5E2E3 27160004 C9C3D6D3 D6D94040 INST....ICOLOR
0070 40404040 40404040 40404040 40404040
0080 00000000 00000000 00000000 00000000 ................
1 identical line(s) suppressed
The following messages are received on the OUT1 destination specified by the replication parameters:
The Event Replicator Server accepts the request and sends the INST/INIT status message. URBH is followed by URBS.
0000 E4D9C2C8 00000040 F0F10001 000000C0 URBH... 01......
0010 00000067 BB57F5D2 9C176D82 27170000 ......5K.._b....
0020 D9C5D7E3 D6D94040 00000000 00000000 REPTOR ........
0030 00000000 00000000 00000000 00000000 ................
0040 E4D9C2E2 00000080 E3D6D2C5 D5F14040 URBS....TOKEN1
0050 C9D5E2E3 C9D5C9E3 BB57F5D2 8A8E6E62 INSTINIT..5K..>.
0060 00000000 00000000 40404040 40404040 ........
0070 C9C3D6D3 D6D94040 40404040 40404040 ICOLOR
0080 40404040 40404040 00000000 00000000 ........
0090 00000000 00000000 00000000 27160004 ................
00A0 00000000 00000000 00000000 00000000 ................
1 identical line(s) suppressed
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 192
urbhmsnr = 103
urbhtime = 2004-06-09 17:22:52.308854
urbhrpid = 10007
urbhrpni = 0
urbhname = "REPTOR"
URBS element at offset X'0040'
urbseye = "URBS"
urbslen = 128
urbsrtok = "TOKEN1"
urbsrt = "INST"
urbsst = "INIT" Initial-state processing started
urbstime = 2004-06-09 17:22:52.237030
urbsrsp = 0
urbssubc = 0
urbserri = " "
urbsinam = "ICOLOR"
urbssnam = " "
urbsdnam = " "
urbsptim =
urbsttim =
urbstsnr = 0
urbsdbid = 10006
urbsfnr = 4
The initial-state data comes from the database; file 4 has only three records. The nucleus wraps the data in a pseudo-transaction (URBT) containing records (URBR) and after images (URBD).
0000 E4D9C2C8 00000040 F0F10001 00000250 URBH... 01.....&
0010 00000069 BB57F5D2 CF429E80 27170000 ......5K........
0020 D9C5D7E3 D6D94040 00000000 00000000 REPTOR ........
0030 00000000 00000000 00000000 00000000 ................
0040 E4D9C2E3 00000070 C3D6D3D6 D9404040 URBT....COLOR
0050 00000000 00000003 BB57F5D2 AEE40D22 ..........5K.U..
0060 BB57F5D2 B68E2102 27160000 11111111 ..5K............
0070 22222222 BB57F5D2 93F61021 00000000 ......5Kl6......
0080 27170000 00040000 27170000 404040E8 ............ Y
0090 E3D6D2C5 D5F14040 40000000 00000000 TOKEN1 .......
00A0 00000000 00000000 00000000 00000000 ................
00B0 E4D9C2D9 00000040 00000001 00010004 URBR... ........
00C0 00000002 BB57F5D2 AEA661A2 D9400000 ......5K.w/sR ..
00D0 00000000 40404040 40404040 00000000 .... ....
00E0 00000000 00000000 00000000 00000000 ................
00F0 E4D9C2C4 00000040 00000020 00000020 URBD... ........
0100 00000001 C1000000 00000000 00000000 ....A...........
0110 C7D9C5C5 D5404040 40404040 40404040 GREEN
0120 F2F0F0F4 F0F5F2F5 F1F8F3F5 F4F6F1F0 2004052518354610
0130 E4D9C2D9 00000040 00000002 00010004 URBR... ........
0140 00000003 BB57F5D2 AEE3BE02 D9400000 ......5K.T..R ..
0150 00000000 40404040 40404040 00000000 .... ....
0160 00000000 00000000 00000000 00000000 ................
0170 E4D9C2C4 00000040 00000020 00000020 URBD... ........
0180 00000001 C1000000 00000000 00000000 ....A...........
0190 C2D3E4C5 40404040 40404040 40404040 BLUE
01A0 F2F0F0F4 F0F5F2F5 F1F8F3F5 F4F6F1F1 2004052518354611
01B0 E4D9C2D9 00000040 00000003 00010004 URBR... ........
01C0 00000004 BB57F5D2 AEE3FF62 D9400000 ......5K.T..R ..
01D0 00000000 40404040 40404040 00000000 .... ....
01E0 00000000 00000000 00000000 00000000 ................
01F0 E4D9C2C4 00000040 00000020 00000020 URBD... ........
0200 00000001 C1000000 00000000 00000000 ....A...........
0210 E8C5D3D3 D6E64040 40404040 40404040 YELLOW
0220 F2F0F0F4 F0F5F2F5 F1F8F3F5 F4F6F1F2 2004052518354612
0230 E4D9C2C5 00000020 C3D6D3D6 D9404040 URBE....COLOR
0240 00000000 00000000 00000000 00000000 ................
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 592
urbhmsnr = 105
urbhtime = 2004-06-09 17:22:52.518441
urbhrpid = 10007
urbhrpni = 0
urbhname = "REPTOR"
URBT element at offset X'0040'
urbteye = "URBT"
urbtlen = 112
urbtsnam = "COLOR"
urbttsnr = 0
urbtrcnt = 3
urbtttim = 2004-06-09 17:22:52.385856
urbtptim = 2004-06-09 17:22:52.417250
urbtdbid = 10006
urbtnuci = 0
urbtguid = X'1111111122222222BB57F5D293F61021000000002717000000040000'
urbtrpid = 10007
urbtrpni = 0
urbtusrv = " "
urbtrsnd = " "
urbtinst = "Y"
urbtrtok = "TOKEN1"
urbtcont = " "
URBR element at offset X'00B0'
urbreye = "URBR"
urbrlen = 64
urbrrsnr = 1
urbrdcnt = 1
urbrfnr = 4
urbrisn = 2
urbrtime = 2004-06-09 17:22:52.384870
urbrtyp = "R" initial state
urbrrsnd = " "
urbrrsp = 0
urbrsubc = 0
urbrerrc = " "
URBD element at offset X'00F0'
urbdeye = "URBD"
urbdlen = 64
urbdlenh = 32
urbdlend = 32
urbddsnr = 1
urbdtyp = "A" after image
ubddata = "GREEN","2004052518354610"
URBR element at offset X'0130'
urbreye = "URBR"
urbrlen = 64
urbrrsnr = 2
urbrdcnt = 1
urbrfnr = 4
urbrisn = 3
urbrtime = 2004-06-09 17:22:52.385851
urbrtyp = "R" initial state
urbrrsnd = " "
urbrrsp = 0
urbrsubc = 0
urbrerrc = " "
URBD element at offset X'0170'
urbdeye = "URBD"
urbdlen = 64
urbdlenh = 32
urbdlend = 32
urbddsnr = 1
urbdtyp = "A" after image
urbddata = "BLUE","2004052518354611"
URBR element at offset X'01B0'
urbreye = "URBR"
urbrlen = 64
urbrrsnr = 3
urbrdcnt = 1
urbrfnr = 4
urbrisn = 4
urbrtime = 2004-06-09 17:22:52.385855
urbrtyp = "R" initial state
urbrrsnd = " "
urbrrsp = 0
urbrsubc = 0
urbrerrc = " "
URBD element at offset X'01F0'
urbdeye = "URBD"
urbdlen = 64
urbdlenh = 32
urbdlend = 32
urbddsnr = 1
urbdtyp = "A" after image
urbddata = "YELLOW","2004052518354612"
URBE element at offset X'0230'
urbeeye = "URBE"
urbelen = 64
urbesnam = "COLOR"
urbetsnr = 0
At the end of initial-state processing, the Event Replicator Server sends a completion status message URBS/INST/CMPL
0000 E4D9C2C8 00000040 F0F10001 000000C0 URBH... 01......
0010 0000006A BB57F5D2 CF658501 27170000 ......5K..e.....
0020 D9C5D7E3 D6D94040 00000000 00000000 REPTOR ........
0030 00000000 00000000 00000000 00000000 ................
0040 E4D9C2E2 00000080 E3D6D2C5 D5F14040 URBS....TOKEN1
0050 C9D5E2E3 C3D4D7D3 BB57F5D2 B690FF62 INSTCMPL..5K....
0060 00000000 00000000 40404040 40404040 ........
0070 C9C3D6D3 D6D94040 40404040 40404040 ICOLOR
0080 40404040 40404040 00000000 00000000 ........
0090 00000000 00000000 00000000 27160004 ................
00A0 00000000 00000000 00000000 00000000 ................
1 identical line(s) suppressed
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 192
urbhmsnr = 106
urbhtime = 2004-06-09 17:22:52.519000
urbhrpid = 10007
urbhrpni = 0
urbhname = "REPTOR"
URBS element at offset X'0040'
urbseye = "URBS"
urbslen = 128
urbsrtok = "TOKEN1"
urbsrt = "INST"
urbsst = "CMPL" Initial-state processing completed
urbstime = 2004-06-09 17:22:52.417295
urbsrsp = 0
urbssubc = 0
urbserri = " "
urbsinam = "ICOLOR"
urbssnam = " "
urbsdnam = " "
urbsptim =
urbsttim =
urbstsnr = 0
urbsdbid = 10006
urbsfnr = 4
An invalid initial-state request is answered with a status response INST/ERRO to the response destination. The destination file number is not specified correctly.
0000 E4D9C2C8 00000040 F0F10001 000000C0 URBH... 01......
0010 0000006C BB57FAA1 09D9A980 27170000 ...%.....Rz.....
0020 D9C5D7E3 D6D94040 00000000 00000000 REPTOR ........
0030 00000000 00000000 00000000 00000000 ................
0040 E4D9C2E2 00000080 E3D6D2C5 D5F14040 URBS....TOKEN1
0050 C9D5E2E3 C5D9D9D6 BB57FAA1 09D8A720 INSTERRO.....Qx.
0060 00000083 0000000C 40404040 40404040 ...c....
0070 C9C3D6D3 D6D94040 40404040 40404040 ICOLOR
0080 40404040 40404040 00000000 00000000 ........
0090 00000000 00000000 00000000 27160002 ................
00A0 00000000 00000000 00000000 00000000 ................
1 identical line(s) suppressed
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 192
urbhmsnr = 108
urbhtime = 2004-06-09 17:44:22.506906
urbhrpid = 10007
urbhrpni = 0
urbhname = "REPTOR"
URBS element at offset X'0040'
urbseye = "URBS"
urbslen = 128
urbsrtok = "TOKEN1"
urbsrt = "INST"
urbsst = "ERRO" Initial-state processing ERROR
urbstime = 2004-06-09 17:44:22.506890
urbsrsp = 131
urbssubc = 12 INITIALSTATE DBID/FNR definition not found as requested in URBI
urbserri = " "
urbsinam = "ICOLOR"
urbssnam = " "
urbsdnam = " "
urbsptim =
urbsttim =
urbstsnr = 0
urbsdbid = 10006
urbsfnr = 2
This example shows an initial-state request using selection criteria. In addition, since the client is on an Intel x86 machine, the data must be converted for the different machine architecture.
Let's assume the EMPLOYEES file (Adabas example) is replicated to a client application that stores the records on a separate database – for example to provide in-house web access to selected fields for name-telephone look-up.
The subscription definition, EMPLOYEE, defines the following:
The data is to be delivered to destination OUT1.
The data is to be converted to ISO8859-1/Latin-1 = ECS code page 819 for alpha fields. The data to be converted to UTF-8 = ECS code page 4091 for wide fields. Integer numbers are to be byte-swapped and floating point data is to be converted to IEEE.
The file to be replicated is number 9 on database 10006.
The global format, EMPLTEL, defines the format to be used for the before and after images.
The initial-state definition, IEMPLAA, defines a selection criteria on the PERSONNEL-ID. This is the unique primary key AA. The selection criteria "AA,S,AA." requires the starting and ending values for the primary key. In the example below the selection value "20011000" through "20011100" selects all records in this range – that is 2 records.
ADARPD SUBSCRIPTION NAME=EMPLOYEE ADARPD SDESTINATION='OUT1' ADARPD SACODE=819,SWCODE=4091,SARC=9 ADARPD SFILE=9,SFDBID=10006 ADARPD SGFORMATAI=EMPLTEL * ADARPD GFORMAT NAME=EMPLTEL Fields extracted for Telephone List WEBAPP ADARPD GFB='AA,AC,AD,AE,' PERSONNEL-ID FIRST-NAME MIDDLE LAST-NAME ADARPD GFB='AH,8,U,AN,AM,AO,AP.' BIRTH AREA-CODE PHONE DEPT JOB-TITLE * ADARPD INITIALSTATE NAME=IEMPLAA,IFILE=9,IDBID=10006,SELCRIT='AA,S,AA.' *
The following application code submits the initial-state request.
rr=newMessage(bb.send_buffer) # start a new message beginning with URBH rr.requestInitialState( # followed by URBI token=EMPLTOKN, rnam=OUT1, inam=IEMPLTEL,dbid=10006,fnr=4, arc=9,acode=819,wcode=4091) bb.send_length=rr.endMessage() # end message with URBHLENT = total message size # and set length for messaging system bb.send() # send message
This is the resulting message with URBH and URBI settings generated from the initial-state request that is sent to the Event Replicator input queue:
0000 55524248 40000000 30310100 B0000000 URBH@...01......
0010 00000000 00000000 00000000 00000000 ................
0020 41646D69 6E202020 00000000 00000000 Admin ........
0030 00000000 00000000 00000000 00000000 ................
0040 55524249 70000000 60000000 10000000 URBIp...........
0050 454D504C 544F4B4E 4F555432 20202020 EMPLTOKNOUT2
0060 494E5354 16270900 49454D50 4C414120 INST.'..IEMPLAA
0070 20202020 20202020 20202020 20202020
0080 33030000 FB0F0000 09000000 00000000 3...............
0090 00000000 00000000 00000000 00000000 ................
00A0 32303031 31303030 32303031 31313030 2001100020011100
The following messages are received on the OUT1 destination specified by the replication parameters:
The Event Replicator Server accepts the request and sends the INST/INIT status message. URBH is followed by URBS.
0000 55524248 40000000 30310100 C0000000 URBH@...01......
0010 08000000 42CE8C88 B2BA7DBB 17270000 ....B........'..
0020 52455054 4F522020 00000000 00000000 REPTOR ........
0030 00000000 00000000 00000000 00000000 ................
0040 55524253 80000000 454D504C 544F4B4E URBS....EMPLTOKN
0050 494E5354 494E4954 626B8888 B2BA7DBB INSTINITbk......
0060 00000000 00000000 20202020 20202020 ........
0070 49454D50 4C414120 20202020 20202020 IEMPLAA
0080 20202020 20202020 00000000 00000000 ........
0090 00000000 00000000 00000000 16270900 .............'..
00A0 00000000 00000000 00000000 00000000 ................
1 identical line(s) suppressed
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 192
urbhmsnr = 8
urbhtime = 18:20:41.098444
urbhrpid = 10007
urbhrpni = 0
urbhname = "REPTOR"
URBS element at offset X'0040'
urbseye = "URBS"
urbslen = 128
urbsrtok = "EMPLTOKN"
urbsrt = "INST"
urbsst = "INIT" Initial-state processing started
urbstime = 18:20:41.098374
urbsrsp = 0
urbssubc = 0
urbserri = " "
urbsinam = "IEMPLAA"
urbssnam = " "
urbsdnam = " "
urbsptim =
urbsttim =
urbstsnr = 0
urbsdbid = 10006
urbsfnr = 9
Here is the initial-state data message:
0000 55524248 40000000 30310100 90020000 URBH@...01......
0010 09000000 803223B8 B2BA7DBB 17270000 .....2#......'..
0020 52455054 4F522020 00000000 00000000 REPTOR ........
0030 00000000 00000000 00000000 00000000 ................
0040 55524254 70000000 454D504C 4F594545 URBTp...EMPLOYEE
0050 00000000 02000000 62297389 B2BA7DBB ........b)s.....
0060 00A205A5 B2BA7DBB 16270000 11111111 .........'......
0070 33333333 BB7DBAB2 889A9A02 00000000 3333............
0080 27170000 00090000 17270000 20202059 '........'.. Y
0090 454D504C 544F4B4E 20090000 33030000 EMPLTOKN ...3...
00A0 FB0F0000 00000000 00000000 00000000 ................
00B0 55524252 40000000 01000000 01000900 URBR@...........
00C0 5A020000 428F7289 B2BA7DBB 52200000 Z...B.r.....R ..
00D0 00000000 20202020 20202020 00000000 .... ....
00E0 00000000 00000000 00000000 00000000 ................
00F0 55524244 A0000000 20000000 80000000 URBD.... .......
0100 01000000 41000000 00000000 00000000 ....A...........
0110 32303031 31303030 424F4220 20202020 20011000BOB
0120 20202020 20202020 20202020 48454E52 HENR
0130 59202020 20202020 20202020 20202020 Y
0140 41444B49 4E534F4E 20202020 20202020 ADKINSON
0150 20202020 30303334 30353035 30313031 003405050101
0160 20202833 31362933 38392D39 33323520 (316)389-9325
0170 2053414C 45323053 414C4553 20504552 SALE20SALES PER
0180 534F4E20 20202020 20202020 20202020 SON
0190 55524252 40000000 02000000 01000900 URBR@...........
01A0 5B020000 62F57289 B2BA7DBB 52200000 ....b.r.....R ..
01B0 00000000 20202020 20202020 00000000 .... ....
01C0 00000000 00000000 00000000 00000000 ................
01D0 55524244 A0000000 20000000 80000000 URBD.... .......
01E0 01000000 41000000 00000000 00000000 ....A...........
01F0 32303031 31313030 53484952 4C592020 20011100SHIRLY
0200 20202020 20202020 20202020 502E2020 P.
0210 20202020 20202020 20202020 20202020
0220 4D454C4B 414E4F46 46202020 20202020 MELKANOFF
0230 20202020 30303432 30373230 30313031 004207200101
0240 20202838 30342933 37362D30 38353020 (804)376-0850
0250 204D474D 5433304D 414E4147 45522020 MGMT30MANAGER
0260 20202020 20202020 20202020 20202020
0270 55524245 20000000 454D504C 4F594545 URBE ...EMPLOYEE
0280 00000000 00000000 00000000 00000000 ................
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 656
urbhmsnr = 9
urbhtime = 18:20:41.293363
urbhrpid = 10007
urbhrpni = 0
urbhname = "REPTOR"
URBT element at offset X'0040'
urbteye = "URBT"
urbtlen = 112
urbtsnam = "EMPLOYEE"
urbttsnr = 0
urbtrcnt = 2
urbtttim = 18:20:41.102130
urbtptim = 18:20:41.215066
urbtdbid = 10006
urbtnuci = 0
urbtguid = X'1111111133333333BB7DBAB2889A9A02000000002717000000090000'
urbtrpid = 10007
urbtrpni = 0
urbtusrv = " "
urbtrsnd = " "
urbtinst = "Y"
urbtrtok = "EMPLTOKN"
urbtcont = " "
urbtarc = X'09'
urbtacod = 819
urbtwcod = 4091
URBR element at offset X'00B0'
urbreye = "URBR"
urbrlen = 64
urbrrsnr = 1
urbrdcnt = 1
urbrfnr = 9
urbrisn = 602
urbrtime = 18:20:41.102120
urbrtyp = "R" initial state
urbrrsnd = " "
urbrrsp = 0
urbrsubc = 0
urbrerrc = " "
URBD element at offset X'00F0'
urbdeye = "URBD"
urbdlen = 160
urbdlenh = 32
urbdlend = 128
urbddsnr = 1
urbdtyp = "A" after image
urbddata =
0000 32303031 31303030 424F4220 20202020 20011000BOB
0010 20202020 20202020 20202020 48454E52 HENR
0020 59202020 20202020 20202020 20202020 Y
0030 41444B49 4E534F4E 20202020 20202020 ADKINSON
0040 20202020 30303334 30353035 30313031 003405050101
0050 20202833 31362933 38392D39 33323520 (316)389-9325
0060 2053414C 45323053 414C4553 20504552 SALE20SALES PER
0070 534F4E20 20202020 20202020 20202020 SON
URBR element at offset X'0190'
urbreye = "URBR"
urbrlen = 64
urbrrsnr = 2
urbrdcnt = 1
urbrfnr = 9
urbrisn = 603
urbrtime = 18:20:41.102127
urbrtyp = "R" initial state
urbrrsnd = " "
urbrrsp = 0
urbrsubc = 0
urbrerrc = " "
URBD element at offset X'01D0'
urbdeye = "URBD"
urbdlen = 160
urbdlenh = 32
urbdlend = 128
urbddsnr = 1
urbdtyp = "A" after image
urbddata =
0000 32303031 31313030 53484952 4C592020 20011100SHIRLY
0010 20202020 20202020 20202020 502E2020 P.
0020 20202020 20202020 20202020 20202020
0030 4D454C4B 414E4F46 46202020 20202020 MELKANOFF
0040 20202020 30303432 30373230 30313031 004207200101
0050 20202838 30342933 37362D30 38353020 (804)376-0850
0060 204D474D 5433304D 414E4147 45522020 MGMT30MANAGER
0070 20202020 20202020 20202020 20202020
URBE element at offset X'0270'
urbeeye = "URBE"
urbelen = 32
urbesnam = "EMPLOYEE"
urbetsnr = 0
Here is the initial-state completion message:
0000 55524248 40000000 30310100 C0000000 URBH@...01......
0010 0A000000 603141B8 B2BA7DBB 17270000 .....1A......'..
0020 52455054 4F522020 00000000 00000000 REPTOR ........
0030 00000000 00000000 00000000 00000000 ................
0040 55524253 80000000 454D504C 544F4B4E URBS....EMPLTOKN
0050 494E5354 434D504C 801E08A5 B2BA7DBB INSTCMPL........
0060 00000000 00000000 20202020 20202020 ........
0070 49454D50 4C414120 20202020 20202020 IEMPLAA
0080 20202020 20202020 00000000 00000000 ........
0090 00000000 00000000 00000000 16270900 .............'..
00A0 00000000 00000000 00000000 00000000 ................
1 identical line(s) suppressed
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 192
urbhmsnr = 10
urbhtime = 18:20:41.293843
urbhrpid = 10007
urbhrpni = 0
urbhname = "REPTOR"
URBS element at offset X'0040'
urbseye = "URBS"
urbslen = 128
urbsrtok = "EMPLTOKN"
urbsrt = "INST"
urbsst = "CMPL" Initial-state processing completed
urbstime = 18:20:41.215105
urbsrsp = 0
urbssubc = 0
urbserri = " "
urbsinam = "IEMPLAA"
urbssnam = " "
urbsdnam = " "
urbsptim =
urbsttim =
urbstsnr = 0
urbsdbid = 10006
urbsfnr = 9
If the target application detects a gap in the transaction sequence numbers, a prior-transaction request may be issued to have the Event Replicator Server attempt to send a missing transaction again. Defining a resend buffer and associating it with a subscription enables this capability. Gaps in the transaction number sequence should not occur when a guaranteed-delivery message transport system (such as WebSphere MQ) is being used. A prior-transaction request consists of one URBH followed by one URBI.
The resend buffer operates in a circular manner. Newer transactions will overwrite older ones. The number of transactions available for retransmission depends on the size of the buffer, the number of subscriptions sharing the buffer, and the size of the transactions. The resend buffer retains the URBT and URBRs from the transactions, as well as before-image URBDs. After-image URBDs are not retained.
The subscription name (URBISNAM), destination name (URBIDNAM), and transaction number (URBITSNR) are always required in the prior-transaction request. The transaction will be sent to the single destination identified in the request. Destinations receiving retransmitted transactions must be associated with the subscription and must be for WebSphere MQ or webMethods EntireX messaging systems.
If the optional reply destination (URBIRNAM) is provided, a status message (URBS) will be sent to that destination for successful prior-transaction requests.
A URBS status message with response code 131 and an appropriate subcode may also be generated for errors. Error status messages are routed depending on the error and whether valid optional destinations are available:
If the prior-transaction request specifies a valid reply destination name (URBIRNAM), a status message is sent to the specified destination.
If the prior-transaction request specifies a valid destination name (URBIDNAM), a status message is sent to the specified destination for certain errors (subcodes 34, 35, 37 and 39 to 43).
If the reply destination name is also associated with the subscription, only one status message will be sent to that destination.
If no active destination can be identified for an error status message, message ADAF1V will be generated on the operator’s console and file DDPRINT.
Destinations receiving status messages must be for WebSphere MQ or webMethods EntireX messaging systems. Status messages contain the following information:
| Element | Description |
|---|---|
| URBSTIME | STCK time when the URBS message was created. |
| URBSRTOK | User token provided with the URBI. |
| URBSSNAM | Subscription name provided with the URBI. |
| URBSDNAM | Destination name provided with the URBI. |
| URBSTSNR | Transaction sequence number within the subscription/destination provided with the URBI. |
| URBSRT | "TRAN" |
| URBSST | "TRSP" |
| URBSRSP | Response code. |
| URBSSUBC | Subcode. |
This section covers the following topics:
For a prior-transaction request, set the elements in the URBI DSECT as described in the following table. Values may be provided for only these fields. All unused binary fields must be set to zero, and all unused character fields must be set to blanks.
| Element | Setting |
|---|---|
| URBIEYE | Set to "URBI". |
| URBILEN | Set to URBIL. |
| URBILENH | Set to URBIL. |
| URBIRT | Set to "TRAN". |
| URBISNAM | Supply the subscription name. |
| URBITSNR | Supply the transaction number for which retransmission is requested. |
| URBIDNAM | Supply the destination name associated with the supplied subscription for which retransmission is requested. |
| URBIRNAM | Optionally, supply a reply destination name. |
| URBIRTOK | Optionally, supply the eight-byte token that allows your target application to recognize different status requests. |
This example requests a prior-transaction run of the subscription named COLOR. The following topics are included in this section.
Assume that the RESEND1 resend buffer is defined with the size specified as shown below:
ADARPD RESENDBUFFER NAME=RESEND1 ADARPD RSIZE=2048K
Assume also that the COLOR subscription is associated with output destinations and the RESEND1 resend buffer as shown below:
ADARPD SUBSCRIPTION NAME=COLOR ADARPD SFILE=4,SFDBID=10006,SFBAI='AA,AB.',SDESTINATION='OUT1,OUT2' ADARPD SRESENDBUFFER=RESEND1
The following application code requests retransmission of transaction 100 within subscription COLOR. The transaction will be sent to destinations OUT1 and OUT2, and a URBS status message will be sent to destination OUT3.
rr=newMessage(bb.send_buffer) # start a new message beginning with
# URBH and followed by URBI
rr.requestPriorTransaction(
token=TOKTOK,
snam=COLOR,
tsnr=100,
rnam=OUT3)
bb.send_length=rr.endMessage() # end message with
# URBHLENT = total message size
# and set length for messaging system
bb.send() # send message
This is the resulting message with URBH and URBI settings generated from the status request that is sent to the Event Replicator input queue :
0000 E4D9C2C8 00000040 F0F10001 000000A0 URBH... 01...... 0010 00000000 00000000 00000000 00000000 ................ 0020 C1849489 95404040 00000000 00000000 Admin ........ 0030 00000000 00000000 00000000 00000000 ................ 0040 E4D9C2C9 00000060 00000060 00000000 URBI............ 0050 E3D6D2E3 D6D24040 D6E4E3F3 40404040 TOKTOK OUT3 0060 E3D9C1D4 00000000 40404040 40404040 TRAN.... 0070 C3D6D3D6 D9404040 40404040 40404040 COLOR 0080 00000000 00000000 00000000 00000000 ................ 0090 00000000 00000000 00000000 00000000 ................
If the transaction was found in the resend buffer, OUT1 and OUT2 will receive a message with a URBH, URBT, all URBRs and before-image URBDs, and ending with a URBE. The following fields are altered to indicate retransmission:
| Element | Setting |
|---|---|
| URBTRSND | Set to "Y", indicating data may have been sent previously. |
| URBTPTRN | Set to "Y", indicating data from a previous transaction is being resent. |
| URBRRSND | Set to "Y", indicating data may have been sent previously. |
If there were errors, OUT1 and OUT2 may each receive a URBS status message similar to the one described for OUT3.
The following depicts the received message at destination OUT3 for normal completion:
0000 E4D9C2C8 00000040 F0F10001 000000C0 URBH... 01...... 0010 00000004 BB680AF2 C1C27F60 27170000 .......2AB"-.... 0020 D9C5D7E3 D6D94040 00000000 00000000 REPTOR ........ 0030 00000000 00000000 00000000 00000000 ................ 0040 E4D9C2E2 00000080 E3D6D2E3 D6D24040 URBS....TOKTOK 0050 E3D9C1D4 E3D9E2D7 BB680AF2 C1C18060 TRANTRSP...2AA.- 0060 00000000 00000000 40404040 40404040 ........ 0070 40404040 40404040 C3D6D3D6 D9404040 COLOR 0080 40404040 40404040 BB680A7E 1AF84B02 ...=.8.. 0090 00000000 00000000 00000064 00000000 ................ 00A0 00000000 00000000 00000000 00000000 ................ 00B0 00000000 00000000 00000000 00000000 ................
A status request inquires about the status of a subscription.
If the status request specifies a subscription and destination, a status message about the subscription/destination pair is sent to the specified destination.
If the status request specifies only the subscription, a status message about each subscription/destination pair in the subscription is sent to all destinations defined in the subscription.
If the status request specifies only the destination, a status message about the subscription/destination pair is sent to the specified destination for each subscription having the destination as output.
In addition, a reply destination can be specified in the status request. The reply destination receives a copy of the status messages. Destinations receiving status messages must be for WebSphere MQ or webMethods EntireX messaging systems.
The status message (URBS) contains the following information:
| Status Element | Description |
|---|---|
| URBSTTIM | STCK Time of transaction commit. In other words, when database processed the ET |
| URBSSTIM | STCK Time when last records was processed by subscription |
| URBSTIME | STCK Time when URBS message was sent |
| URBSTSNR | Transaction sequence number within subscription/destination |
This section covers the following topics:
For a status request, set the elements in the URBI DSECT as described in the following table.
| Element | Setting |
|---|---|
| URBIEYE | Set to ‘URBI’. |
| URBILEN | Set to URBIL. |
| URBILENH | Set to URBIL. |
| URBILEND | Set to 0. |
| URBIRT | Set to 'STAT' |
| URBISNAM | Supply the subscription name. Either the subscription name (URBISNAM) or the destination name (URBIDNAM) or both are required. |
| URBIDNAM | Supply the destination name. Either the subscription name (URBISNAM) or the destination name (URBIDNAM) or both are required. |
| URBIRNAM | Optionally supply a response destination. |
| URBIRTOK | Optionally supply the eight-byte token that allows your client program to recognize different status requests. |
This example requests a status of the subscription named COLOR.
The COLOR subscription defines the format and output destination:
ADARPD SUBSCRIPTION NAME=COLOR,SFILE=4,SFDBID=10006,SFBAI='AA,AB.',SDESTINATION='OUT1'
The following application code inquires about the status of subscription COLOR.
rr=newMessage(bb.send_buffer) # start a new message beginning with URBH
rr.requestStatus( # followed by URBI
token=TOKTOK,,
snam=COLOR)
bb.send_length=rr.endMessage() # end message with URBHLENT = total message size
# and set length for messaging system
bb.send() # send message
This is the resulting message with URBH and URBI settings generated from the status request that is sent to the Event Replicator input queue :
0000 E4D9C2C8 00000040 F0F10001 000000A0 URBH... 01......
0010 00000000 00000000 00000000 00000000 ................
0020 C1849489 95404040 00000000 00000000 Admin ........
0030 00000000 00000000 00000000 00000000 ................
0040 E4D9C2C9 00000060 00000060 00000000 URBI...-...-....
0050 E3D6D2E3 D6D24040 40404040 40404040 TOKTOK
0060 E2E3C1E3 00000000 40404040 40404040 STAT....
0070 C3D6D3D6 D9404040 40404040 40404040 COLOR
0080 00000000 00000000 00000000 00000000 ................
1 identical line(s) suppressed
The following depicts the received message on the OUT1 destination specified by the replication parameters:
0000 E4D9C2C8 00000040 F0F10001 000000C0 URBH... 01......
0010 00000004 BB680AF2 C1C27F60 27170000 .......2AB"-....
0020 D9C5D7E3 D6D94040 00000000 00000000 REPTOR ........
0030 00000000 00000000 00000000 00000000 ................
0040 E4D9C2E2 00000080 E3D6D2E3 D6D24040 URBS....TOKTOK
0050 E2E3C1E3 E2E4C2E2 BB680AF2 C1C18060 STATSUBS...2AA.-
0060 00000000 00000000 40404040 40404040 ........
0070 40404040 40404040 C3D6D3D6 D9404040 COLOR
0080 40404040 40404040 BB680A7E 1AF84B02 ...=.8..
0090 BB680A7D F767EE02 00000002 00000000 ...'7...........
00A0 00000000 00000000 00000000 00000000 ................
1 identical line(s) suppressed
which can be interpreted as:
URBH element at offset X'0000'
urbheye = "URBH"
urbhlen = 64
urbhvers = "01"
urbhbord = X'0001'
urbhlent = 192
urbhmsnr = 4
urbhtime = 2004-06-22 12:22:34.789927
urbhrpid = 10007
urbhrpni = 0
urbhname = "REPTOR"
URBS element at offset X'0040'
urbseye = "URBS"
urbslen = 128
urbsrtok = "TOKTOK"
urbsrt = "STAT"
urbsst = "SUBS" Subscription status information
urbstime = 2004-06-22 12:22:34.789912
urbsrsp = 0
urbssubc = 0
urbserri = " "
urbsinam = " "
urbssnam = "COLOR"
urbsdnam = " "
urbsptim = 2004-06-22 12:20:32.471940
urbsttim = 2004-06-22 12:20:32.326270
urbstsnr = 2
urbsdbid = 0
urbsfnr = 0