Database control (DBCTL)

Design overview

The CICS® support that enables connection to DBCTL, via the database resource adapter (DRA), is based on the CICS resource manager interface (RMI), also known as the task-related user exit interface. However, because it is necessary to provide compatibility with the existing CICS-DL/I implementation (in terms of link-edit stubs, API return codes, and so on), a limited amount of support within CICS itself is provided, but there are no DBCTL release dependencies within the CICS modules.

The main components of the CICS-DBCTL interface are shown in Figure 1.

The connection process (CICS-DBCTL)

The CICS-DBCTL connection process relies on the following components:

CICS-DBCTL connection and disconnection programs

These programs are used for establishing and terminating the connection with the DRA. In order to initialize, terminate, and inquire on the status of the interface, a set of four programs is available:

• Menu program (DFHDBME)
• Connection program (DFHDBCON)
• Disconnection program (DFHDBDSC)
• Inquiry program (DFHDBIQ)

CICS-DBCTL control program (DFHDBCT)

This program is responsible for resolving indoubt units of work after a CICS or DBCTL failure. It also outputs messages when DBCTL notifies CICS of a change in the status of the CICS-DBCTL interface. When the CICS disconnects from DBCTL, the control program is responsible for invoking the disable program which performs clean up. For details, see Control program (DFHDBCT).

DRA control exit (DFHDBCTX)

This exit is invoked by the DRA, when connection has been established with the DBCTL address space, to initiate the resynchronization process, that is, to initiate the resolution of indoubt units of work. It is also invoked to handle cases where connection to DBCTL cannot be achieved or when the connection has failed. For details, see DRA control exit (DFHDBCTX).

DBCTL user-replaceable program (DFHDBCTX)

This program is invoked whenever CICS successfully connects to DBCTL and whenever CICS disconnects from DBCTL. For details, see DBCTL user-replaceable program (DFHDBUEX).

Disable program (DFHDBDI)

This program is invoked when CICS disconnects from DBCTL. It performs clean up, which includes disabling the adapter.

The DBCTL call processor program (DFHDLIDP)

For DBCTL, DFHDLIDP invokes the CICS RMI to pass control to DBCTL. The program issues an RMI call to DBCTL and to maintain compatibility with the existing CICS-DL/I interface in areas such as application program return codes, and so on. For details, see The DBCTL call processor program (DFHDLIDP).

The interface layer

The interface layer includes the following components:

The adapter (DFHDBAT)

The adapter’s primary responsibility is interfacing the RMI and DRA parameter lists. Other responsibilities include the issuing of DRA initialization and termination calls, when invoked by the CICS connection and disconnection programs, and the management of CICS tasks, to effect an orderly shutdown of the CICS-DBCTL interface. For details, see Adapter (DFHDBAT).

DRA suspend and resume exits

These exits are invoked by the DRA to suspend and resume a CICS task while a DL/I call is processed by DBCTL. For details, see DRA suspend and resume exits (DFHDBSPX and DFHDBREX).

Adapter exits

There are four exits for use by the adapter:

• The statistics exit (DFHDBSTX)
• The token exit (DFHDBTOX)
• The monitoring exit (DFHDBMOX)
• The status exit (DFHDBSSX)

For details, see Adapter exits (DFHDBSTX, DFHDBTOX, DFHDBMOX, and DFHDBSSX).

DBCTL PSB scheduling and termination

When a CICS task requests the scheduling of a DL/I PSB by means of an EXEC DLI SCHEDULE request or DL/I PCB call, and the request is for a DBCTL PSB, control is passed to DFHDLIDP.

DBCTL PSB termination is performed during the syncpoint when the resource manager interface (RMI) communicates with DBCTL.

Shutdown of the CICS-DBCTL interface during CICS termination

The CICS-DBCTL interface is closed down during CICS termination. This should avoid the possibility of causing DBCTL to terminate with a U113 abend because of CICS terminating while DL/I threads are running on its behalf in DBCTL. To provide the support, there is an extension to the RMI to invoke active adapters at CICS termination.

If CICS termination hangs because the CICS-DBCTL interface does not close down, the operator should type in a /DISPLAY ACTIVE command on the DBCTL console and identify the threads corresponding to the CICS system being terminated. This is possible because the threads’ recovery tokens, which are displayed, start with the CICS applid. The operator should then issue /STOP THREAD requests for each thread.

Control blocks

The following diagram shows the major control blocks used to support the CICS-DBCTL interface:

The DL/I interface parameter list (DLP) is described in DL/I interface parameter list (DLP).

The DBCTL global block (DGB) is acquired, from storage above the 16MB line, when the CICS-DBCTL interface is first initialized. It lasts for the remainder of the CICS execution.

The DBCTL scheduling block (DSB) is acquired, from storage above the 16MB line, when a task issues a PSB schedule request to DBCTL; that is, the PSB used does not appear in the remote PDIR. The DSB is freed at task termination.

Modules

Exits

Reference