DBCTL error scenarios

DBCTL errors can occur in a variety of ways, such as during connection to DBCTL, or during PSB scheduling. Use dumps and trace messages to help diagnose the error for fixing.

Connection to DBCTL has failed to complete

In this situation, the DRA may be in a wait state because you attempted to connect CICS® to DBCTL using the CDBC transaction, but the connection process failed to complete.

Connection to DBCTL using the CICS-supplied transaction CDBC takes place in two phases:

In phase 1, CDBC passes the request for connection to IMS and returns.
In phase 2, IMS processes the request asynchronously and returns to CICS when connection is complete.

To discover where the problem occurred, try to find out how far the connection attempt has progressed by taking either of the following actions:

Press PF2 on the CDBC menu panel to refresh this display, as described in CDBC transaction for connect and disconnect.
Use the CDBI inquiry panel, as described in CDBI transaction for inquiry.

Phase 1 fails to complete

If the connection is in phase 1, the following message is issued:

DFHDB8291 I DBCTL CONNECT PHASE 1 IN PROGRESS

It is very unlikely that a wait will occur during this phase, unless there is a problem with the CICS transaction.

Phase 2 fails to complete

If the connection is in phase 2, the following message is issued:

DFHDB8292 I DBCTL CONNECT PHASE 2 IN PROGRESS

If phase 2 fails to complete, the failure is associated with IMS. Here are some possible causes of this failure:

The DRA startup table is pointing to the wrong system because the DBCTL subsystem ID is incorrect. If this is so, CICS issues a WTO message:
```
SUBSYSTEM xxxx NOT ACTIVE.  REPLY WAIT OR CANCEL
```
where xxxx is the subsystem ID indicated on the CDBC panel.
See Defining the IMS DRA startup parameter table for information on specifying the DBCTL subsystem ID.
DBCTL has been initialized, but no restart command has been issued. Remember that DBCTL needs a restart command unless you are using AUTO start. See Connecting to DBCTL: overview and Restarting DBCTL for information on restarting DBCTL and on the implications of different restart options.

If neither situation applies

If neither of these situations applies, the problem is in IMS. See Diagnosis in IMS product documentation for further guidance.

For an example of the trace entries produced by CICS for a successful connection to DBCTL, see Example: Trace entries produced when CICS connects to DBCTL.

Disconnection from DBCTL failed to complete

The DRA might be in a wait state because you attempted to disconnect CICS from DBCTL using the CDBC transaction, but the disconnection process failed to complete.

For an example of the trace entries produced by CICS for a successful disconnection from DBCTL, see Example: Trace entries produced when CICS disconnects from DBCTL.

When you use CDBC to disconnect from DBCTL, it invokes another CICS transaction, CDBT. CDBT makes the disconnection request to DBCTL, and is suspended by CICS while DBCTL services the request asynchronously.

If disconnection fails to complete, you can inquire on CDBT by using CEMT INQ TASK to see how far disconnection has progressed. You might find that CDBT is waiting on resource name DLSUSPND and resource type DBCTL, which means the request is being processed by DBCTL. For an illustrated example, see the description of CEMT INQ TASK in Purging a transaction that is using DBCTL.

If CDBT is waiting on DLSUSPND, the next step depends on whether the disconnection requested was orderly or immediate. To find out, you can use the CDBI inquiry panel, as described in CDBI transaction for inquiry.

If you requested orderly disconnection, DBCTL is probably waiting for a task that is issuing many DL/I requests, or for a conversational task, perhaps one that is waiting for input from an unattended terminal.
If necessary, you can override an orderly disconnection by requesting immediate disconnection, in which case the process should conclude at once. However, be aware that immediate disconnection can cause indoubt UOWs, and leave database records unavailable to other CICS systems using that DBCTL until it is reconnected, as described in Deciding whether to use orderly or immediate disconnection.
If you requested immediate disconnection, and it has not taken place, an unexpected wait in IMS has probably occurred. For further guidance, see Diagnosis in IMS product documentation.

If CDBT is not waiting on DLSUSPND, this indicates a problem in CICS.

If CDBT does not end automatically after DBCTL has terminated, you can attempt to force purge the transaction as a last resort.

Failures during PSB scheduling

Use /DISPLAY PROGRAM psbname to check that the application control block (ACB) is valid.
A status of invalid means that the PSB was not defined during IMS system generation. A status of notinit means that the ACB is not in the ACBLIB. A status of stopped means an error has caused DBCTL to stop the PSB, or that a /STOP command has been issued for the PSB. Investigate the cause of this error. When the problem is resolved, use /START PROGRAM psbname to start the PSB again.
Use /DISPLAY DATABASE dbname to check that the databases are valid.

For examples of trace entries produced by CICS during PSB scheduling (both successful and failed), see Example: Trace entries produced for successful PSB schedule and Example: Trace entries produced for failed PSB schedule.

Failures during DL/I request processing

The DRA might enter a wait state because you have a CICS task in a wait state.

If a task appears to hang, query it using CEMT INQ TASK, as for any CICS task. If a task is waiting on a resource name of DLSUSPND and resource type DBCTL, the task has made a DL/I request and has been suspended in CICS while DBCTL services that request. If repeated use of CEMT INQ TASK shows the task still waiting on DLSUSPND, it has hung in DBCTL. If you want to purge the task, you must use DBCTL operator commands to do so. See Purging a transaction that is using DBCTL for an illustrated example of using CEMT INQ TASK and the relevant DBCTL operator commands in this way.

If the task is not waiting on DLSUSPND, this might indicate a problem in CICS.

For an example of the trace entries produced by CICS during DL/I request processing, see Example: Trace entries produced for a DL/I request. For an example of the trace entries produced by DBCTL during DL/I request processing, see Trace entries produced by DBCTL.