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:
When the CICS disconnects from DBCTL, the control program is responsible for invoking the disable program which performs cleanup.
The function of this program is to issue 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.
Details of these components are described in the following topics.
In order to initialize, terminate, and inquire on the status of the interface, a set of four programs is available:
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.
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.
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:
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.
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.
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:
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.
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.
In this case, the control program starts the disable program.
The control exit is invoked in the DRA environment in the following circumstances:
The control exit is invoked in the DRA environment whenever contact has been established with DBCTL, whether invoked by the user or due to the DRA automatically reestablishing contact after a DBCTL failure. The control exit receives an input parameter list that includes the DBCTL ID, DBCTL’s list of in-doubt units of work, and the DBCTL RSE name. The control exit posts the control program, which actually performs the resynchronization.
This could occur if the DRA was trying to issue an IDENTIFY request to a DBCTL subsystem that was not running. In this case the control exit sets a response code of ‘0’. The first time in a connection attempt that the DRA receives a ‘0’ response after an MVS SSI failure, the DRA outputs message DFS690A inviting the operator to reply WAIT or CANCEL. On subsequent failures when a response code of ‘0’ is returned, the DRA waits for the length of time specified in the DRA startup table before attempting the IDENTIFY request again.
In this case, the control exit asks the DRA to terminate.
In this case, the control exit notifies the DRA to terminate immediately.
In this case, the control exit invokes the control program and then it asks the DRA to issue an IDENTIFY request to DBCTL.
In this case, it is not possible to access DBCTL from the same CICS session without initializing the CICS-DBCTL interface using the menu program.
Note that /CHECKPOINT FREEZE is the command used to close down a DBCTL subsystem. In this case the control exit invokes the control program which, in turn, invokes the disconnection program requesting an orderly disconnection from DBCTL. The control exit notifies the DRA to wait for a termination request.
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.
The disable program, DFHDBDI, is invoked when CICS disconnects from DBCTL. It performs cleanup, which includes disabling the adapter.
Among the functions of the DBCTL call processor program, DFHDLIDP, are:
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.
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.
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.
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.
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:
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.
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 |
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 |
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 |
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.
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).
The following topics describe the adapter exits.
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 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 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 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 is described in the IMS™ System Definition Reference.
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.
For DBCTL, DFHDLIDP invokes the CICS RMI to pass control to DBCTL.
DBCTL PSB termination is performed during the syncpoint when the resource manager interface (RMI) communicates with DBCTL.
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 ]]