The sample exit programs, DSNCUEXT and DFHD2PXT

Two sample assembler language exit programs, DSNCUEXT and DFHD2PXT, are supplied in both source and object code. The programs are functionally identical, but the CICS®-supplied program definition for DSNCUEXT specifies CONCURRENCY(QUASIRENT), while the CICS-supplied program definition for DFHD2PXT specifies CONCURRENCY(THREADSAFE).

There are two sample programs because when CICS exploits the open transaction environment (OTE), the CICS Db2® task-related user exit operates as a threadsafe program and can receive control on an open TCB (L8 mode). For further explanation, see Enabling CICS Db2 applications to use OTE through threadsafe programming . If the application program that made the Db2 request is threadsafe, it can also run on the open TCB. In this situation, TCB switching should not be needed.

However, if a dynamic plan exit is used that is defined with CONCURRENCY(QUASIRENT), like DSNCUEXT, this causes a switch back to the QR TCB, incurring an additional cost. Dynamic plan exits that are defined with CONCURRENCY(THREADSAFE) and are coded to threadsafe standards, like DFHD2PXT, can run on the open TCB, and do not incur the additional cost.

Therefore, when CICS is connected to Db2, use DFHD2PXT as your dynamic plan exit rather than DSNCUEXT. Remember that if you add logic that is not threadsafe to the supplied sample program, or issue non-threadsafe CICS commands in the exit, this will cause a switch back to the QR TCB, and the additional cost is incurred. To gain performance benefits by avoiding TCB switching, use a dynamic plan exit that is defined as threadsafe, code logic that is threadsafe, and ensure that the program contains only threadsafe commands.

The object code (load module) for the sample plan exits are included in the SDFHLOAD library. DSNCUEXT is the default dynamic plan exit, and it is invoked as a CICS user-replaceable program. The source code for both sample programs is written in assembler language and supplied in the SDFHSAMP library. The sample programs show how to address the parameter list, but do not change the plan name.

A parameter list is passed to the sample program through a COMMAREA, and has the following format in the Assembler version:
Table 1. Example of a parameter list passed to the DSNCUEXT or DFHD2PXT sample program through a COMMAREA
Assembler version format
CPRMPLAN DS CL8 The DBRM/plan name of the first SQL statement on entry to the sample program. The field can be modified to establish a new plan.
CPRMAUTH DS CL8 The current authorization ID that is passed to Db2 at signon time. This is for information only. Any changes made to it are ignored.
CPRMUSER DS CL4 A user area that is reserved for use by the sample program. The CICS Db2 attachment preserves this field across invocations of the sample program.
CPRMAPPL DS CL8 The name of the application program that issued the SQL call.
  • The Assembler version of the parameter list is shipped as member DSNCPRMA in SDFHMAC library.
  • The COBOL version is DSNCPRMC in SDFHCOB library.
  • The PL/I version is DSNCPRMP in SDFHPLI library.

Before calling the dynamic plan exit, the CICS Db2 attachment facility sets CPRMPLAN to the name of the DBRM set in the parameter list of the first EXEC SQL statement executed in the unit of work. As supplied by CICS , the dynamic plan exits DSNCUEXT and DFHD2PXT do not modify the plan name as input in CPRMPLAN by the CICS Db2 attachment facility, but return immediately, leaving the plan name as that chosen by the CICS Db2 attachment facility.

As a consequence of adding support for JDBC and SQLJ support for Java™ applications for CICS , the CICS-supplied dynamic plan exits have been changed. SQLJ and JDBC require Db2 to produce four DBRMs for each application program to support dynamic change of isolation levels. For JDBC and SQLJ applications, the DBRM name is restricted to seven characters so that the eighth character can be used as a suffix of 1, 2, 3, or 4. Therefore, for JDBC and SQLJ applications you cannot use a default naming convention of program name equals dbrm name equals plan name, because the DBRM name has a suffix of 1, 2, 3 or 4.

For JDBC applications, SQLJ applications, and mixed JDBC and SQLJ applications, the Db2 JDBC driver uses information from the JDBC profile to set the name of the DBRM in the parameter list of the first EXEC SQL statement executed. The first SQL issued always has the DBRM name set to the JDBC base program with the default isolation level appended; that is, by default, DSNJDBC2. For example, if the JDBC profile is generated using pgmname=OTHER, the DBRM name will be OTHER2. If dynamic plan exits are not used, the plan name is obtained from the DB2CONN or DB2ENTRY definition; the plan name in the properties file is ignored.

To support a default naming convention for the IBM® Data Server Driver for JDBC and SQLJ, the CICS-supplied dynamic plan exits DSNCUEXT and DFHD2PXT can detect an input CPRMPLAN name whose first characters are SYSSTAT, SYSLH or SYSLN. If such a plan name is detected, the plan name is changed to DSNJCC (the seventh and eighth characters set to blanks). To use the default dynamic plan exits with Java applications for CICS, bind the multiple DBRMs into a plan called DSNJCC.