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 31:

Figure 31. The major components of the CICS-DBCTL interface
 In the CICS address space are: MENU, CONN, DISC, INQ and CONTROL transactions. User DL/I transactions, with the RMI stub. CICS itself (which has a log). All these can interface with DBCTL through the RMI or exits, the adapter, and DRA (as explained below). In the IMS/ESA address space are: DBCTL (with a log), DL/I, DBRC, and IRLM.

Details of these components are described in the following topics.

Note:
CICS documentation uses the term "connecting and disconnecting from DBCTL". The DRA documentation refers to "initializing and terminating the CICS-DBCTL interface". In general, these two terms are synonymous.

The connection process

Connection and disconnection programs

In order to initialize, terminate, and inquire on the status of the interface, a set of four programs is available:

  1. Menu program
  2. Connection program
  3. Disconnection program
  4. Inquiry program.
Menu program (DFHDBME)

This permits a terminal user to display a menu, which offers the option of connecting and disconnecting from DBCTL.

The menu program passes control to either the connection or the disconnection program, as appropriate, using the COMMAREA to pass any overrides and parameters.

In the case of connection, it offers the ability to supply the suffix of the DRA startup parameter table and the name of the DBCTL region. The DRA startup parameter table contains various parameters, mostly relating to the initialization of the CICS-DBCTL interface, including the name of the DBCTL region and the minimum and maximum number of CICS-DBCTL threads. It also contains the length of time in seconds that the DRA waits after an unsuccessful attempt to connect to DBCTL, before attempting to connect again.

For disconnection, it offers the ability to specify whether an orderly or immediate disconnection from DBCTL is required.

The menu program is intended for use by CICS operators or network controllers, that is, users with special privileges.

BMS maps are used for both the menu and the inquiry programs. It should be noted that the bottom half of the menu screen includes all the items which appear on the inquiry screen, and the values are displayed on entry to the menu program, if they are known. The DRA startup table suffix is not included on the inquiry screen because the DRA startup table contains the application group name which is used for security checking.

After a connection request has been issued, it is possible to issue a disconnection request (orderly or immediate) from the menu program while the connection process is still in progress. After an orderly disconnection request has been issued, it is also possible to issue an immediate disconnection request while the orderly disconnection process is in progress. This has the effect of upgrading the orderly disconnection to an immediate disconnection.

Connection program (DFHDBCON)

This program invokes the adapter requesting connection to DBCTL.

This program can be invoked either from the menu program or from the CICS PLT. It issues an ATTACH request of the CICS control program that later carries out resynchronization of in-doubt units of work with DBCTL. The control program then issues a WAIT request.

The connection program continues by loading, activating (using the EXEC CICS ENABLE command), and then calling the adapter (using a DFHRMCAL request). A set of parameters is passed to the adapter which includes:

As a result of the DFHRMCAL request issued from the connection program, the adapter loads the DRA startup/router module from the CICS STEPLIB library and passes control to it, supplying it with various parameters including the CICS applid, DRA startup parameter table suffix, and DBCTL ID. The DRA startup/router module loads the DRA startup table. It then initiates the processes required to establish the DRA and then returns control to the adapter which, in turn, returns control to the connection program which then terminates. Until this point is reached, any DBCTL requests issued from CICS tasks are rejected by the CICS RMI stub (the DBCTL call processor).

The DRA startup/router module is responsible for establishing the DRA environment, using the parameters specified in the DRA startup table in the CICS STEPLIB library, overridden by any parameters passed to it.

The DRA establishes contact with the DBCTL address space and then invokes the control exit to initiate the resynchronization process.

Disconnection program (DFHDBDSC)

This program invokes the adapter requesting disconnection from DBCTL.

The disconnection program is used to terminate the DRA environment. Two types of disconnection are available:

Orderly disconnection
All existing CICS tasks using DBCTL are allowed to run to completion.
Immediate disconnection
Existing DL/I requests are allowed to complete but no further DL/I requests are accepted.

