How Do You Trace a Timeout Across API, CICS, Db2^®, and MQ?

It's 9:14 a.m. Customers can't complete payments in the mobile app, and the service desk declares a severity 1 (Sev-1) incident. The application programming interface (API) gateway looks green. The Customer Information Control System (CICS) region looks normal. IBM Db2^® and IBM MQ aren't alarming. Yet the transaction keeps timing out.

Short answer: To trace a timeout across API, CICS, Db2^®, and MQ, follow one failing transaction end to end instead of checking each component on its own. Reconstruct its path, compare each hop's elapsed time to its normal baseline, and find the first point where it diverges. That divergence tells you where to dig, and correlated evidence tells you why.

Teams can't fix a timeout until they know where the transaction is actually slowing down. The rest of this guide walks through a disciplined way to find it.

Why are mainframe transaction timeouts so hard to diagnose?

Mainframe transaction timeouts are hard to diagnose because the symptom usually surfaces far from the bottleneck. The API layer reports the timeout, but the delay may sit in CICS, IBM Db2^®, IBM MQ, the network, or a downstream service.

Four conditions make this harder than it should be:

• Distributed-to-mainframe dependencies. One mobile request can cross an API gateway, an integration layer, a CICS transaction, Db2^® tables, and MQ queues before it returns.
• Different logs, clocks, and monitoring domains. Each team sees its own tools, and timestamps rarely line up perfectly.
• Lost transaction context. Identifiers often don't survive each hop, so you can't easily match an API error to a specific CICS task.
• Healthy averages. A component can perform well on average while one transaction path fails badly.

Transaction context is the set of identifiers, timestamps, and dependencies that link one user request to every system it touches, from the API call to the CICS task, the Db2^® thread, and the MQ message. Without it, every team investigates a different piece of the same incident.

Why doesn't component health prove transaction health?

Component health doesn't prove transaction health because dashboards summarize resources, while customers experience paths. A CICS region can run at modest CPU, Db2^® can report normal buffer pool activity, and MQ can show acceptable queue depths, while one specific transaction waits on a single locked row, a single slow reply queue, or one exhausted connection pool. Averages hide that kind of narrow failure. A green dashboard tells you a component isn't broadly overloaded. It doesn't tell you whether your failing transaction moved through that component on time.
 

Where should you start when a transaction times out?

Start with the affected transaction, not with whichever console fired the loudest alert. Then work through the path in a fixed order so every team builds from the same evidence.

1. Confirm the scope. Identify the API endpoint, the CICS transaction ID, affected users, the timeout threshold, and the exact start time.
2. Reconstruct the path. Map the request from the API gateway through the integration layer, such as IBM Z^®/OS Connect, to the CICS transaction and programs, the Db2^® packages it runs, the MQ queues and channels it uses, and any downstream service.
3. Align clocks and identifiers. Normalize timestamps across systems and use correlation IDs wherever they exist.
4. Find where elapsed time first departs from baseline. Compare API gateway latency, CICS response time, Db2^® elapsed time, and MQ wait time against normal behavior for the same period.
5. Classify the wait. Decide whether the delay looks like compute, database, messaging, network, locking, or a downstream dependency.
6. Check what changed. Review recent deployments, configuration changes, batch schedules, Db2^® rebinds, and volume shifts.
7. Correlate before you act. Look for at least two independent signals that point to the same cause, then route the incident to the owning team with the evidence attached.

How do you tell whether CICS is causing the timeout?

Evidence points more strongly toward CICS when task response time rises inside the region while time spent waiting on Db2^®, MQ, or remote calls stays flat.

CICS monitoring facility (CMF) performance records, written as System Management Facilities (SMF) type 110 records, break elapsed time into dispatch, CPU, and suspend components. Look for tasks queuing at the maximum tasks (MXT) limit or a transaction class limit, short-on-storage conditions, a looping program burning CPU, or hung tasks that never complete. Rising CICS response time on its own isn't conclusive, though. A CICS task waiting on Db2^® also shows longer response time, so check where the suspend time actually goes.

