Precompiler+Bind+Plans + DBRMS + Packages + Collections + Versions = Confusion

Packages and Collections

In V2R3, the DB2 developers solved the seven problems I listed (and many more) by introducing another layer in the program preparation procedure. The precompile step still split the program into tattooed twins, and the treatment of the modified source code stayed the same. But the DBRM could now be bound either into a PLAN (the old way) or into a PACKAGE. Although the relationship between a DBRM and a PLAN was one-to-many, the relationship between a DBRM and a PACKAGE was always one-to-one. Most of the work of BIND PLAN was moved into BIND PACKAGE. Therefore, if PGMA changed, only PACKAGE A would have to be bound.
If only one DBRM could be bound into a PACKAGE, but PGMA could still CALL PGMB, then a structure was needed to gather all of the PACKAGEs into a searchable list. This structure became a packagelist, rather than a memberlist, bound into a PLAN.

This tiny change solved many, but not all, of the problems inherent in the "memberlist of DBRMs bound into a PLAN" technique. To solve a few more problems, IBM introduced the concept of COLLECTIONs. A collection is simply a way of grouping packages into meaningful (for you) groups. You could BIND all of the packages that must run against Corporation 1's tables into one COLLECTION and all of the packages that must run against Corporation 2's tables into another. Or, you could use COLLECTIONs to separate programs for different application areas, such as payroll and inventory.

Another use might be to separate programs bound with ISOLATION UR from programs bound with ISOLATION CS. COLLECTIONs are simply high-level grouping names to designate that this group of packages share something, anything, in common.
So, now, with the introduction of COLLECTIONs, our BIND PLAN process (think search chain) can now include a packagelist of fully qualified package names such as COLLPAYROLL.PGMA, COLLPAYROLL.PGMB, and COLLCOMMON.PGMX. Or, if we choose, we can just substitute an asterisk for the program name and list (COLLPAYROLL.*, COLLCOMMON.*). Then any program bound into the COLLECTION will be accessible by the named PLAN.

Where Are Packages and Plans?

When you BIND a DBRM into a PLAN, or BIND a PACKAGE into a COLLECTION and then the COLLECTION(s) into a PLAN, the information must be stored somewhere safe inside DB2 until it's needed at run time. These items (PLANs and PACKAGEs) aren't stored in the DB2 Catalog. Rather, they're stored in the DB2 Directory. In fact, you can think of the Directory as the DB2 loadlib for the Danny portion of your program, complete with tattoo.

Run Time

At run time, the load module starts up and eventually hits a paragraph containing a CALL to DB2. This CALL contains information such as a description of the tattoo, the content of your SQL host variables (now populated), the statement number, and so on. The CALL invokes the COBOL-DB2 interface program, which connects to DB2. And if the run-time code necessary to execute your SQL isn't currently resident inside DB2 (in the EDMPOOL), we go to the buffer pool (BP0) assigned to the DB2 Directory and look there. If we don't find Danny there, we go to VSAM to disk to look in the COLLECTIONs named in the PLAN for the PACKAGE with the same name and the same tattoo, also known as the consistency token or timestamp.

And if you don't find the twin anywhere in DB2 (not that this has ever happened to anyone reading this column), you get a -805 error. If you're still using the older technique of binding DBRMs directly into PLANs via a memberlist, then an unsuccessful search for Danny will result in a -818 error code.


In my next column, I'll give you some ideas about the various ways of using the concept of the COLLECTION. I'll also write about VERSIONs and how they're used.