In both cases a DBCTL U113 abend is avoided. (DBCTL can issue a U113 abend if CICS terminates while there is an active DL/I thread running on its behalf in DBCTL. The thread remains active for the duration of the PSB schedule, but DBCTL would issue a U113 abend if the thread is doing something for the CICS task.)

The disconnection program calls the adapter, using DFHRMCAL, supplying a parameter to indicate the type of termination required.

In the case of immediate disconnection, the adapter issues a DRA TERM call and returns to the disconnection program only when all existing DL/I threads have completed. In the case of orderly disconnection, the adapter assumes responsibility for managing CICS tasks, that is, it continues to accept requests for current tasks using DBCTL until they terminate, but does not allow new CICS tasks to use DBCTL. When the adapter detects that the count of permitted tasks has reached zero, it issues a DRA TERM call.

The disconnection program finally posts the control program to notify it of the fact that the CICS-DBCTL interface has been terminated. The control program then terminates after starting the disable program. The disable program issues a DISABLE command for the adapter, and performs cleanup.

It should be noted that the terminal used to invoke the disconnection program is released after the input to the menu screen has been validated, enabling the terminal operator to use other programs. Any further messages from the disconnection process are generated centrally.

Inquiry program (DFHDBIQ)

This program enables the user to inquire on the status of the interface. It is intended for a wider audience than the menu program; for example, application programmers.

Control program (DFHDBCT)

The control program is invoked in the following circumstances:

Its function in all cases is to issue messages. It then issues a WAIT after every invocation. Also, it has some special functions in three cases:

  1. When contact has been made with DBCTL and resynchronization of in-doubts is required.

    In this case, the control program issues the command:

       EXEC CICS RESYNC ENTRYNAME(adapter)
       IDLIST(DBCTL’s in-doubts) ...

    This causes CICS to create tasks for each in-doubt unit of work. Each task performs resynchronization and then informs the adapter via the CICS syncpoint manager as to whether the task has committed or backed out. The adapter then notifies the DRA on a task basis.

    The following is a list of the possible calls to the adapter from the CICS syncpoint manager:

    Notes:

    1 These items can be issued as a result of a RESYNC request.

    2 These items can be issued as a result of a RESYNC request only.

  2. When /CHECKPOINT FREEZE has been requested.

    In this case, the control program invokes the disconnection program requesting an orderly disconnection from DBCTL. Generally, an orderly disconnection from DBCTL allows CICS tasks already using DBCTL to continue until task termination. However, when a /CHECKPOINT FREEZE has been requested, DBCTL prevents any PSB schedules from taking place. Thus, in this case, some tasks might be terminated before end of task is reached with a ‘DBCTL not available’ return code, if they issue a subsequent PSB schedule request.

  3. When the disconnection program invokes the control program.

    In this case, the control program starts the disable program.

DRA control exit (DFHDBCTX)

The control exit is invoked in the DRA environment in the following circumstances:

DBCTL user-replaceable program (DFHDBUEX)

The DBCTL user-replaceable program, DFHDBUEX, is invoked whenever CICS successfully connects or disconnects from DBCTL. It provides the opportunity for the customer to supply code to enable and disable CICS-DBCTL transactions at these times.

The program runs as a CICS application and can thus issue EXEC CICS requests. The program is invoked with a CICS COMMAREA containing the following parameters:

See the CICS Customization Guide for information about the DFHDBUEX program.

Disable program (DFHDBDI)

The disable program, DFHDBDI, is invoked when CICS disconnects from DBCTL. It performs cleanup, which includes disabling the adapter.

The DBCTL call processor program (DFHDLIDP)

Among the functions of the DBCTL call processor program, DFHDLIDP, are:

Issuing DFHRMCAL requests to the adapter

DL/I requests issued from application programs that have been routed to this module are passed on to the adapter. The DBCTL call processor constructs a register 1 parameter list that includes the DL/I parameter list and a thread token. It then issues a DFHRMCAL request.

It is the responsibility of this module to generate the thread token required by the DRA.

Maintaining return code compatibility

