Enabling CICS Db2 applications to use OTE through threadsafe programming

The CICS® Db2® attachment facility includes a CICS Db2 task-related user exit (TRUE), DFHD2EX1, that is invoked when an application program makes an SQL request. It manages the process of acquiring a thread connection into Db2, and of returning control to the application program when the Db2 processing is complete.

About this task

The CICS Db2 attachment facility uses the OTE to enable the CICS Db2 TRUE to invoke and return from Db2 without switching TCBs. In the OTE, the CICS Db2 TRUE is automatically enabled using the REQUIRED option (but without the OPENAPI option, thereby meaning CICSAPI) on the ENABLE PROGRAM command during connection processing. This enables it to receive control on any type of key8 open TCB (an L8 or X8 or T8 TCB). Typically its an L8 TCB, but an X8 TCB is used for xplink C programs, and a T8 TCB used if its a Java program. Requests to Db2 are also issued on the open TCB, so it acts as the thread TCB, and no switch to a subtask TCB is needed.

In the OTE, if for example a cobol user application program that invoked the TRUE conforms to threadsafe coding conventions and is defined to CICS as threadsafe, it can also run on the L8 TCB. Before its first SQL request, the application program runs on the CICS main TCB, the QR TCB. When it makes an SQL request and invokes the TRUE, control passes to the L8 TCB, and Db2 processing is carried out. On return from Db2, if the application program is threadsafe, it now continues to run on the L8 TCB.

Programs defined with CONCURRENCY(REQUIRED) run on an open TCB from the start of the program. For CICSAPI programs, CICS uses an L8 open TCB regardless of the execution key of the program. For OPENAPI programs, CICS uses an L9 TCB if EXECKEY(USER) is set and an L8 TCB if EXECKEY( CICS ) is set.

Where the correct conditions are met, the use of open TCBs for CICS Db2 applications decreases usage of the QR TCB, and avoids TCB switching. An ideal CICS Db2 application program for the OTE is a threadsafe program, containing only threadsafe EXEC CICS commands, and using only threadsafe user exit programs. An application like this moves to an L8 TCB when it makes its first SQL request, and then continues to run on the L8 TCB through any amount of Db2 requests and application code, requiring no TCB switching. This situation produces a significant performance improvement where an application program issues multiple SQL calls. If the application program does not issue many SQL calls, the performance benefits might not be as significant.

If the execution of the program involves any actions that are not threadsafe, CICS switches back to the QR TCB at that point. Such actions are non-threadsafe CICS requests issued by the program, the use of non-threadsafe dynamic plan exits, the use of non-threadsafe TRUEs, and the involvement of non-threadsafe global user exits (GLUEs). Switching back and forth between the open TCB and the QR TCB is detrimental to the performance of the application.

In order to gain the performance benefits of the OTE for CICS Db2 applications, you must meet the following conditions:
  • CICS must be connected to a supported version of Db2. For details of the Db2 releases that are supported and the APARs that must be applied, see https://www.ibm.com/support/docview.wss?uid=swg27020857.
  • The system initialization parameter FORCEQR must not be set to YES. FORCEQR forces programs that are defined as threadsafe to run on the QR TCB, and it might be set to YES as a temporary measure while problems that are connected with threadsafe-defined programs are investigated and resolved.
  • The CICS Db2 application must have threadsafe application logic (that is, the native language code in between the EXEC CICS commands must be threadsafe), use only threadsafe EXEC CICS commands, and be defined to CICS as threadsafe. Only code that has been identified as threadsafe is permitted to execute on open TCBs. If your CICS Db2 application is not defined as threadsafe, or if it uses EXEC CICS commands that are not threadsafe, TCB switching takes place and some or all of the performance benefits of OTE exploitation are lost.
  • Any dynamic plan exits used by the CICS Db2 attachment facility must be coded to threadsafe standards and defined to CICS as threadsafe. The default dynamic plan exit DSNCUEXT, which is started as a CICS user-replaceable program, is not defined to CICS as threadsafe, but the alternative CICS-supplied sample dynamic plan exit DFHD2PXT is defined as threadsafe. See Dynamic plan exits for more information.
  • Any GLUEs on the execution path used by the application must be coded to threadsafe standards and defined to CICS as threadsafe (for CICS Db2 applications. In particular the GLUEs XRMIIN and XRMIOUT).
  • Any other TRUEs used by the application must be defined to CICS as threadsafe, or as OPENAPI.

