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. 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 bridge monitors should be running, 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 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 we 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.

 

Parent topic:

Information applicable to both DPL and 3270


fg15780_