CICS Threadsafe Support

CA IDMS is enhanced with CICS threadsafe support that allows threadsafe application programs to use multiple open TCBs while accessing CA IDMS.
Threadsafe Concepts
CICS Transaction Server for z/0S (CTS) provides a method for multiple CTS transactions to run simultaneously on separate TCBs. Application programs that are eligible to run in this mode are described as threadsafe. For more information on the CTS threadsafe operation, see the appropriate IBM documentation. A brief overview of this IBM feature as it relates to the CA IDMS interface is described in the next section.
Historically, all CICS application programs ran on the same TCB, which allowed only one program task to execute at any given instant. While multiple tasks could be active, only one task could execute instructions on a CPU. Under CTS, IBM has introduced the concept of threadsafe application programs that can be run on open TCBs, thus allowing multiple programs to execute simultaneously on different CPUs.
A program that is declared with the CONCURRENCY(THREADSAFE) attribute is considered to be eligible to run on an open TCB, but this attribute alone is not enough to cause the program to do so. Various conditions exist that cause a threadsafe program to execute on an open TCB. Three of the most common cases are the following:
  • Define an application program with the API(OPENAPI) attribute. This attribute is only available in CTS V3.1 and later.
  • Invoke a Task Related User Exit (TRUE) that has been enabled with the API(OPENAPI) attribute.
  • Access a DB2 database using DB2 Version 6 or later. This is a special instance of the previous case because DB2 executes as a TRUE exit.
When a task begins to run on an open TCB, it continues to run until one of the following occurs:
  • A non-threadsafe command is executed
  • An EXEC CICS RETURN is made to a non-threadsafe program
  • A particular point is reached during CICS task termination processing
A threadsafe command is one which can be executed on an open TCB. A program defined as threadsafe can issue a non-threadsafe command. However, issuing a non-threadsafe command causes the task to be switched to run on the QR (single-threaded) TCB. This can cause performance degradation, particularly if a lot of TCB switching is done.
If a threadsafe program defined with API(CICSAPI) is switched to the QR TCB, it stays there unless another OPENAPI TRUE exit is invoked. If a threadsafe program defined with API(OPENAPI) is switched to the QR TCB, it switches back to the open TCB when control is returned to the application program after execution of the non-threadsafe command.
CA IDMS Support for Threadsafe Applications
The CA IDMS interface modules that run in a CTS region have been enhanced to be threadsafe. Threadsafe application programs, that is, programs defined with the CONCURRENCY(THREADSAFE) attribute can use this enhancement to obtain increased throughput.
An application program that is running on an open TCB can access CA IDMS without switching to the single-threaded QR TCB. A new option, TRUEAPI, is provided to allow the first CA IDMS access by a task to force a switch to an open TCB. If the interface has been called by a program defined as threadsafe, the program continues to run on the open TCB after return from the CA IDMS call. For more information on the TRUEAPI option, see IDMSINTC.
CTS has rules and guidelines on whether an application program can or should be defined with CONCURRENCY(THREADSAFE) or API(OPENAPI) attributes or both. Before defining your own programs as THREADSAFE or OPENAPI, be sure to consult the appropriate IBM documentation.
The use of CA IDMS with an otherwise threadsafe program does not cause integrity problems and can provide significant performance improvement. Depending on the nature of the application, however, it may not improve performance and could conceivably cause performance degradation. In addition, if a client-written application program is declared to be threadsafe and the program itself violates the rules for threadsafe programs, the results are unpredictable.
A few cases exist where the CA IDMS interfaceissues CICS commands that force a switch to the QR TCB. For more information, see IDMSINTC Interface Considerations.
IDMSINTC Interface Considerations
You can enter the IDMSINTC interface program using one of the following methods:
  • Through the PLT or by invocation of a transaction that starts the IDMSINTC interface. By invoking IDMSINTC in this way, it is not threadsafe, so the program cannot be defined as THREADSAFE. See the sample definition of PROGRAM(IDMSINTC) in member CICSCSD in the installed CA IDMS source library.
  • Through a branch entry from the application program using the IDMSCINT stub program. This entry functions as an extension of the calling program with the same program attributes. This includes the THREADSAFE and OPENAPI attributes.