How do you tell whether IBM Db2^® is causing the timeout?

IBM Db2^® becomes the likely cause when SQL elapsed time or lock and latch suspension time grows enough to explain most of the delay.

Db2^® accounting data shows time spent inside Db2^® and how much of it went to suspensions such as lock waits, I/O, and latch contention. Watch for lock timeouts and deadlocks (SQLCODE -911 or -913), contention with batch jobs running against the same tables, access path changes after a rebind or statistics refresh, and thread limits. Keep one caveat in mind: a slow query may be the victim of another workload's locks, not the source of the problem.

How do you tell whether IBM MQ is causing the delay?

IBM MQ becomes the likely cause when messages sit on queues longer than normal or when the channel carrying them stops moving.

Check queue depth trends, the age of the oldest message, channel status (such as retrying or stopped), and whether MQGET wait intervals expire before replies arrive. A reply queue that isn't draining often means the consuming application stopped or slowed. That's why a deep queue doesn't always mean MQ is at fault. The consumer may be stuck waiting on Db2^®.

What evidence points to CICS, Db2^®, MQ, or the network?

The strongest evidence is a delay that appears first in one layer and explains most of the end-to-end elapsed time. Use this comparison as a starting point, not a verdict.

Why is cross-system correlation more useful than another alert?

Another alert tells you a threshold crossed. Cross-system correlation tells you how the signals relate, which is what you need to act.

During a Sev-1, teams rarely lack data. They lack a shared picture. The cloud team sees API failures, the mainframe team sees Db2^® lock waits, and both investigate separately. Adding alerts often adds noise. Assembling context across the transaction is what shortens MTTR, because it turns scattered clues into one line of reasoning everyone can verify.

Where can AI help with mainframe incident diagnosis?

AI helps most with the work that slows humans down: gathering evidence, correlating telemetry across domains, matching current symptoms to past incidents, ranking likely causes with supporting evidence, summarizing dependencies, and suggesting the next diagnostic step.

AI-assisted diagnosis is the use of AI to collect, correlate, and explain evidence so a human can decide what to do. Autonomous remediation is the use of AI to change production systems without that human decision. These are separate capabilities with separate risk profiles. An AI that ranks Db2^® lock contention as the probable cause should show the evidence and stop there unless policy explicitly authorizes the next step and a person approves it.

Leaders are already drawing this line. According to the Mainframe AI Study conducted by Hanover Research on behalf of Rocket Software in June 2026, based on a survey of 250 financial services IT leaders: 41% said they'd use agentic AI to generate ranked likely root causes with evidence; 91% rated AI-driven diagnostics as credible for reducing MTTR; and 43% identified over-dependence on prompt quality and user expertise as a top challenge with conversational AI tools. Generic chatbots answer the questions you already know to ask. Useful diagnosis surfaces the questions you should be asking.

¿Dónde encaja Rocket EVA ?

Rocket^® EVA^™ fits at the point where teams need operational context assembled across systems and actions kept under governance.

Rocket EVA lets operators ask natural language questions about operational and incident status, dependencies, and root cause correlations. According to Rocket Software's product documentation, Rocket EVA queries data across sources including Db2^®, SMF, TMON/SDSF, and workload manager systems.Rocket EVA also integrates with ticketing systems to learn organization-specific incident resolution practices; Jira is cited as one supported example in Rocket Software's published materials. That combination can help less-experienced staff investigate without waiting for a senior specialist.

According to Rocket Software's published product materials, Rocket EVA is built on an open tool layer that uses Model Context Protocol (MCP), designed to work alongside existing monitoring and service management tools. Rocket Software also describes Rocket EVA as supporting governed operations, including human oversight and approval workflows, though the specific implementation of identity controls, role-based access, and audit trail capabilities should be confirmed against current product documentation before publication. That commitment to human accountability at each step supports a modernization-without-disruption approach: better operational diagnosis on top of the infrastructure you already run.

Rocket is a trademark of Rocket Software, Inc. IBM and Db2^® are trademarks of International Business Machines Corporation.