Db2 Application Environment: COBOL, DBRM, Package, Plan, and Runtime Flow



Last updated: July 2026

A COBOL program with embedded SQL does not run against Db2 just because the source compiled. The program must pass through precompile, compile, link-edit, bind, execution JCL, runtime libraries, and SQL return-code checks. A missing package, a wrong collection, or a stale plan can stop the job before the first business record is processed.

The Db2 application environment is the set of source members, DBRMs, packages, plans, load modules, subsystem settings, libraries, and runtime checks that let an application program use Db2 safely on z/OS.

Build and bind before the program runs.

What belongs in a Db2 application environment

For a Db2 for z/OS application, the environment usually includes developer source libraries, precompile output, DBRM libraries, load libraries, bind jobs, package collections, plans, runtime JCL, and operational logging. The exact names vary by shop, but the responsibilities are similar.

Part	Purpose	What to verify
COBOL source	Contains embedded SQL inside EXEC SQL and END-EXEC.	Host variables, copybooks, SQLCA include, and indicator variables are correct.
Precompile step	Separates SQL from COBOL and creates a DBRM.	DBRM member name, SQL syntax, and precompiler options match the application standard.
Compile and link-edit	Builds the executable load module.	Correct compiler options, copybook libraries, and Db2 interface modules are available.
Bind package or plan	Creates the executable SQL control structure used by Db2.	Collection, owner, qualifier, isolation, validation timing, and package/plan name are right.
Runtime JCL or online region	Runs the program under batch, CICS, IMS, or another execution path.	Subsystem, libraries, plan or package reference, and error logging are correct.
SQLCA handling	Reports SQL execution results back to the program.	Program checks SQLCODE, SQLSTATE, warning flags, and row counts where needed.

Batch COBOL Db2 flow

A common batch flow starts with a COBOL source member, runs a Db2 precompile, compiles the modified COBOL, link-edits the load module, binds the DBRM into a package or plan, and executes the program through JCL. If one of those artifacts is out of sync, production can fail with package-not-found, authorization, or access-path problems.

//BINDPKG  EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
  DSN SYSTEM(DB2P)
  BIND PACKAGE(APP1COLL) -
       MEMBER(ACCTUPD) -
       ACTION(REPLACE) -
       ISOLATION(CS) -
       VALIDATE(BIND)
  END
