Create a DB2 Package with BIND PACKAGE

What a DB2 package is

When you precompile a COBOL, PL/I, C, or other host-language program that contains embedded SQL, Db2 produces a database request module (DBRM). The DBRM holds the SQL statements and a consistency token. Compiling and link-editing produce a load module that calls the Db2 language interface. Binding is the Db2-side step that validates the SQL, chooses access paths, and stores an executable package.

Modern shops almost always bind each DBRM into a package inside a collection, then point an application plan at that collection with PKLIST. That design lets you change and rebind one program without rebinding every other DBRM that used to live inside a monolithic plan MEMBER list.

• DBRM — input produced by precompile or SQL statement processing.
• Package — bound SQL for one DBRM, stored under a collection.
• Collection — named container for related packages.
• Plan — runtime allocation object that lists packages or collections.

Prerequisites

Do not start BIND PACKAGE until the deployment unit is clear. The package is only one artifact in a chain that must stay consistent from precompile through production run.

Confirm the Db2 subsystem or group attach name, the DBRM library disposition, and whether ACTION should be ADD for a new version or REPLACE for the current version. Agree on OWNER and QUALIFIER with the DBA team so unqualified SQL resolves to the intended schema and privilege checks use the intended authorization ID.

Important BIND PACKAGE options

BIND PACKAGE has many options. Shops standardize a subset so test and production behave the same way. Understand at least these before you submit a bind job.

Isolation, release, currentdata, degree, and APPLCOMPAT also matter for concurrency and SQL level. Copy an approved bind skeleton from your shop rather than inventing a unique set of options for every program. Different collections can hold the same package name with different options when you need alternate behaviors such as CS versus UR.

Steps: create the package

1. Confirm the DBRM

List the DBRM library member and match its name to the program. The member used for BIND PACKAGE must be the DBRM from the same precompile that produced the object module in the load library. Mixing a new load module with an old DBRM (or the reverse) is a classic path to SQLCODE -818.

2. Run BIND PACKAGE under DSN

Batch shops usually run the TSO Terminal Monitor Program IKJEFT01, start a DSN session for the subsystem, and issue BIND PACKAGE. The following skeleton uses a training collection and replaces the package for member EMPRPT01.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//BINDPKG  EXEC PGM=IKJEFT01,DYNAMNBR=20
//STEPLIB  DD DISP=SHR,DSN=DSN.V12R1M0.SDSNEXIT
//         DD DISP=SHR,DSN=DSN.V12R1M0.SDSNLOAD
//DBRMLIB  DD DISP=SHR,DSN=APP.TRAIN.DBRMLIB
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
  DSN SYSTEM(DB2T)
  BIND PACKAGE(TRAINCOLL) MEMBER(EMPRPT01) -
       ACTION(REPLACE) -
       OWNER(APPTRAIN) -
       QUALIFIER(TRAINING) -
       ISOLATION(CS) -
       VALIDATE(BIND) -
       RELEASE(COMMIT) -
       EXPLAIN(YES)
  END
/*

Adjust STEPLIB, SYSTEM, collection, OWNER, QUALIFIER, and library names to your site. Some shops put LIBRARY on the BIND statement instead of relying only on DBRMLIB. If you bind from DB2I, the panels collect the same information and generate comparable DSN commands.

3. Ensure the plan can find the package

Binding the package does not automatically attach it to every plan. A typical plan uses a collection wildcard:

1
2
3
4
BIND PLAN(TRAINPLN) -
     PKLIST(TRAINCOLL.*) -
     ACTION(REPLACE) -
     ISOLATION(CS)

After the collection is already on the PKLIST, rebinding one package is enough for that program change. Rebind the plan only when the package list itself changes.

4. Optional: COPY into another collection

BIND PACKAGE can COPY an existing package into another collection and change selected options. That pattern is useful when promoting a tested package or when you need the same SQL with a different ISOLATION or QUALIFIER without re-precompiling.

Verify results

Treat a zero return code from the bind step as necessary but not sufficient. Verify the catalog and the runtime path.

• Query SYSIBM.SYSPACKAGE for COLLID, NAME, VERSION, OWNER, QUALIFIER, BINDTIME, and ISOLATION.
• Confirm the plan PKLIST still includes the collection (SYSIBM.SYSPACKLIST or your shop's reporting view).
• If EXPLAIN(YES) was used, review PLAN_TABLE rows for unexpected tablespace scans or missing index use.
• Run a controlled program or CALL path that exercises the new package and checks SQLCODE 0 for expected statements.

1
2
3
4
5
6
SELECT COLLID, NAME, VERSION, OWNER, QUALIFIER,
       BINDTIME, ISOLATION, VALID, OPERATIVE
  FROM SYSIBM.SYSPACKAGE
 WHERE COLLID = 'TRAINCOLL'
   AND NAME   = 'EMPRPT01'
 ORDER BY BINDTIME DESC;

Catalog column details can vary by Db2 release. Use the catalog documentation for your installed level, and prefer local reporting views when your site provides them.

Common errors

Most package problems are consistency problems: wrong library, wrong collection, wrong plan list, or mismatched timestamps. Use the symptom table as a first triage guide.

Also watch for VALIDATE(RUN) packages that bind cleanly and then fail at first execution when an object or privilege is missing. Prefer VALIDATE(BIND) for static production packages unless your shop has a documented reason to defer validation.

Explain It Like I'm Five

Imagine each COBOL program writes its Db2 questions on a worksheet (the DBRM). Creating a package is like giving that worksheet to a teacher who checks the questions, decides the fastest way to find the answers, and files the finished sheet in a labeled binder (the collection). The class plan is a list of binders the teacher is allowed to open. If your sheet is filed but the class plan never lists that binder, the student still cannot get answers at run time.

Exercises

1. Write a BIND PACKAGE command for DBRM ORDUPD01 into collection APPCOLL with QUALIFIER(SALES) and ISOLATION(CS).
2. Explain why ACTION(REPLACE) on a package usually does not require rebinding every other package in the same collection.
3. List three catalog or operational checks you will perform after a successful bind return code.
4. Describe how a correct package bind can still produce SQLCODE -805 at run time.
5. Compare BIND PACKAGE with REBIND PACKAGE and state when each is appropriate.