Debugging CICS bridge applications
This section describes some common symptoms when your bridge application
appears not to work as you might expect, and suggests procedures for diagnosing
the problem.
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 it 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(R) CSMT and joblog
on all CICS regions where bridge monitors should be running, to see if there
has been an error that 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 is not the first message 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 will almost always report
the reason why the DPL program or transaction failed to run. The common reasons
for this are:
- 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 bridge are given in WebSphere MQ for z/OS System Setup Guide.
- Check the message that is sent to the reply queue by the bridge monitor.
If an error has occurred, it is likely that MQCIH.Format 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 should be set to a feedback code that indicates the reason
for the failure.
For information on feedback codes, including those specific
to the CICS Bridge, see "MQMD - Message descriptor" in the WebSphere MQ Application Programming Reference.
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 ABR*, ABS* and ABX* are CICS bridge abends, and are documented in CICS Messages and Codes. Abends MBR* and MQB* are WebSphere MQ bridge abends,
and are documented in WebSphere MQ for z/OS Messages and Codes.
Some common abend codes can be dealt with 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 non zero 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
- Caused either by having brmq_re_buffer_indicator set
to N, when a receive with the buffer option was specified, or having brmq_re_buffer_indicator 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 brmq_vector_length and
the length of the data vector do not agree, or there is not enough data in
the CICS headers and vector
- MBRN
- The message is shorter than expected. There are one or two data length
fields in every vector structure. 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 actually is, the
bridge task will abend MBRN.
- MBRO and MBRP
- There is an error in the vector structure (not the variable length data).
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, which
are described in the CICS Internet and External Interfaces Guide for CICS V1.2, or the CICS External Interfaces Guide for CICS V1.3..
Bridge monitor errors
Some errors can cause the bridge monitor transaction, CKBR, to terminate
unexpectedly. If you are using triggered queues to start the monitor, and
there are still messages on the bridge request queue, the CKTI transaction
might attempt to restart CKBR. If the original error persists, this can lead
to a loop of CKBR failures. 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 executing CICS or MQ services.