See Threadsafe programs for information about how to make application programs and user exit programs threadsafe. By defining a program to CICS as threadsafe, you are only specifying that the application logic is threadsafe, not that all the EXEC CICS commands included in the program are threadsafe. CICS can ensure that EXEC CICS commands are processed safely by switching to the QR TCB for those commands not yet converted that still rely on quasi-reentrancy. In order to permit your program to run on an open TCB, CICS needs you to guarantee that your application logic is threadsafe.

The EXEC CICS commands that are threadsafe, and so do not involve TCB switching, are indicated in the command syntax diagrams in the description of the API and SPI commands.

If a user application program in the OTE is not defined as threadsafe, the CICS Db2 TRUE still runs on an L8 TCB, but the application program runs on the QR TCB throughout the task. Every time the program makes an SQL request, CICS switches from the QR TCB to the L8 TCB and back again, so the performance benefits of the OTE are negated. The maximum TCB switching for a CICS Db2 application would occur if your program used a non-threadsafe user exit program and a non-threadsafe EXEC CICS command after every Db2 request. In particular, the use of a non-threadsafe exit program on the CICS-Db2 mainline path (for example, a program that is enabled at XRMIIN or XRMIOUT) causes more TCB switching than the level that is experienced when CICS is connected to earlier versions of Db2.

The table shows what happens when application programs with different concurrency attributes invoke the CICS Db2 TRUE. We shall assume it is not an xplink C program nor a Java program, so an L8 TCB is used.
Table 1. Combinations of application programs and the CICS Db2 TRUE
Program's concurrency attribute CICS Db2 TRUE's operation Effect
QUASIRENT Runs on an L8 TCB Application program runs under the CICS QR TCB. TRUEs run under an L8 TCB, and Db2 requests are executed under the L8 TCB. CICS switches to and from the CICS QR TCB and the L8 TCB for each Db2 request.
THREADSAFE Runs on an L8 TCB OTE exploitation. TRUEs run under an L8 TCB, and Db2 requests are executed under the L8 TCB. The application program also runs on the L8 TCB when control is returned to it. No TCB switches are needed until the task terminates, or if it issues a non-threadsafe CICS request which forces a switch back to the QR TCB.
REQUIRED with API(CICSAPI) Runs on an L8 TCB OTE exploitation. TRUEs run under an L8 TCB, and Db2 requests are executed under the L8 TCB. The application program runs on the L8 TCB from the start. The program always uses an L8 TCB irrespective of the execution key of the program. No TCB switches are needed until the task terminates, or if it issues a non-threadsafe CICS request which forces a switch back to the QR TCB and then a switch back afterward to the L8 TCB.
REQUIRED with API(OPENAPI) Runs on an L8 TCB OTE exploitation. Not preferred for user key CICS-Db2 applications (and when storage protection is active), as it causes switching from the L9 TCB to the L8 TCB and back again for every Db2 request.
In summary, to gain the performance benefits of the OTE:
  • CICS must be connected to Db2.
  • FORCEQR must not be set to YES.
  • The CICS Db2 application must have threadsafe application logic (that is, the native language code in between the EXEC CICS commands must be threadsafe). If the application logic is not threadsafe, the program must be defined as CONCURRENCY(QUASIRENT), and so must operate on the CICS QR TCB. In this case TCB switching occurs for every Db2 request, even if the TRUE is running on an open TCB.
  • A threadsafe application can be defined to CICS as CONCURRENCY(THREADSAFE) API(CICSAPI) or CONCURRENCY(REQUIRED) API(CICSAPI). The setting to use depends on how many non-threadsafe EXEC commands the program uses. If there are many non-threadsafe CICS commands the program is best defined as CONCURRENCY(THREADSAFE). If the program has few or no non-threadsafe CICS commands, then CONCURRENCY(REQUIRED) can be used. Programs defined with CONCURRENCY(REQUIRED) have the benefit of starting on an L8 open TCB, but every non-threadsafe CICS command results in two TCB switches.
  • The CICS Db2 application must use only threadsafe or open API dynamic plan exits, TRUEs, and GLUEs. If any non-threadsafe exits are used, this forces a switch back to the QR TCB.
If all these conditions are met, you can gain the performance benefits of the OTE.