After the precompiler or coprocessor writes a DBRM, DB2 for z/OS still cannot run the SQL. You bind that DBRM into a package that lives in a collection, then list the package (or the whole collection) on an application plan. This page is the map mainframe developers use every day: DBRM versus package, collections, versions, package lists, copies, the current package at run time, dependencies, authorization, invalidation, consistency tokens, versioning, and package stability.
A database request module is a file (almost always a PDS or PDSE member, sometimes an HFS file from UNIX System Services) that holds the SQL statements and host-variable information the SQL statement processor extracted. It is not an access path and not a load module. BIND PACKAGE reads one DBRM per package. IBM’s exception: you do not need to bind a DBRM if the only SQL in the program is SET CURRENT PACKAGESET.
Promote DBRMs with the same care as source. If production BIND reads a DBRM that does not match the load module you shipped, the consistency token will not match and the thread fails. Many shops bind in a promotion job that uses the DBRM created in the same compile as the load module being copied to production.
A package is the bound SQL for that DBRM. Db2 records the description in catalog tables (SYSIBM.SYSPACKAGE and related tables) and saves the prepared form in the directory. BIND PACKAGE also deletes phased-out package copies used by plan management. You can COPY a package instead of binding from a DBRM (remote bind, cloning bind options into another collection).
| Part | Meaning |
|---|---|
| Location | Subsystem / remote server; omitted means local |
| Collection | User-chosen package group (BIND PACKAGE name) |
| Package-id | Usually the DBRM / program name (SYSPACKAGE.NAME) |
| Version | VERSION precompiler option, or empty-string default |
| Consistency token | Pairs load module SQL calls with the bound package |
1234BIND PACKAGE(PAYROLL) MEMBER(PAYCALC) - ACTION(ADD) VERSION(V2) - OWNER(PAYBIND) QUALIFIER(HR) - ISOLATION(CS) VALIDATE(BIND)
ACTION(ADD) creates a new package or a new version. ACTION(REPLACE) replaces an existing one. Packages let you test a new program version without rebinding every other package on the plan — that flexibility is why IBM moved shops off “all DBRMs in the plan” years ago.
A collection is not a data set. It is a name you choose on BIND PACKAGE(collection-id). Typical patterns:
You can bind the same DBRM into more than one collection (BIND ADD or BIND COPY). Each copy can have different isolation, qualifier, APPLCOMPAT, or owner. CREATE IN or PACKADM on the collection is the privilege that lets binders put packages there.
Specify VERSION(id) on the precompiler or coprocessor SQL options. That identifier is stored in the DBRM and becomes the package version. Without VERSION, Db2 uses an empty-string version. You can keep several versions of PAYCALC in collection PAYROLL at once so an old CICS load library and a new one can run side by side — each load module’s consistency token selects its version.
Version is not the same as a PLANMGMT copy. Changing VERSION is a new bind from a new DBRM (usually new source). PLANMGMT copies are extra bound structures for the same version after REBIND.
The plan’s PKLIST is the search path for packages at run time. You can list a specific package or a whole collection:
123BIND PLAN(PAYPLAN) - PKLIST(PAYROLL.*, COMMON.DATEXT) - ACTION(REPLACE) RETAIN
When the program issues SQL, Db2 looks along the package list for a package whose collection, name, version, and consistency token match. PAYROLL.* means “any package in PAYROLL.” Order can matter when the same package-id exists in more than one collection on the list — CURRENT PACKAGESET (and related special registers) is how you pin the collection instead of relying on search order.
PLANMGMT (plan management) is the package-stability feature. The subsystem default is typically EXTENDED. When you REBIND with EXTENDED or BASIC, Db2 keeps extra copies:
| Copy | Role |
|---|---|
| Current (active) | The copy Db2 runs |
| Previous | Copy from the last REBIND; SWITCH(PREVIOUS) |
| Original | Kept under EXTENDED; SWITCH(ORIGINAL) |
Copies share location, collection, name, version, and consistency token. They differ in metadata and compiled run-time structures (access paths). If a REBIND produces a bad path, REBIND … SWITCH(PREVIOUS) or SWITCH(ORIGINAL) makes the saved copy current without re-optimizing from scratch. That is package stability: you can try new statistics and still fall back.
APREUSE tries to reuse saved access paths on REBIND. APCOMPARE compares the newly chosen path with the old one and can warn or fail. Together with PLANMGMT they are how production shops change indexes without gambling the next online day.
At run time the “current package” is the one Db2 actually executes for a given SQL call: matching CONTOKEN, name, version, and collection. You influence collection selection with:
Trigger packages and REST service packages are also packages, but you do not BIND PACKAGE them from a COBOL DBRM in the usual way. Basic triggers are created with CREATE TRIGGER and rebound with REBIND TRIGGER PACKAGE. Native REST services use BIND SERVICE.
SYSIBM.SYSPACKDEP records what a package depends on: tables, indexes, views, aliases, functions, sequences, and so on. BIND/REBIND builds that graph while it resolves names. When you DROP INDEX or ALTER TABLE, Db2 walks dependencies and marks packages invalid. Different copies can be affected differently: dropping a table invalidates all copies; dropping an index might invalidate only copies that used that index.
Package privileges on z/OS are BIND, COPY, and EXECUTE (GRANT ALL grants all three). Collection privileges include CREATE IN and PACKADM. Static SQL is authorized at bind time for the owner; end users typically need EXECUTE on the plan or package, not SELECT on every table. BINDAGENT lets a binder specify OWNER. In a trusted context with role-as-object-owner, OWNER is a role.
Db2 sets VALID='N' in SYSPACKAGE (and SYSPLAN when a plan is involved) when the package must be automatically rebound. With statement-level invalidation, VALID='S' can mark only some statements. Failed autobind can set OPERATIVE to inoperative. Causes include:
Autobind replaces the current copy only; previous and original copies are left alone. If autobind is disabled or fails, the application sees a bind-related SQLCODE until someone REBINDs. SQL statement changes are not an invalidation event — you must BIND from a new DBRM (usually ACTION REPLACE).
The precompiler or coprocessor identifies each call to Db2 with a consistency token. The same token identifies the DBRM and the package you bound from it. The token alone is not unique: the same DBRM can be bound at many locations and collections, all sharing the token. Run time still needs collection (and sometimes location) to pick among them. You can override the generated token if your shop has a special scheme; most sites never do.
Query SYSIBM.SYSPACKAGE for NAME, COLLID, VERSION, CONTOKEN, VALID, OPERATIVE, LASTUSED, and bind options. HEX(CONTOKEN) is how people compare the catalog to a DBRM listing when a CICS region “cannot find the package.”
A DBRM is a recipe card you wrote in the kitchen (precompile). A collection is a labeled shelf. A package is the cooked meal sitting on that shelf. A plan is the waiter’s list of shelves they are allowed to visit. The secret stamp on the card and on the meal must match or the waiter will not serve it. Versions are different editions of the same cookbook. Extra copies in the freezer (PLANMGMT) let you bring back last week’s meal if today’s cooking tastes wrong.
1. What is a DBRM in Db2 for z/OS?
2. How is a package identified?
3. What does a collection do?
4. What do PLANMGMT copies share?
5. When is a package marked invalid?