/*

The bind job is not just a build step. It decides where Db2 will look for objects, which collection holds the package, when object checks happen, and what access path Db2 records for static SQL.

Online application paths

Batch is not the only application path. CICS and IMS programs can also call Db2, but the runtime setup is different. CICS needs the correct Db2 connection setup, transaction definition, program definition, and plan or package access. IMS regions need the correct dependent-region and Db2 attachment configuration.

For support work, the practical question is simple: which subsystem did the program connect to, which plan or package did it use, and what SQL return code came back?

Development, test, and production separation

Most shops keep separate Db2 subsystems or schemas for development, test, and production. The program name can stay the same while the collection, qualifier, or subsystem changes by environment. That is useful, but it also creates easy mistakes.

• A test package might be rebound while production still uses an old access path.
• A job might point to the wrong subsystem after a JCL copy.
• A package collection might contain the right member name but the wrong version.
• A static SQL change might be compiled but not bound.

Runtime checks inside the program

The application environment is incomplete without runtime validation. A program should include SQLCA handling and should check the SQL result close to the statement that produced it.

EXEC SQL
   INCLUDE SQLCA
END-EXEC.

EXEC SQL
   SELECT ACCT_STATUS
     INTO :WS-ACCT-STATUS
     FROM ACCOUNT
    WHERE ACCT_NO = :WS-ACCT-NO
END-EXEC.

EVALUATE SQLCODE
   WHEN 0
      PERFORM PROCESS-ACCOUNT
   WHEN +100
      PERFORM HANDLE-NOT-FOUND
   WHEN OTHER
      PERFORM WRITE-DB2-ERROR
      PERFORM ROLLBACK-WORK
END-EVALUATE.

That small check prevents a program from treating a missing row as a valid business result. For data-change SQL, add row-count checks when the program expects exactly one row or a known number of rows.

Common failure points

DBRM and load module are not from the same source level

This often happens when a compile runs but the bind step is missed. The load module contains the latest logic, while Db2 still executes SQL based on an older package.

Wrong collection or plan

A job can run the correct program and still use the wrong package collection. Check the bind cards, run JCL, and runtime messages together.

Authorization missing at bind or run time

Bind authorization and execution authorization are separate concerns. A developer may be able to compile a program but not bind or run against a protected table.

SQL warnings ignored

Warnings can indicate truncation or null-handling problems. Treat warning flags as part of the application contract, not as decoration.

Checklist before moving to production

• Confirm the source, DBRM, load module, package, and plan names match the release package.
• Confirm the bind ran in the correct Db2 subsystem with the intended collection and qualifier.
• Confirm runtime JCL or online definitions point to the expected subsystem and libraries.
• Confirm SQLCA handling logs SQLCODE, SQLSTATE, message tokens, program name, and business keys.
• Confirm restart or rollback behavior for failed updates in batch jobs.

Related Db2 topics

Use this guide with Db2 Binding Application, Db2 Binding and Rebinding, Db2 Packages, Db2 SQL Execution Validation, and Db2 SQLCODE and SQLSTATE.

FAQ

What is a Db2 application environment?

It is the set of build, bind, runtime, and support components that allow an application program to execute SQL against Db2, including source, DBRM, package or plan, load module, subsystem, JCL, and SQLCA handling.

Why does a COBOL Db2 program need precompile and bind?

The precompile step extracts embedded SQL and creates a DBRM. The bind step turns that DBRM into executable SQL control information that Db2 can use at runtime.

What should be checked when a Db2 program fails in production?

Check the subsystem, package collection, plan, load library, bind timestamp, SQLCODE, SQLSTATE, message tokens, and the business key being processed when the failure occurred.

Db2 DSN Command Reference: BIND, RUN, SPUFI, DCLGEN, and REBIND



DSN runs Db2 commands from TSO.

A bind job can fail before a COBOL program ever reaches its first OPEN or FETCH. In many Db2 for z/OS shops, the first place to check is the TSO DSN command stream in SYSTSIN, because that is where BIND, REBIND, RUN, SPUFI, and related subcommands are issued.

DSN is the Db2 command processor that runs as a TSO command. It can be used in the foreground under TSO/ISPF or in batch through programs such as IKJEFT01. Once a DSN session starts, the subcommands tell Db2 what action to perform.

Where DSN fits

Db2 administration and application work uses several command paths. Some commands are Db2 system commands such as -DISPLAY DATABASE. Others are DSN subcommands used inside a DSN session, such as BIND PACKAGE or RUN PROGRAM. The old article mixed those categories together, so this refresh separates the common DSN work from general Db2 command usage.

• DSN command: starts a Db2 command processor session from TSO.
• DSN subcommands: run inside DSN, including BIND, REBIND, FREE, RUN, DCLGEN, SPUFI, END, and comments beginning with *.
• Db2 system commands: can be issued through DSN or from operator/admin paths, usually beginning with a hyphen, such as -DISPLAY or -START.

Common DSN subcommands

Subcommand	Used for	Production note
DSN	Starts the Db2 command processor session for a subsystem.	Check SYSTEM(DB2P) or the subsystem name before running bind or run jobs.
BIND	Creates or replaces an application package or plan from a DBRM.	Review collection, qualifier, owner, validation timing, and isolation before release.
REBIND	Refreshes an existing package or plan without using a new DBRM.	Use with care after RUNSTATS or access-path changes; keep fallback steps clear.
FREE	Deletes a package or plan.	Confirm no active application depends on the object before removing it.
RUN	Runs an application program under DSN.	Check plan name, program load library, and runtime SQL errors together.
DCLGEN	Generates host-language declarations for tables or views.	Regenerate declarations when column definitions used by COBOL change.
SPUFI	Runs SQL from an input file in an ISPF foreground session.	Good for controlled testing, not for unattended production jobs.
END	Ends the DSN session.	Always close the command stream cleanly in batch SYSTSIN.
*	Marks a DSN command-stream comment.	Use comments to identify release number, package, and change ticket.

Batch DSN example with BIND PACKAGE

In batch, a DSN command stream is normally placed in SYSTSIN. The example below starts DSN for subsystem DB2P, binds package member ACCTUPD, and ends the session.

//BINDPKG  EXEC PGM=IKJEFT01
//STEPLIB  DD  DISP=SHR,DSN=DB2P.SDSNLOAD
//SYSTSPRT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSTSIN  DD  *
  DSN SYSTEM(DB2P)
  BIND PACKAGE(APP1COLL) -
       MEMBER(ACCTUPD) -
       ACTION(REPLACE) -
       ISOLATION(CS) -
       VALIDATE(BIND)
  END
/*

When this job fails, read SYSTSPRT and SYSPRINT before changing the bind cards. The messages usually show whether the problem is an authorization issue, missing DBRM, invalid option, unavailable subsystem, or SQL object problem.

RUN PROGRAM example

RUN can execute an application program through DSN. Many production sites use normal batch JCL or schedulers for application execution, but RUN is still useful in examples and controlled test jobs.

//RUNPGM   EXEC PGM=IKJEFT01
//STEPLIB  DD  DISP=SHR,DSN=DB2P.SDSNLOAD
//         DD  DISP=SHR,DSN=APP1.LOADLIB
//SYSTSPRT DD  SYSOUT=*
//SYSTSIN  DD  *
  DSN SYSTEM(DB2P)
  RUN PROGRAM(ACCTUPD) PLAN(ACCTPLAN)
  END
/*

If the program starts but fails during SQL execution, move from DSN diagnostics to application diagnostics: SQLCODE, SQLSTATE, SQLERRMC, package name, plan name, and the business key being processed.

DCLGEN and SPUFI usage

DCLGEN

DCLGEN creates host-variable declarations that match a table or view. For COBOL teams, it helps keep copybooks consistent with Db2 column names and data types. Regenerate and review DCLGEN output after table changes, especially nullable columns and decimal precision changes.

SPUFI

SPUFI is the SQL processor using file input under ISPF. It is practical for testing SQL, checking catalog rows, or validating a small query before it is added to a program. Keep production fixes in controlled jobs or approved tooling rather than ad hoc foreground edits.

Common mistakes

• Running BIND against the wrong subsystem after copying JCL from test to production.
• Binding a package into the wrong collection and then running a plan that does not reference it.
• Using REBIND without recording the prior access path or fallback plan.
• Deleting a package with FREE before checking dependent jobs and online transactions.
• Ignoring SYSTSPRT and looking only at the job return code.

Quick troubleshooting checklist

Symptom	First checks
Bind job fails	Subsystem name, DBRM library, member name, package collection, owner, qualifier, and bind authority.
Program cannot find package or plan	Collection, package name, plan name, package list, and runtime JCL.
Access path changed after REBIND	RUNSTATS timing, catalog statistics, bind options, and package copy/fallback procedure.
SPUFI SQL works but program fails	Host variables, indicator variables, package bind options, authorization ID, and SQLCA handling.

Related Db2 topics

Use this reference with Db2 Binding Application, Db2 Binding and Rebinding, Db2 Packages, Db2 Commands Quick Reference, and Db2 Application Environment.

FAQ

What is the DSN command in Db2 for z/OS?

DSN is the Db2 command processor that runs as a TSO command. It starts a session where subcommands such as BIND, REBIND, RUN, DCLGEN, and SPUFI can be issued.

Can DSN run in batch?

Yes. DSN commands are often run in batch through IKJEFT01, with the command stream placed in SYSTSIN and output written to SYSTSPRT.

What is the difference between BIND and REBIND?

BIND creates or replaces a package or plan using DBRM input. REBIND refreshes an existing package or plan, often after catalog statistics or environment changes.

Db2 Directory Guide: SPT01, SCT02, DBD01, SYSLGRNX, and SYSUTILX



Db2 manages the directory internally.

A Db2 package can be present in the catalog and still fail at execution time if the internal execution structures are damaged, unavailable, or out of sync. When recovery, bind, or utility processing is involved, Db2 uses directory objects that normal application SQL does not query.

The Db2 directory stores internal control information used by Db2 for operation, package and plan execution, database descriptors, log range tracking, and utility restart. Unlike the catalog, the directory is not a normal SQL reporting source. Db2 and supported utilities maintain it.

What the Db2 directory does

The directory supports Db2 execution and recovery work that must be fast and controlled. It stores internal forms of packages and plans, database descriptors, log ranges used for recovery, and utility status needed for restart. Developers usually learn about it when a bind, run, utility, or recovery problem points below normal catalog metadata.

Directory versus catalog

Area	Purpose	Normal access
Db2 catalog	Stores queryable metadata about objects, privileges, packages, plans, routines, and statistics.	Read with SQL when authorized.
Db2 directory	Stores internal control data used by Db2 for execution, recovery, utility restart, and package or plan processing.	Managed by Db2 and supported utilities, not normal application SQL.

Important Db2 directory objects

Directory object	What it supports	Why it matters
SPT01	Skeleton package table, often called SKPT.	Contains internal package information and access-path data created by BIND PACKAGE and removed by FREE PACKAGE.
SCT02	Skeleton cursor table, often called SKCT.	Contains internal plan information and access-path data created by BIND PLAN and removed by FREE PLAN.
DBD01	Database descriptors.	Stores internal database descriptor information for table spaces, indexes, tables, constraints, and related structures.
SYSLGRNX	Log range tracking.	Helps Db2 locate log ranges needed for recovery of updated table spaces or partitions.
SYSUTILX	Utility execution and restart state.	Stores utility status so Db2 can restart, recover, or terminate utility work correctly.

How directory objects show up in support work

Package or plan execution

When a static SQL program runs, Db2 uses package or plan structures created at bind time. Catalog rows help you identify the package, collection, and validity, but execution also depends on internal structures in the directory. If a bind or free operation fails, support teams often check both catalog state and Db2 messages tied to directory processing.

Recovery and log ranges

SYSLGRNX helps Db2 find the log ranges needed for recovery. If an object has been updated, Db2 can use recorded ranges instead of searching all log data blindly. This matters during RECOVER, restart, and problem diagnosis after an outage.

Utility restart

SYSUTILX is involved when utilities such as REORG, LOAD, COPY, or RECOVER need restart or cleanup handling. If a utility stops, do not delete anything by hand. Use supported commands such as -DISPLAY UTILITY, restart procedures, or -TERM UTILITY only when site rules allow it.

-DISPLAY UTILITY(*)
-TERM UTILITY(utility-id)

Safe handling rules

• Do not update or delete Db2 directory data manually.
• Use supported Db2 commands, bind actions, utilities, and recovery procedures.
• Check the catalog first when the question is about object names, package names, privileges, or statistics.
• Check Db2 messages, utility output, and recovery documentation when the problem points to directory-managed state.
• Escalate directory damage, utility restart confusion, or recovery inconsistencies to the DBA or systems programmer team.

Common mistakes

Treating the directory like catalog tables

The catalog is meant to be queried for metadata. The directory is internal. Treating both as ordinary application data is a support risk.

Terminating utilities without restart context

A utility entry can represent recoverable work. Capture the utility ID, phase, object name, and messages before taking action.

Looking only at package catalog rows

Package catalog rows help identify the package, but a runtime issue may also involve bind output, plan references, load libraries, directory-managed structures, or subsystem messages.

Related Db2 topics

Use this guide with Db2 Catalog, Db2 Packages, Db2 Utilities, Db2 Commands Quick Reference, and Db2 Binding and Rebinding.

FAQ

What is the Db2 directory?

The Db2 directory stores internal control information used by Db2 for package and plan execution, database descriptors, log range tracking, utility restart, and recovery processing.

Can I query the Db2 directory with SQL?

No for normal application or support work. The catalog is the SQL-queryable metadata source. The directory is maintained by Db2 and supported utilities.

What is SYSUTILX used for?

SYSUTILX stores Db2 utility execution and restart information. It helps Db2 restart or clean up utility work after interruption.

Db2 Optimizer Guide: RUNSTATS, EXPLAIN, Indexes, and Access Paths



Optimizer choices depend on SQL, statistics, and indexes.

A batch job can read ten rows or ten million rows from the same table depending on the access path chosen for one SQL statement. The Db2 optimizer is the part of Db2 that evaluates the SQL, catalog statistics, indexes, predicates, and bind options before choosing how to access the data.

For COBOL programs with static SQL, the access path is usually chosen during bind or rebind. That is why a performance fix often includes more than changing the SQL text. RUNSTATS, indexes, predicate form, and bind timing all matter.

What the Db2 optimizer does

The optimizer estimates the cost of possible access paths and chooses one for the SQL statement. It may choose an index access, a table space scan, a nested loop join, a sort, or another method depending on the data and the SQL shape.

Input	How it affects access path choice
SQL text	Predicates, joins, subqueries, sorting, grouping, and selected columns change the possible paths.
Catalog statistics	RUNSTATS data helps Db2 estimate table size, index usefulness, column distribution, and filter factor.
Indexes	Matching columns, clustering, uniqueness, and index-only access can change the selected path.
Bind options	Static SQL access path selection is tied to bind or rebind, so timing and options matter.
Host variables	For static SQL, Db2 may not know the actual runtime value during bind, so predicate design is important.

RUNSTATS gives the optimizer better facts

RUNSTATS collects information about table spaces, tables, indexes, and column values. Without current statistics, the optimizer can choose a path based on old assumptions. A table that grew from 50,000 rows to 50 million rows should not be planned as if it were still small.

RUNSTATS TABLESPACE APPDB.TSORD
  TABLE(ALL)
  INDEX(ALL)
  SHRLEVEL CHANGE

For static SQL, updated statistics do not automatically change an existing package access path. The package normally needs a rebind for Db2 to choose paths using the new statistics. For dynamic SQL, updated statistics can affect later prepares.

Indexes help only when predicates can use them

An index on CUSTOMER_ID is useful when the SQL searches by CUSTOMER_ID in a form Db2 can match. The same index may not help much if the program wraps the column in a function or uses a predicate that prevents matching index access.

-- Better starting point for an indexed CUSTOMER_ID
SELECT CUSTOMER_NAME, CITY
FROM CUSTOMER
WHERE CUSTOMER_ID = :WS-CUSTOMER-ID;

-- Often harder for index matching
SELECT CUSTOMER_NAME, CITY
FROM CUSTOMER
WHERE SUBSTR(CUSTOMER_ID,1,5) = :WS-CUST-PREFIX;

The second query may still be valid SQL, but it asks Db2 to evaluate an expression on the column. If that query is on a high-volume path, review the predicate and index design before accepting the access path.

EXPLAIN shows what Db2 selected

EXPLAIN writes access path information to explain tables such as PLAN_TABLE. It lets a developer or DBA check whether Db2 plans to use an index, scan a table space, sort rows, or join tables in a certain order.

EXPLAIN PLAN FOR
SELECT ORDER_NO, ORDER_DATE
FROM ORDERS
WHERE CUSTOMER_ID = 'C00001234'
  AND ORDER_DATE >= DATE('2026-01-01');

EXPLAIN output should be reviewed with the real table design and statistics in mind. A table space scan is not always bad, and an index access is not always good. The question is whether the selected path fits the row counts, filter factors, and job runtime target.

Static SQL, bind, and rebind

In a COBOL static SQL program, the DBRM is bound into a package or plan. That bind step is where Db2 selects access paths for the static statements. If a table grows, an index changes, or RUNSTATS is refreshed, the package may need a rebind to pick up a better path.

This is why a release checklist should include both application build evidence and database performance evidence. A program can pass functional testing while still carrying an old access path that hurts the nightly batch window.

Optimizer checklist for COBOL SQL

• Run or confirm RUNSTATS after major load, purge, or reorganization activity.
• Check whether static packages need rebind after statistics or index changes.
• Use EXPLAIN for SQL that reads high-volume tables or appears in long-running jobs.
• Keep predicates simple enough for matching index access where the business rule allows it.
• Review host variable data types so Db2 does not have to handle avoidable conversions.
• Check ORDER BY, GROUP BY, DISTINCT, and join predicates for sort and join cost.

Common optimizer surprises

Symptom	What to check
A job slows down after a large data load	RUNSTATS timing, package rebind, and whether the old access path assumed smaller tables.
An index exists but Db2 scans the table space	Predicate form, column order in the index, filter factor, and whether the scan is actually cheaper.
A query sorts a large work file	ORDER BY, GROUP BY, DISTINCT, index order, and selected columns.
Two similar programs perform very differently	Package bind time, collection, bind options, host variable types, and statement text differences.

Related DB2 topics

The optimizer connects directly to Db2 SQL Optimization Tips for COBOL Programs, Db2 Indexing, Db2 Binding and Rebinding, Db2 Binding an Application, and Db2 Data Types.

FAQ

Does RUNSTATS change a static SQL access path by itself?

No. RUNSTATS updates statistics. For static SQL, a package generally needs a bind or rebind before Db2 can choose a new access path from those statistics.

Is index access always faster than a table space scan?

No. If a query reads a large part of the table, a scan can be cheaper than many index lookups. EXPLAIN and real row counts matter.

Why can the same SQL run differently in test and production?

Statistics, table size, indexes, bind time, bind options, and host variable values can differ between environments. Compare the package and EXPLAIN details before changing code.

For slow SQL, start with the access path evidence. Guessing from the SQL text alone is how small problems grow into long batch nights.

Db2 Binding an Application: COBOL DBRM, Package, Plan, and Run JCL



Bind the DBRM before the program runs.

A COBOL program with embedded SQL does not run against Db2 just because the load module was created. The SQL has to be precompiled into a DBRM, the program has to be compiled and link-edited, and Db2 must have a package or plan that matches what the program calls at run time.

That is the point of application binding. It connects the program's static SQL to Db2 access paths before the batch job, CICS transaction, or IMS program reaches production.

Where binding fits in the COBOL build

A typical static SQL build has four moving parts. If one of them is missing or from the wrong compile, the job can fail even when the COBOL source looks correct.

Build part	What it creates	Why it matters
Db2 precompile	Modified COBOL source and a DBRM member	The DBRM contains the static SQL that Db2 will bind.
COBOL compile	Object module	The embedded SQL calls have already been replaced with host-language calls.
Link-edit	Executable load module	The load module calls the Db2 language interface at run time.
Bind	Package and plan entries in Db2	Db2 stores executable forms of the SQL statements and the selected access paths.

Precompile creates the DBRM

The Db2 precompiler reads the COBOL source and finds each EXEC SQL block. It checks SQL syntax, handles host variable references, includes members such as SQLCA or DCLGEN copybooks when requested, and writes a DBRM member to a partitioned data set.

The DBRM is not the same as the COBOL object module. It is the Db2-side input for binding. In many shops the member name matches the program name, such as PAYRPT01, because that makes the bind JCL and promotion controls easier to audit.

//PC.SYSIN    DD  DSN=APP.SOURCE(PAYRPT01),DISP=SHR
//PC.SYSCIN   DD  DSN=APP.WORK.COBOL(PAYRPT01),DISP=SHR
//PC.DBRMLIB  DD  DSN=APP.DBRMLIB(PAYRPT01),DISP=SHR

Bind the package from the DBRM

For most production applications, bind the DBRM as a package and include the package in a plan. A package keeps the bind unit close to one program module, so a change to one COBOL program does not force every related DBRM in a large plan to be rebound.

BIND PACKAGE(APP01)
  MEMBER(PAYRPT01)
  ACTION(REPLACE)
  ISOLATION(CS)
  CURRENTDATA(NO)
  QUALIFIER(PROD)

The exact bind options depend on the shop standard and workload. For example, a read-only reporting program may use different lock and isolation choices from an update program that posts end-of-day financial rows. Do not copy a bind card from another application without checking the program's SQL behavior.

Bind the plan used by run JCL

The application plan tells the run command which packages can be used. A common pattern is to bind packages into a collection and then bind a plan with a package list.

BIND PLAN(PAYPLAN)
  PKLIST(APP01.PAYRPT01)
  ACTION(REPLACE)

Some sites use a wildcard package list such as APP01.* for a controlled collection. That can reduce plan maintenance, but it should still be managed by promotion rules so test packages do not accidentally become callable from production jobs.

Run JCL must point to the right plan

After compile, link-edit, package bind, and plan bind, the batch job still has to call the expected plan. A typical DSN run step names the Db2 subsystem, program, plan, and application load library.

//RUNSQL  EXEC PGM=IKJEFT01
//STEPLIB DD  DSN=DSN.V12.SDSNLOAD,DISP=SHR
//SYSTSIN DD  *
  DSN SYSTEM(DSN1)
  RUN PROGRAM(PAYRPT01) PLAN(PAYPLAN) -
      LIB('APP.PROD.LOADLIB')
  END
/*
//SYSPRINT DD SYSOUT=*

If the run step names an old plan, a test collection, or the wrong load library, the program may call a package that does not match the current DBRM. That is why a release checklist should compare the load module, DBRM member, package bind, plan bind, and run JCL before the job is released.

Common bind failures and runtime clues

Binding problems usually show up in the bind output, Db2 messages, or SQLCODE returned to the program. The exact message text matters, so always check the Db2 output from the failing job before changing bind options.

Symptom	Likely area to check
Bind fails because a table or view cannot be found	Check the qualifier, owner, current environment, and whether the object exists in that subsystem.
Bind fails because the user is not authorized	Check package, plan, table, view, and execute privileges for the bind owner.
Runtime SQLCODE points to package not found	Check package collection, plan package list, subsystem, and whether the package was promoted.
Runtime SQLCODE points to timestamp or consistency mismatch	Check whether the load module and DBRM/package came from the same precompile.

Application bind checklist

• Use the DBRM created from the same source version that produced the load module.
• Keep DBRM library, load library, package collection, and plan name visible in promotion records.
• Bind changed programs as packages instead of rebinding a large plan directly from many DBRMs.
• Review QUALIFIER, OWNER, VALIDATE, isolation, and current data options against the application type.
• Confirm the run JCL names the intended plan and load library before moving the job to production.

Related DB2 topics

Application binding sits close to several other Db2 topics. Review Db2 Binding and Rebinding for package and plan maintenance, Db2 Packages for package structure, Db2 Objects for database object context, and Db2 SQL Optimization Tips for COBOL Programs for access path review.

FAQ

Is a DBRM the same as a package?

No. The DBRM is produced by the precompile step. A package is created when Db2 binds that DBRM into the catalog and directory.

Can a COBOL Db2 program run without a bind?

A static SQL COBOL program needs a valid package or plan before it can run successfully against Db2. Dynamic SQL follows a different prepare path at run time.

Why does a program fail after a successful compile?

The compile only proves the host language build completed. The run can still fail if the DBRM was not bound, the plan does not include the package, or the load module and package do not match.

For production, treat bind output as part of the build evidence. A clean compile without the matching DBRM, package, plan, and run JCL is not enough.

DB2 BIND and REBIND: What They Do and When to Run Each



Binding turns static SQL into a runnable package.

A COBOL program with embedded SQL does not become runnable after compile alone. The SQL is precompiled into a DBRM, bound into a package, connected to a plan or package list, and then used by the job, CICS transaction, or IMS program at runtime.

This refresh explains Db2 binding and rebinding for mainframe developers: what BIND does, why REBIND is used, how collections and package sets affect runtime lookup, and what to check before promoting a changed program.

Where Binding Fits in a COBOL Db2 Build

A typical static SQL build has these steps:

1. Precompile the COBOL source and extract SQL into a DBRM.
2. Compile the modified COBOL source.
3. Link-edit the load module.
4. Bind the DBRM into a package.
5. Bind or use a plan that includes the package.

If the package is missing or the plan cannot find it, the program can compile cleanly and still fail at runtime.

What BIND PACKAGE Does

BIND PACKAGE takes a DBRM and creates a package. During bind, Db2 validates SQL, checks object names, checks authorization, and selects an access path for static SQL statements.

BIND PACKAGE(CERTCOL)
     MEMBER(CERTPGM)
     ACTION(REPLACE)
     ISOLATION(CS)
     OWNER(DB2USER1)
     QUALIFIER(DB2USER1)

The package becomes the stored form of the program's static SQL. The access path chosen at bind time can change when statistics, indexes, SQL text, or bind options change.

What BIND PLAN Does

A plan is the runtime object that lets an application execute Db2 SQL. Modern static SQL designs usually bind DBRMs into packages and then bind a plan that references package collections through PKLIST.

BIND PLAN(CERTPLAN)
     PKLIST(CERTCOL.*)
     ACTION(REPLACE)
     ISOLATION(CS)

Using package lists means packages can be added or replaced in a collection without rebinding the plan every time.

Collections and Package Names

A collection is a group of associated packages. A package name is commonly referenced as collection.package. The collection is implicitly created the first time a package is bound into that collection.

Collections are useful for separating environments or application versions. For example, test packages can use CERTCOL while production packages use a different collection name.

CURRENT PACKAGESET

The CURRENT PACKAGESET special register can direct package lookup to a specific collection for dynamic package resolution scenarios. Older applications sometimes use it to force package searches into a chosen collection.

EXEC SQL
    SET CURRENT PACKAGESET = 'CERTCOL'
END-EXEC.

Use this carefully. If the collection name is wrong, the application can fail even when the package exists somewhere else.

What REBIND Does

REBIND rebuilds an existing package or plan without changing the source program. It is commonly used after RUNSTATS, index changes, catalog changes, or Db2 maintenance when access paths need to be refreshed.

REBIND PACKAGE(CERTCOL.CERTPGM)

REBIND can change access paths. That is useful when statistics have improved, but risky when a critical batch job depends on a stable path. Review high-risk packages before rebinding in production.

BIND ADD, BIND REPLACE, and REBIND

Action	Use when	Common risk
ACTION(ADD)	Creating a new package or plan.	Fails if the object already exists.
ACTION(REPLACE)	Program SQL changed and the package must be replaced.	Can replace the wrong collection member if naming is sloppy.
REBIND	Program did not change, but access path or bind options need refresh.	Can change a stable access path after statistics or index changes.

Binding While a Package Is in Use

Packages and plans can be locked during execution and bind processing. A package or plan generally cannot be rebound while the same object is actively running. A different package version, however, can be bound depending on how versioning and collections are set up.

This is why batch windows and CICS availability matter. Rebinding a package used by a high-volume transaction is not the same as rebinding a rarely used report package.

Bind Options That Affect Programs

Bind options can affect runtime behavior. Some options control isolation, ownership, qualifier resolution, package lookup, and environment restrictions.

BIND PLAN(CICSONLY)
     PKLIST(CERTCOL.*)
     ACTION(REPLACE)
     ISOLATION(CS)
     OWNER(DB2USER1)
     QUALIFIER(DB2USER1)
     ENABLE(CICS)

These settings should be reviewed as deployment controls, not just DBA syntax.

Freeing or Dropping Packages

Use FREE to remove packages or plans from the catalog when they are no longer needed.

FREE PACKAGE(CERTCOL.*)

A package can also be removed with SQL in environments that support the statement and required authorization:

DROP PACKAGE DB2USER.DB2CERT

Do not remove a package just because a load module is old. Confirm runtime references, collection usage, and fallback needs first.

Promotion Checklist

• Confirm the DBRM member matches the COBOL source level.
• Bind into the correct collection.
• Confirm the plan or package list can find the package.
• Review changed access paths for high-volume SQL.
• Check authorization for the bind owner and runtime auth ID.
• Keep fallback package/version details for production rollout.

How Binding Relates to Packages

This article focuses on bind and rebind actions. For a wider explanation of package structure, collections, plans, DBRMs, and static SQL promotion, see Db2 Packages Guide for COBOL Static SQL.

For access-path checks after bind or rebind, see Db2 SQL Optimization Tips for COBOL Programs and Db2 Indexing.

FAQ

What is the difference between BIND and REBIND in Db2?

BIND creates or replaces a package or plan from DBRM input. REBIND rebuilds an existing package or plan, often to refresh access paths after statistics, index, or catalog changes.

Does REBIND require a COBOL program change?

No. REBIND is commonly used when the program did not change but Db2 should reconsider access paths or bind options.

Why do collections matter in Db2 packages?

A collection groups related packages and helps plans or package lookup find the correct package version at runtime.

Binding is not an afterthought after compile. It is the point where Db2 validates the SQL, checks authority, and chooses the access path your COBOL program will use.

Db2 Packages Guide for COBOL Static SQL



Db2 packages hold prepared SQL and access paths.

A COBOL program with static SQL does not carry its access path inside the load module. During precompile, Db2 extracts embedded SQL into a DBRM. During bind, Db2 turns that DBRM into a package that records prepared SQL, bind options, authorization context, and the access path chosen for the SQL statements.

This refresh replaces the old C-oriented explanation with a Db2 for z/OS package guide for COBOL teams. It covers DBRMs, collections, packages, plans, BIND PACKAGE, REBIND, and the checks developers should make before promoting a static SQL change.

What Is a Db2 Package?

A Db2 package is a database object that contains the prepared form of static SQL statements from one program or routine. IBM's BIND PACKAGE documentation says the subcommand builds an application package, records the package description in catalog tables, and saves the prepared package in the directory.

For a COBOL application, the package is the Db2-side partner to the compiled and linked load module. If the load module and package do not match the same SQL level, the program can fail or run with the wrong assumptions.

COBOL Static SQL Build Flow

The build path matters because each output has a different job. The COBOL compiler handles host language code. Db2 handles embedded SQL through the DBRM and bind process.

Step	Output	Why it matters
Precompile	Modified COBOL source and DBRM	Separates SQL from COBOL source.
Compile and link-edit	Load module	Creates executable program code.
BIND PACKAGE	Package in a collection	Prepares static SQL and records access paths.
BIND PLAN or package list	Runtime plan reference	Connects run unit to packages.

DBRM, Package, Collection, and Plan

These four terms often get mixed together in incident calls. Keep them separate.

Term	Meaning	Common problem
DBRM	Database request module created by precompile.	Wrong DBRM library used during bind.
Package	Bound SQL from a DBRM or copied package.	Package not rebound after SQL or statistics change.
Collection	Named group that contains packages.	Runtime points to the wrong collection.
Plan	Runtime object that can include a package list.	Plan does not include the expected package collection.

BIND PACKAGE Example

Site JCL and options vary, but a package bind normally identifies the collection, DBRM member, action, owner or qualifier options, isolation level, and validation behavior.

BIND PACKAGE(ACCTCOLL) -
     MEMBER(ACCTPOST) -
     ACTION(REPLACE) -
     QUALIFIER(ACCT) -
     ISOLATION(CS) -
     VALIDATE(BIND) -
     EXPLAIN(YES)

Do not copy bind options blindly. ISOLATION(UR), RELEASE(DEALLOCATE), VALIDATE(RUN), and REOPT can be correct in one workload and wrong in another. Use the site standard unless there is a documented reason to deviate.

Package and Access Path

For static SQL, the access path is selected at bind or rebind time. That is why a COBOL program can slow down after a package rebind even when source code did not change. New RUNSTATS, index changes, subsystem function level, bind options, and SQL changes can all affect the path.

• Capture EXPLAIN output when binding important packages.
• Record the DBRM library, collection, package, and version used in the change.
• Compare access paths before and after a rebind for high-volume programs.
• Know the rollback option if the new package performs badly.

The related Db2 SQL Optimization Tips for COBOL Programs article covers access-path investigation in more detail.

REBIND PACKAGE

A rebind rebuilds an existing package using the current environment and selected options. It is common after RUNSTATS, index changes, SQL compatibility changes, or package maintenance. Rebind is powerful because it can improve performance without changing COBOL source, but it can also choose a worse path if statistics or options are wrong.

REBIND PACKAGE(ACCTCOLL.ACCTPOST) -
       APREUSE(WARN) -
       EXPLAIN(YES)

For production packages, make the rebind visible in the change record. Include package name, collection, owner, bind options, reason, expected benefit, and fallback plan.

Common Package Problems

Symptom	Likely package issue	Check
Program works in test but fails in production.	Different collection or missing package.	Plan PKLIST, collection, package name, and version.
SQL starts running slowly after maintenance.	Access path changed during rebind.	EXPLAIN before/after and RUNSTATS timing.
Authorization error appears at bind or run time.	Owner or VALIDATE option mismatch.	Package owner, binder authority, and object grants.
Old load module calls new SQL package.	Promotion mismatch.	Load library, DBRM, package timestamp, and change ticket.

Developer Checklist

• Confirm the DBRM was generated from the same source level as the load module.
• Confirm the package collection used by the runtime plan.
• Review bind options with the DBA for high-volume programs.
• Use EXPLAIN for SQL that can affect batch windows or online response time.
• Keep package rollback details in the implementation plan.
• Coordinate package changes with related DB2 Binding and Rebinding procedures.

FAQ

Is a Db2 package the same as a plan?

No. A package contains prepared SQL for a program or routine. A plan is a runtime object that can reference packages through a package list.

When should a package be rebound?

Rebind after relevant SQL, index, statistics, compatibility, or bind-option changes. For critical packages, compare access paths before and after the rebind.

Can a COBOL program run without its package?

No, static SQL needs the corresponding package or plan/package setup at runtime. The load module and Db2 package must be promoted together.

Package work is successful when the COBOL load module, DBRM, package collection, bind options, and access path all line up. Treat the package as part of the application deliverable, not an afterthought.