If any calls are made to the RMI before the first part of the connection process has completed, that is, before the DFHDBCON program has received a "successful" response code from the DRA via the adapter, error return codes are set in the task control area (TCA) to indicate that DBCTL is unavailable. These codes are put in the user interface block (UIB) by the DL/I call router program, DFHDLI.

Similarly, the DBCTL call processor informs application programs when DBCTL is no longer available; for example, after a DBCTL abend.

Another function of the call processor is to set up the TCA fields, TCADLRC and TCADLTR, with response and reason codes respectively for the call. This ensures that the application program continues to receive responses indicating normal response, NOTOPEN, and INVREQ conditions, with the appropriate response and reason codes in the corresponding UIB fields, UIBFCTR and UIBDLTR, after NOTOPEN and INVREQ conditions have been raised.

Initiating PC abends

If an ‘unsuccessful’ return code is passed back to CICS as a result of a DBCTL request, indicating that the CICS thread must be abended, the DBCTL call processor issues a PC ABEND, which invokes syncpoint processing to back out changes made to recoverable resources. Various abend codes can be issued. Note that, in the case of a deadlock abend (abend code ADCD) it may be possible to restart the program.

Exception trace entries are output in the case of transaction abends.

Writing CICS messages

For any thread abend in DBCTL, a CICS message is written indicating the abend code passed back to CICS in the field PAPLRETC. Similarly, for any scheduling failures, where the application program receives the UIBRCODE field (UIBFCTR and UIBDLTR fields combined) set to X'0805', the scheduling failure subcode is contained in a CICS message.

The interface layer

Adapter (DFHDBAT)

Control is passed to the adapter via the CICS RMI. It is the responsibility of the adapter to construct the DRA INIT, DRA TERM, and DRA THREAD parameter lists from the RMI parameter list passed to it. It must also transform the DRA parameter list passed back after a DL/I call to the format expected by CICS.

Part of the DRA parameter list requires two tokens to be generated by CICS:

  1. A thread token
  2. A recovery token.

The thread token is generated by the DBCTL call processor, and enables a CICS unit of work to be related to a DBCTL unit of work. It is used by the asynchronous RESUME exit to identify the CICS thread to be resumed after a DL/I call.

The 16-byte recovery token is constructed by concatenating an 8-byte unique CICS subsystem name (the CICS applid) with the 8-byte CICS RMI recovery token (also known as the unit of work ID).

A further responsibility of the adapter is to manage CICS tasks when an orderly termination of the CICS-DRA interface has been requested by means of the CICS termination program. In this case, it continues to accept DL/I requests from CICS tasks currently using DBCTL, but does not allow new CICS tasks to use DBCTL. When the adapter detects that the count of current tasks has reached zero, it issues a DRA TERM call to shut down the interface.

Table 3 summarizes the types of invocations of the adapter code from CICS, and how the adapter reacts to the individual invocation.

Table 4 summarizes the types of invocations of the adapter code from the DRA, and how the adapter reacts to each individual invocation.

Table 5 summarizes the cases when the adapter invokes the adapter exits.

