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

1. 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. You should use a queue attribute of TRIGTYPE(FIRST).

   If the bridge monitor was running but is no longer running, check the output in the CICS MSGUSR log to see if there has been an error that has caused the bridge monitor to terminate.

2. If the bridge request queue is defined with QSGDISP(SHARED), check that it also specifies INDXTYPE(CORRELID).
3. 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).
4. 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

1. 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.
2. 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.
3. 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 the CICS Messages and Codes book. 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 will return a facility token in field MQCIH.Facility, and you can use this value in all subsequent inbound messages in the pseudoconversation.

MBRJ

The MQCIH has invalid data. Check the values in the MQCIH field by field to find the one that is out of range.

MBRN

The message is shorter than expected. There are one or two data length fields in every vector structure. The first is the very 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 which 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 give 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 may attempt to restart CKBR. If the original error persists, this can lead to a loop of CKBR failures. To halt the loop you can 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 is unable to write to the dead letter queue or it encounters problems when executing CICS or MQ services.