Except for a few cases, discussed in Non-threadsafe Instructions, the IDMSINTC interface does not issue any non-threadsafe commands. Therefore, if IDMSINTC is entered on an open TCB, it stays on the open TCB throughout its execution and return to the application program.
When a task makes its first CA IDMS call, IDMSINTC invokes the CA IDMS TRUE exit. This exit is always enabled with the THREADSAFE attribute. The TRUEAPI=OPEN parameter is provided on the CICSOPT macro that causes the exit to also be enabled with the OPENAPI attribute. For more information on the TRUEAPI parameter, see
If TRUEAPI=OPEN is specified, the first CA IDMS call in each task causes a switch to an open TCB. If the application program is defined as threadsafe, the interface continues to execute on that open TCB through its return to the application program.
Non-threadsafe Instructions
A few cases exist where invocation of the CA IDMS interface from an application program causes a non-threadsafe instruction to be issued. If the application program is defined as THREADSAFE, but not OPENAPI, the interface continues to execute on the QR TCB through return to the application program. If the application program is defined as OPENAPI, CICS switches to the QR TCB during execution of the non-threadsafe instruction and back to the open TCB after completion of the instruction. The interface continues to run on the open TCB through return to the application program.
The following cases can cause a non-threadsafe instruction to be issued:
  • If the CICSOPT macro specifies a value other than IMMEDIATE on the TIMEOUT parameter, an EXEC CICS START TRANSACTION is issued at task termination. This is not an important performance consideration because there will be no return to an application program, and CICS always switches to the QR TCB at some point during task termination.
  • If a ROLLBACK command is issued when AUTOCMT=ON is in effect, an EXEC CICS SYNCPOINT ROLLBACK is issued.
  • Certain error conditions can cause a message to be written using an EXEC CICS WRITEQ TD command. These conditions are rare in a production system.
  • If DEBUG=ON is specified in the CICSOPT macro or IDMSDBUG=ON is specified as a SYSIDMS runtime parameter, various information is written using the EXEC CICS WRITEQ TD command. These options are usually used only in special situations when Technical Support personnel need diagnostic information to resolve a problem. For more information on using an alternative parameter value of DEBUG=QTS, see
    CICSOPT syntax
CA IDMS Applications Which Must Not Be Declared Threadsafe
Some CICS application programs that access CA IDMS are not threadsafe. This can be the case even if these programs do not violate any of the restrictions of CICS threadsafe processing. Unpredictable results can occur if such a program is defined as THREADSAFE to CICS.
The limitations are as follows:
  • Application programs that access CA IDMS via an IDMSINTL interface are not threadsafe.
  • An early version of the release 12.0 IDMSCINT macro did not have the SSC12 parameter. An IDMSCINT application stub program compiled with this version of the macro can be entered from an application program that uses either a R10.2-format Subschema Control (with 16-character names) or a R12.0-format Subschema Control (with 18-character names). Any such application program is not threadsafe.
    Later versions of the IDMSCINT macro that do contain the SSC12 parameter do not cause a program to become non-threadsafe. If a program is compiled with SUBSCHEMA-NAMES LENGTH IS 18, it must be linked with an IDMSCINT module that was assembled specifying SSC12=YES.
    If an application program is otherwise threadsafe, but it has been linked with an early R12.0 IDMSCINT module, the program can be declared threadsafe if it is relinked replacing the old IDMSCINT module with one created with a new IDMSCINT macro.
UCF Front-end ( UCFCICS) Considerations
The UCF Front-end program does not violate any threadsafe rules and can be declared as a THREADSAFE or OPENAPI program. It does, however, issue various non-threadsafe commands, such as terminal I/O commands. Therefore, for best performance, it should be defined with CONCURRENCY(QUASIRENTRANT).
Distributed Processing with UDASCIC Considerations
The distributed processing program created with the #UDASCIC macro rarely issues a non-threadsafe command and is a good candidate to declare as a THREADSAFE or OPENAPI program. However, this program does issue a non-threadsafe command when a 1473 Error-Status is received from the CA IDMS interface because of a MAXERUS condition on the CA IDMS central version. In this case, the program waits by continuing to issue EXEC CICS DELAY INTERVAL(1) commands until the condition is alleviated or 100 attempts have been made.
CICS Abort Session Program Considerations
The CICS Abort Session Program is created by compiling the #UCFCICZ program and can be declared as a THREADSAFE and OPENAPI program.
The #UCFCICZ macro generates some code that is not compliant with the recommended usage with CICS Transaction Server. This code can cause problems with applications that are associated with a bridge facility. To provide compatibility with previous methods of calling #UCFCICZ from CICS error programs, two new parameters are added to the #UCFCICZ macro: PASSVAL and BRIDGE. To prevent the #UCFCICZ macro from issuing non-threadsafe commands, we recommend that you compile it with the PASSVAL=TERMID parameter.
For more information, see CICS Abort Session Program.
IDMSRSYN Resynchronization Program Considerations
IDMSRSYN is threadsafe, but because it issues non-threadsafe commands, it should not be defined as OPENAPI.