Debugging CICS-WebSphere bridge applications
Bridge monitor errors and common abend codes are explained.
Message is PUT to the bridge request queue, but is not processed by the bridge monitor
- Check that the bridge monitor is running. Issue CEMT I TASK and
look for CKBR or whatever other transaction identifier you are using
for the bridge monitor.
If the bridge monitor is not running and you are expecting it to be triggered, make sure that the triggering options on the bridge request queue are correct. Use a queue attribute of TRIGTYPE(FIRST).
If the bridge monitor was running but is no longer running, check the output in the CICS® CSMT and joblog on all CICS regions where you expect bridge monitors to be running, to see if an error has caused the bridge monitor to terminate.
- If the bridge request queue is defined with QSGDISP(SHARED), check that it also specifies INDXTYPE(CORRELID).
- Browse the inbound message that is not being processed and check that the values of MQMD.MsgId and MQMD.CorrelId are correct. If this is the first message in a unit of work or a pseudoconversation, MQMD.CorrelId must be set to a value of MQCI_NEW_SESSION and MQMD.MsgId must be set to MQMI_NONE (binary zeros).
- If this message is not the first one in a unit of work or pseudoconversation,
ensure that your application has checked previous reply messages adequately
for possible errors. As a minimum, it should check the following fields
in the MQCIH:
- MQCIH.ReturnCode
- MQCIH.CompCode
- MQCIH.TaskEndStatus
- MQCIH.AbendCode
- MQCIH.ErrorOffset
Inbound message is taken from the request queue by the bridge monitor, but the CICS DPL program or CICS transaction fails to run
- Check the output in the CICS MSGUSR log. This output nearly
always reports the reason why the DPL program or transaction failed
to run. The common reasons for this are as follows:
- Program or transaction not defined to CICS. Use CEDA to define the program or transaction and run your bridge application again.
- Insufficient authority to run the program or transaction. Details of how to control the level of authentication used by the CICS-WebSphere® MQ bridge are given in Setting up the CICS-WebSphere MQ bridge.
- Check the message that is sent to the reply queue by the bridge monitor. If an error has occurred, it is likely that the MQCIH.Format field is set to MQFMT_STRING and an error message is appended to the MQCIH in place of a vector.
- Check the dead letter queue to see if a reply message has been sent there by the bridge monitor.
If it has, and the values of MQMD.MsgId and MQMD.CorrelId are correct, check the value of
MQDLH.Reason. This value is typically set to a feedback code that indicates the reason for the
failure.
For information on feedback codes, including those specific to the CICS-IBM MQ bridge, see CICS messages.
Bridge task abends
Abend codes are set in outbound messages in field MQCIH.AbendCode. In addition, the output in the CICS MSGUSR log reports abend codes for failing bridge tasks.
Abends are documented in CICS messages.
You can deal with some common abend codes as follows:
- ABRG
- An invalid bridge facility token was specified in an inbound message. Your first inbound message must always specify a value of MQCFAC_NONE in field MQCIH.Facility, and a nonzero value in MQCIH.FacilityKeepTime. CICS returns a facility token in field MQCIH.Facility, and you can use this value in all subsequent inbound messages in the pseudoconversation.
- ABXH
- Either brmq_re_buffer_indicator was set to N, when a receive with the buffer option was specified, or brmq_re_buffer_indicator was set to Y and a receive (without the buffer option ) specified.
- MBRJ
- The MQCIH has invalid data. Check the values in the MQCIH field by field to find the one that is out of range. MBRJ can also be caused by a length mismatch; for example, when the value of brmq_vector_length and the length of the data vector do not agree, or the CICS headers and vector do not contain enough data.
- MBRN
- The message is shorter than expected. Every vector structure has one or two data length fields. The first is the first fullword field in the standard header for all vectors, and it should be equal to the overall length of the vector including the variable length data. Some vectors also contain another fullword length field that gives just the length of the variable length data. If these values indicate more data than there is, the bridge task abends with MBRN.
- MBRO and MBRP
- The vector structure (not the variable length data) contains an error. The MQCIH field ERROROFFSET gives the offset of the field in error. Check the values of the fields in the vector against the permitted values, as described in Link3270 message formats.
Bridge monitor errors
Some errors can cause the bridge monitor transaction, CKBR, to end unexpectedly. If you are using triggered queues to start the monitor, and messages remain on the bridge request queue, the CKTI transaction might try to restart CKBR. If the original error persists, CKBR failures might loop. To halt the loop, set off the TriggerControl attribute of the request queue while you diagnose and fix the underlying problem.
The bridge monitor can fail if it does not have sufficient authority to access the queues or CICS transactions, if it cannot write to the dead letter queue or it encounters problems when running CICS or IBM MQ services.