Enabling CICS IMS applications to use the open transaction environment (OTE) through threadsafe programming
The CICS® IMS attachment facility includes a CICS IMS database adapter, DFHDBAT, that is invoked when an application program makes an IMS request. It manages the process of acquiring a thread connection into IMS, and of returning control to the application program when the IMS processing is complete.
About this task
In the OTE, if the 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 IMS request, the application program runs on the CICS main TCB, the QR TCB. When it makes an IMS request and invokes the TRUE, control passes to the L8 TCB, and IMS processing is carried out. On return from IMS , 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 IMS applications decreases usage of the QR TCB, and avoids TCB switching. An ideal CICS IMS 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 IMS request, and then continues to run on the L8 TCB through any amount of IMS requests and application code, requiring no TCB. This situation produces a significant performance improvement where an application program issues multiple IMS calls. If the application program does not issue many IMS 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 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.
- CICS must be connected to IMS Version 12 or later.
- 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 IMS 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 IMS 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 GLUEs on the execution path used by the application must be coded to threadsafe standards and defined to CICS as threadsafe (for CICS IMS 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 IMS 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 IMS 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 IMS application would occur if your program used a non-threadsafe user exit program and a non-threadsafe EXEC CICS command after every IMS request. In particular, the use of a non-threadsafe exit program on the CICS-IMS 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 IMS.
| Program's concurrency attribute | CICS IMS TRUE operation | Effect |
|---|---|---|
| QUASIRENT | Threadsafe and open API | Application program runs under the CICS QR TCB. TRUE runs under an L8 TCB, and IMS requests are executed under the L8 TCB. CICS switches to and from the CICS QR TCB and the L8 TCB for each IMS request. |
| THREADSAFE | Threadsafe and open API | OTE exploitation. TRUE runs under an L8 TCB, and IMS 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) | Threadsafe and open API | OTE exploitation. TRUE runs under an L8 TCB, and IMS requests are executed under the L8 TCB. The application program runs on the L8 TCB from the start. The program always uses an L8 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) | Threadsafe and open API | OTE exploitation. Not preferred for user key CICS-IMS applications (and when storage protection is active), as it causes switching from the L9 TCB to the L8 TCB and back again for every IMS request. |
- CICS must be connected to IMS Version 12 or later.
- FORCEQR must not be set to YES.
- The CICS IMS 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 IMS 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 IMS application must use only threadsafe TRUEs or GLUEs. If any non-threadsafe exits are used, this forces a switch back to the QR TCB.