Table 3. CICS-adapter request summary
Invocation Invoker Adapter action
Initialize Connection program Issues DRA INIT
Terminate-Orderly Disconnection program Issues DRA TERM after waiting for CICS-DBCTL tasks to quiesce
Terminate-Fast Disconnection program Issues DRA TERM
PSB Schedule DBCTL call processor Issues THREAD SCHED
DL/I request DBCTL call processor Issues THREAD DLI
Prepare CICS syncpoint manager Issues THREAD PREP
Commit CICS syncpoint manager Issues THREAD COMTERM
Abort CICS syncpoint manager Issues THREAD ABTTERM
Lost To CICS cold start CICS syncpoint manager Issues COLD request
DBCTL should not be in doubt CICS syncpoint manager Issues UNKNOWN request
Task is terminating CICS task manager Issues TERMTHRD
Force Purge Task Control program Issues PURGE THREAD
Orderly CICS Term CICS termination Issues DRA TERM after waiting for CICS-DBCTL tasks to quiesce
Immediate CICS Term CICS termination Issues DRA TERM
CICS is abending CICS termination Issues DRA TERM
CICS has been canceled CICS termination Returns to CICS
Table 4. DRA-adapter request summary
Invocation from the DRA Adapter action
CICS-DBCTL connection is complete Invoke the control exit
MVS SSI has rejected the IDENTIFY request to DBCTL Invoke the control exit
DBCTL has rejected the IDENTIFY request Invoke the control exit
Operator has replied CANCEL to message DFS690A Invoke the control exit
DBCTL has terminated abnormally Invoke the control exit
DRA has terminated abnormally Invoke the control exit
/CHECKPOINT FREEZE has been issued Invoke the control exit
PSB schedule, DL/I, syncpoint, thread termination, thread purge, or interface termination request is to be suspended Invoke the suspend exit
PSB schedule, DL/I, syncpoint, thread termination, thread purge, or interface termination request is to be resumed Invoke the resume exit
Table 5. Adapter exit summary
Circumstances Adapter action
Successful completion of THREAD SCHED request Invoke the monitoring exit
Completion of THREAD COMTERM or THREAD ABTTERM request Invoke the monitoring exit
DRA thread failure Invoke the status exit
Resynchronization request issued from CICS recovery manager Invoke the token exit
CICS orderly or immediate term Invoke the token exit
CICS ABEND Invoke the token exit
Completion of DRA TERM issued as a result of a termination request from disconnection program Invoke the statistics exit
Completion of DRA TERM issued as a result of a CICS orderly termination request Invoke the statistics exit

Suspend exit (DFHDBSPX)

The suspend exit is invoked by the adapter on behalf of the DRA so that a CICS thread can be suspended during the processing of a DL/I call. The suspend exit outputs a trace entry immediately before issuing a WAIT, and a trace entry immediately after it is posted by the resume exit.

The suspend exit is also invoked by the adapter when a disconnection request from the menu is being processed.

Resume exit (DFHDBREX)

The resume exit is invoked asynchronously by the adapter on behalf of the DRA, and it is executed in the DRA environment. It handles both normal resume and abnormal resume after an abend of the thread. The resume exit issues an MVS POST.

When a thread fails, the resume exit is invoked and an ‘unsuccessful’ return code is passed back to the DBCTL call processor, indicating that CICS must issue an abend for that thread (task).

Adapter exits

The following topics describe the adapter exits.

The adapter statistics exit (DFHDBSTX)

The statistics exit is invoked by the adapter when the CICS-DBCTL interface has been terminated by the CICS operator using the menu program to request disconnection from DBCTL. The exit is also invoked by the adapter when CICS is terminated in an orderly way.

The function of the exit is to invoke the CICS statistics domain supplying the data that has been returned from the DRA relating to the individual CICS-DBCTL session.

For a /CHECKPOINT FREEZE command, the exit is not invoked, but the statistics domain is called by DFHCDBCT.

The adapter token exit (DFHDBTOX)

The token exit is invoked by the adapter when a task is encountered which has not been allocated a thread token, that is, it has not been through the DBCTL call processor module. This occurs for resynchronization tasks and for the CICS termination invocation.

The adapter monitoring exit (DFHDBMOX)

The monitoring exit is invoked by the adapter when monitoring data has been returned by DBCTL as a result of a PSB schedule request, and a CICS SYNCPOINT or DLI TERM request. The exit passes the data on to the CICS monitoring domain to update the tasks monitoring information.

The adapter status exit (DFHDBSSX)

The status exit is invoked by the adapter in the event of a DRA thread failure, so that resources owned by the failing thread can be transferred to CICS, which then releases the transferred resources during syncpoint processing.

DBCTL system definition

DBCTL system definition is described in the IMS™ System Definition Reference.

DBCTL PSB scheduling

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.

Database calls

For DBCTL, DFHDLIDP invokes the CICS RMI to pass control to DBCTL.

DBCTL PSB termination

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

System termination

Support is provided to close down the CICS-DBCTL interface 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.

[[ Contents Previous Page | Next Page Index ]]