When CICS® applications use DB2® data, the application architecture must take account of design aspects related to the CICS DB2 attachment facility. One of the most important aspects to consider is the relationship between transaction IDs, DB2 plans and packages, and program modules. If any of the program modules uses SQL calls, a corresponding DB2 plan or package must be available. The plan to be used for a transaction ID is specified in the DB2CONN or DB2ENTRY definition for the thread that the transaction uses to access DB2. The plan can be named explicitly, or a plan exit routine can be named that selects the plan name. The plan must include the DBRMs from all modules that could possibly run under this transaction ID. The DBRMs can be bound directly into the plan, or they can be bound as packages and named in a package list in the plan. See Overview: Enabling CICS application programs to access DB2 for a more detailed overview of this topic.
To control the characteristics of the plan and the CICS DB2 attachment facility threads, the relationship between transaction IDs, DB2 plans, and the program modules must be defined in the design step. Some characteristics of the threads, environmental description manager (EDM) pool, and plans that depend on the design are the:
There are various design techniques for combining CICS transactions with DB2 plans, as follows:
gives an example of a CICS application accessing DB2, and this example is used in discussion of the various design techniques.
A simple example can be used to explain the consequences of different application design techniques. Figure 27 shows how CICS MAPs and transaction IDs are correlated, and how the transactions should work, without DB2 considerations.
In this example:
Using packages is the best way to ensure that the relationship between CICS transactions and DB2 plans is easy to manage. See Plans, packages and dynamic plan exits for an overview of plans and packages.
In early releases of DB2, before packages were available, the DBRMs from all the programs that could run under a particular CICS transaction had to be directly bound into a single plan. Changing one DBRM in a plan (because the SQL calls for that program had changed) required all the DBRMs in the plan to be bound again. Binding a large plan can be very slow, and the entire transaction is unavailable for processing during the operation. Just quiescing an application can be very difficult for a highly used one, but to leave the plan out of commission for an extended time while it is being rebound is usually unacceptable.
Dynamic plan exits (see Dynamic plan exits) were an interim solution designed to address this problem. The dynamic plan exit is an exit program that you specify in the DB2CONN or DB2ENTRY definition instead of specifying a plan name. You create many small plans for your CICS applications, each containing the DBRMs from a few programs, and the exit program selects the correct plan when each unit of work begins. You can also use the dynamic plan exit to switch between plans within a transaction (see Dynamic plan switching). However, each small plan must still be rebound and taken out of commission every time an SQL statement changes in one of the programs that uses it. Also, the use of dynamic plan switching requires an implicit or explicit CICS SYNCPOINT to allow switching between plans.
Now that packages are available in DB2, using them is the best way to manage your plans. With packages, you can break the program units into much smaller parts, which you can rebind individually without affecting the entire plan, or even affecting the current users of the particular package you are rebinding.
Since updating a plan is easier with packages, you can build much larger applications without the need to switch transactions, programs, or plans to accommodate DB2 performance or availability. This also means that you do not have to maintain as many RDO definitions. You can also avoid situations where you might otherwise use dynamic SQL to obtain program flexibility. In a plan, you can even specify packages that do not exist yet, or specify package collections to which you can add packages. This means that DBRMs from new programs could be added without disturbing the existing plan at all.
The qualifier option on packages and plans to reference different table sets can give you more flexibility to avoid plan switching.
In summary, packages:
during bind for programs that are logically linked together with START, LINK, or RETURN TRANSID and have DBRMs bound together to reduce DB2ENTRY definitions.
There are other benefits that using packages can provide in a CICS environment:
You can also optimize your application by using package lists that order their entries to reduce search time or by keeping package list entries to a minimum.
DB2 also provides accounting at the package level. For more information about packages, refer to the discussions of planning to bind and preparing an application program to run in the DB2 Universal Database™ for OS/390 and z/OS® Application Programming and SQL Guide and DB2 Packages: Implementation and Use.
A transaction that currently uses a dynamic plan exit or dynamic plan switching techniques can be converted to use packages as follows:
You could choose to have a single plan for the whole application, or one plan per transaction. The following sections give more detailed instructions for converting your transactions, based on this choice.
A similar approach can be taken for converting all CICS applications, whether they use a dynamic plan exit or not.
Note that high-usage packages can be bound with RELEASE(DEALLOCATE), with low-usage packages bound with RELEASE(COMMIT). This results in the high-usage packages being retained in the plan's package directory until plan deallocation, while the low-usage packages are removed from the directory, and the space in the EDM pool is released. The disadvantage of this approach is that if you use RELEASE(DEALLOCATE) and then need to rebind a highly-used package, you must intervene to force deallocation of the package if it is allocated to a long-running thread. Consider that to rebind a package is less expensive than to rebind a plan, in terms of the time spent doing it.
This approach gives greatest flexibility in defining the DB2ENTRYs and DB2TRANs for the application, because the transactions involved can be grouped to better utilize protected threads and optimize thread reuse. The steps in converting to this environment are:
BIND PLAN (PLANAPP1) ..... PKLIST (COLLAPP1.*) ..
PLANEXITNAME=DSNCUEXT
with
PLAN=PLANAPP1
This approach was preferable prior to DB2 Version 3 because accounting at the individual package level was not possible, which forced accounting to be done by plan name. However, current releases of DB2 provide accounting at the package level, which allows for plans to be made up of a large number of packages whilst still providing the required accounting granularity.
The steps in using this approach are:
BIND PLAN (TRAN1) .... PKLIST (TRAN1.*) ...
or
BIND PLAN (TRAN1) .... PKLIST (COLLAPP1.*) ...
For dynamic plan switching users, if the value of a modifiable special register (for example, the CURRENT PACKAGESET register) is changed during processing and not reset to the initial state before the SYNCPOINT is taken, the following occur:
Therefore you should take care to ensure that any modifiable special register is reset to its initial value before the SYNCPOINT is taken if you want to use dynamic plan switching. The DB2 Universal Database for OS/390 and z/OS Administration Guide lists the modifiable special registers.
Using one large plan for all CICS transactions that issue SQL calls is an easy strategy. For the example in Figure 27:
Because the application plan directory size is directly dependent on the number of segments in the plan, using a large plan influences the EDMPOOL size and the number of I/O operations needed to control it.
This technique requires many transaction IDs, each of which has a corresponding plan. The technique can minimize both plan sizes and plan overlap.
We recommend that you use packages rather than using many small plans.
Using many small plans implies either that the program flow follows a narrow path with limited possibilities for branching out, or that plan switching takes place frequently.
In the example in Figure 27, the switching could take place between program P0 and the programs at the next lower level, or between program PA and the programs at the next lower level.
However, program P3 can transfer control (using the XCTL command) to program PB. A plan switching technique must then be used. These techniques are described in If you need to switch plans within a transaction.
A special variation of using small plans exists. In some applications, it can be convenient to have the terminal user specify the transaction ID for the next transaction. It is typically in read-only applications, where the user can choose between many different information panels by entering a systematically built 1- to 4-character transaction ID. The advantage for the user is the ability to jump from any panel to any other panel without passing a hierarchy of submenus.
If a DB2 plan is associated with each transaction ID, the application ends up with many small plans.
Transaction grouping can produce a number of midsize independent plans, where a plan switch can occur if necessary.
It is often possible to define such groups of programs, where the programs inside a group are closely related. That means that they are often executed in the same transaction, or in different transactions being executed consecutively. One separate plan should then be used for each group.
In the example in Figure 27 two plans could be built:
However, program P3 can transfer control to program PB. A plan switching technique could then be used. These techniques are described in section If you need to switch plans within a transaction. It is recommended that plan switching is an exception and not the normal case, mainly due to additional processor overhead.
In this case, the result of the transaction grouping technique matches the result for the technique of using many small plans. This is because of the simplicity of the example used. Normally the transaction grouping technique should produce a larger plan.
You can design CICS applications around numerous small plans and select the plan dynamically at execution time. A small plan is not the same as a package, which has a strictly one-to-one correspondence to a database request module (DBRM). The use of packages is recommended rather than the use of dynamic plan exits, as packages have additional advantages over dynamic plan exits -- see Using packages for more information. The use of dynamic plan exits was an interim solution that was designed to address problems in the CICS DB2 environment before packages were available in DB2.
Normally, a dynamic plan exit is driven to determine which plan to use at the start of the first unit of work (UOW) of the transaction. This is referred to as dynamic plan selection.
A dynamic plan exit can also be driven at the start of a subsequent UOW (assuming the thread was released at syncpoint) to determine what plan to use for the next UOW. The plan exit can decide to use a different plan. This is referred to as dynamic plan switching. See Dynamic plan switching for more information.
When a dynamic plan exit is used, DB2 plan allocation occurs only upon execution of the first SQL statement in a program, or after the program issues a syncpoint and links or transfers control to another program with a separate DBRM.
This is accomplished by using an exit program specified in:
IBM® supplies two sample assembler language exit programs, DSNCUEXT and DFHD2PXT, in both source and object code form. You can also write other exit programs.
Note that the use of the following items within the dynamic exit
program is not supported:
IBM supplies two sample assembler language exit programs, DSNCUEXT and DFHD2PXT, in both source and object code form. DSNCUEXT and DFHD2PXT 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).
The two programs are supplied because as explained in Enabling CICS DB2 applications to exploit the open transaction environment (OTE) through threadsafe programming, when CICS is connected to DB2 Version 6 or later and exploits the open transaction environment (OTE), the CICS DB2 task-related user exit operates as a threadsafe program and is able to receive control on an open TCB (L8 mode). If the application program that made the DB2 request is threadsafe, it can also run on the open TCB. In this situation, no TCB switching should 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.
When CICS is connected to DB2 Version 6 or later, you should therefore use DFHD2PXT as your dynamic plan exit in preference to DSNCUEXT. However, note 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 the performance benefits resulting from the avoidance of TCB switching, you must 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, DSNCUEXT and DFHD2PXT, 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 DSNCUEXT (or DFHD2PXT) through a COMMAREA, and has the following format in the Assembler version:
CPRMPLAN | DS | CL8 | The DBRM/plan name of the first SQL statement on entry to DSNCUEXT (or DFHD2PXT). 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 DSNCUEXT (or DFHD2PXT). The CICS DB2 attachment preserves this field across invocations of DSNCUEXT (or DFHD2PXT). |
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 that DB2 produce four DBRMs for each application program in order to support dynamic change of isolation levels. For JDBC and SQLJ applications, the DBRM name is restricted to seven characters, the eighth character being used as a suffix of 1,2,3 or 4. Hence for JDBC and SQLJ applications it is not possible to use a default naming convention of program name = dbrm name = plan name, as the DBRM name being used will contain 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 will always have the DBRM name set to the JDBC base program with the default isolation level appended. That is, DSNJDBC2 by default, or if, for example, the JDBC profile was generated using pgmname=OTHER, the DBRM name will be OTHER2. For example, if dynamic plan exits are not used, the plan name is always obtained from the DB2CONN or DB2ENTRY definition, the plan name in the properties file is ignored.
In order to support a default naming convention for JDBC 1.2 and 2.0 and SQLJ, the CICS-supplied dynamic plan exits DSNCUEXT and DFHD2PXT have been changed to detect an input CPRMPLAN name whose first seven characters are "DSNJDBC" or "DSNSQLJ". If such a plan name is detected, the plan name is changed to "DSNJDBC " (with the eighth character set to blanks). Users wishing to use the default dynamic plan exits with Java applications for CICS should bind the multiple DBRMs into a plan called DSNJDBC.
For
the support of the DB2 Universal JDBC Driver, the CICS-supplied dynamic plan
exits DSNCUEXT and DFHD2PXT have been changed to 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 "
(with the seventh and eighth characters set to blanks). Users wishing to use the default dynamic plan exits with Java
applications for CICS should bind the multiple DBRMs into a plan called DSNJCC.
The exit program can be written in assembler language, COBOL, or PL/I. The program is a CICS program, which means it must:
The CICS DB2 attachment facility program passes a parameter list to the exit program using a COMMAREA. The exit program can change the default plan name (DBRM name) supplied in the parameter list, when the first SQL statement is processed by the CICS DB2 attachment facility. The name specifies the plan name for this execution of the transaction.
If CICS is connected to DB2 Version 6 or later, then as explained in Enabling CICS DB2 applications to exploit the open transaction environment (OTE) through threadsafe programming, you should ensure that the logic in your dynamic plan exit is coded to threadsafe standards, and that the program is defined as threadsafe (like the sample exit program DFHD2PXT). If the program is not defined as threadsafe, each use of the program causes a switch back to the QR TCB, incurring an additional cost. If the program is defined as threadsafe but uses non-threadsafe CICS commands (which is permitted), each non-threadsafe command causes a switch back to the QR TCB and incurs the additional cost.
You can use this technique if the applications were developed with little attention to the DB2 plan aspects. After the application is completely developed, the plans are defined to match the transaction.
In general, defining plans after the application has already been developed is not recommended, but this technique is useful for conversion projects, where the application design is unchanged but the application now uses DB2.
When defining the DB2 plans and the DB2ENTRY specifications, you can perform the following steps:
The output from this step is a list of DBRMs for each transaction.
For this step you have many alternatives. The possible number of plans to use is between one and the number of different transaction IDs. The best way to manage the plans is to use packages, binding all the DBRMs into packages that are then listed in plans (see Using packages). If you do not use packages, alternative techniques are described in Using one large plan for all transactions, Using many small plans and Using plans based on transaction grouping.
Applied to the example in Figure 27, a possible solution would be:
The advantages and disadvantages of this technique completely depend on the actual application design and the result of the above-mentioned steps.
Ideally, the plan that a transaction uses to access DB2 should contain or reference the DBRMs from all the application programs that could operate under that transaction ID. However, you might find that if the design of your applications has changed, some of your older plans now do not contain all the relevant DBRMs. In this case, the application design could require a switch to a different plan in the course of a transaction, if the transaction requires that a program not included in the current plan must be executed. This situation could also occur if the structure of the DB2 plans was imperfectly considered during the design of the application.
The best solution to this problem is to use packages. You can bind the DBRM from the missing program into a package, and add the package to a package list in the existing plan. The transaction can now access the missing program without needing to switch plans. There are two other possible solutions, which are discussed below, as follows:
Dynamic plan switching (DPS) allows you to use more than one plan in a transaction. However, as noted above, switching plans within a CICS transaction instance should be a rare occurrence. The dynamic plan exit was designed to select a plan dynamically at the start of the transaction (dynamic plan selection), not to change plans frequently within transactions.
To do dynamic plan switching, the thread must be released at syncpoint and reacquired, to drive the dynamic plan exit. The dynamic plan exit can then be used to select the plan for the program you need to execute. This enables the use of a different plan for different UOWs within a transaction.
In releases of CICS before CICS Transaction Server for OS/390®, Version 1 Release 2, dynamic plan switching could only occur for the pool threads, or for RCT entries that specified THRDA=0, that is, overflowed to the pool. An RCT entry with THRDA > 0 was not capable of dynamic plan switching. In CICS Transaction Server for OS/390, Version 1 Release 2 and later versions and releases, dynamic plan switching can occur for entry threads as well as for the pool, irrespective of the THREADLIMIT parameter.
If you have coded your own dynamic plan exit, check that the logic copes with subsequent invocations for the same task. Either the user application or the dynamic plan exit must be written to tolerate consequences of additional calls to the exit. If the dynamic plan exit would change the plan when not wanted, the user application can avoid this by ensuring the thread is not released at syncpoint. Preferably, if the thread is released, the dynamic plan exit must provide the proper plan for the new cases when it is called, that is, a DB2ENTRY with THREADLIMIT > 0.
To invoke the dynamic plan exit to do plan switching after the end of a UOW, your transaction must release the thread at syncpoint. A transaction releases a thread at syncpoint only if:
Once a transaction has started, the application programmer cannot control the plan used by the transaction ID, but they can control the transaction ID itself. So, from a programmer viewpoint, a possible way to switch plans would be to switch transaction IDs. However, it is strongly recommended that you bind the DBRM from the missing program into a package, and add the package to a package list in the existing plan, rather than changing the transaction ID just to switch to a new plan.
If you have to switch transaction IDs, note that in most cases, the first program transfers data to the next program. The preferred method of doing this is to use an EXEC CICS RETURN IMMEDIATE command. Alternatively, you can start a new CICS task against the same terminal, using an EXEC CICS START command, or using a transient data queue with a trigger level of one. The old program should issue RETURN to CICS to make the new task start. For both of these switching techniques, the work done in one user transaction is split up into more than one UOW. If the new task is backed out, the work done in the first task remains committed.
If you switch transaction IDs in order to switch plans, the application programs contain the logic to decide when to switch transaction ID. This means that if you want to change the plan structure (for example for performance and operational reasons), you need to change the application programs as well.
A different technique is to have the program flow controlled by a table, instead of having code to do this in several programs. The main idea is that it is simpler to maintain the relationship between the plans, programs, and transaction IDs in a table than to maintain code in each application program to do the logic. Developing the application programs is also simpler if a standard interface is provided.
The design principle presented below is an example of a standard method that can be used to implement different types of application design. It allows the use of, for example, one large plan or many small plans without changing the programs.
Table 5 shows an example of the contents of a control table. The example is based on the design situations described in Figure 27.
Function name | Program | Transaction | Plan name | New TRANS ID |
---|---|---|---|---|
P0 | TRX0 | PLAN0 | * | |
Sales | P1 | TRX0 | PLAN0 | |
Order | P2 | TRX0 | PLAN0 | |
Pay | P3 | TRX0 | PLAN0 | |
PA | TRXA | PLANA | * | |
Price | PB | TRXA | PLANA | |
Order | PC | TRXA | PLANA | |
Parts | PD | TRXA | PLANA | |
Price | PB | TEMP | PLANX | * |
PFCP then uses the function column to search for a valid transaction.
In this way, the logic to interpret the user's choices is also removed from the programs and placed in the table, where it is easy to maintain.
The control table reflects the following main relationships:
When implementing the definitions in CICS, you should consider the following:
Multiple "logical RCTs" could be maintained in an RDO environment by placing a DB2CONN definition and its associated DB2ENTRYs and DB2TRANs in a list, and installing the required list. Two additional columns would be added to the control table:
At execution time, the PFCP can determine the applid and DB2CONN name using an EXEC CICS INQUIRE SYSTEM command. It then searches for rows belonging to the current applid and DB2CONN.
The disadvantage, however of multiple "logical RCTs" is that a DB2CONN cannot be discarded and replaced without shutting down the CICS DB2 attachment facility. A solution is to have one DB2CONN definition and to change "RCTs" by discarding and installing different sets of DB2ENTRYs and DB2TRANS to work with it. These can be discarded and installed without shutting down the attachment facility.
In this case, the control table could contain a DB2ENTRY name instead of the DB2CONN. At execution time, the PFCP can use the CICS DB2 SPI commands to inquire whether this DB2ENTRY was installed. In this way using the name of one DB2ENTRY to identify the set of definitions installed, identifies the "logical RCTs".
The control table can be implemented in different ways. The most useful solutions are probably either a DB2 table or a main storage table.
A DB2 table is the simplest to develop and maintain. One or two SELECT calls are needed for each invocation of PFCP. These SELECTs should return only one row and indexes can be used. The data and index pages are referenced often and probably stay in the buffer pool. The response time impact is thus minimal.
A main storage table is faster to access, at least until a certain number of rows in the table is reached. It is more complicated to maintain.
The principle in the program flow is shown in Figure 28.
The flow for the application design used in Figure 27 is explained below:
The table shows that PB must not be executed under TRX0. PFCP then examines the table to find a transaction ID under which program PB can be executed. In the example, both TRXA and TEMP are valid transaction IDs. However, TRXA is pointing to program PA in the transaction definition. The New_TRANS_ID column of the table shows that only the rows with an * can be used when searching for a new transaction ID to start a given program. In this case, it is the TEMP transaction.
There are two possibilities for program names in the RDO transaction definition entry for the TEMP transaction ID:
The solution with the RELAY program is shown in Figure 28.
The two major disadvantages of this technique are the costs of designing and developing the solution and the execution time overhead.
The cost of getting from program to program is approximately doubled. However, this should normally not correspond to more than a few percent increase in the processor time for the transaction. To decide whether or not to use such a solution, you should balance these disadvantages against the advantages.