RPGLE Binding Directories Reference

A binding directory (*BNDDIR) is a list of module and service program names that the binder searches when a program or service program has imports it cannot resolve. It saves you from naming every service program on every compile. This page is the lookup for what the list holds, the order in which the binder uses it, how RPGLE names one, and the commands that maintain it.

It owns the search rules and the commands. For the packaging model in plain terms, read IBM i Modules, Bound Programs, and Binding Directories Explained. For a short walk-through next to service program creation, read Build an ILE RPG Service Program.

What a binding directory is

IBM: “A binding directory lists the names of modules and service programs that you may need when creating an ILE program or service program. Modules or service programs listed in a binding directory are used only if they provide an export that can satisfy any currently unresolved import requests.”

Fact	Detail
Object type	`*BNDDIR`
Optional	Yes. The reasons to use one are convenience and program size
Entries	Names only: object name, object type and library
Entry types	`SRVPGM` (the default when adding) or `MODULE`
Library in an entry	`*LIBL` or a specific library name
Object must exist	No. A name can be added even if the object does not exist yet
Cost	The more entries a directory has, the longer binding may take, so list only what is needed
Program size	A listed object that is not needed to resolve an import is not bound, which keeps programs smaller

How the binder searches

When it creates a program or service program, the binder works in this order. It stops looking in directories as soon as every import is resolved.

Step	What is examined	Bound when
1	The modules on the `MODULE` parameter	Always, in the order listed
2	The service programs on `BNDSRVPGM`	Only if needed to resolve an import
3	The binding directories on `BNDDIR`, in the order listed, and the entries of each in the order listed	Only if needed to resolve an import
4	The binding directories that each bound module lists as reference system objects	Only if needed to resolve an import

More rules from IBM:

Duplicate entries in binding directories are silently ignored.
Message CPD5D03, “Definition supplied multiple times for symbol”, can be signalled while an object is examined, even if that object is not bound in the end.
Processing stops when all imports are resolved, even with OPTION(*UNRSLVREF).
Modules usually have imports that are not visible in the source, added by the compiler for language runtime support. DSPMOD DETAIL(*IMPORT) shows them, and DSPMOD DETAIL(*REFSYSOBJ) shows the reference system binding directories.
CRTPGM or CRTSRVPGM with DETAIL(*EXTENDED) lists the objects that were examined. DSPPGM or DSPSRVPGM with DETAIL(*MODULE) or DETAIL(*SRVPGM) shows what was bound.

Entries are examined in the listed order and bound only if needed, so if two entries could supply the same name, put the one you intend first.

Naming one in RPGLE

Where	Form	Notes
Control specification	`ctl-opt bnddir('MYLIB/REFBND');`	Several names are separated by colons
`CRTBNDRPG`	`BNDDIR(MYLIB/REFBND)`	Up to 50 names. Not allowed with `DFTACTGRP(*YES)`
`CRTPGM`, `CRTSRVPGM`	`BNDDIR(MYLIB/REFBND)`	Up to 300 names

IBM’s rules for the control keyword:

A name can be qualified with a library. Without one, *LIBL is used.
With CRTBNDRPG, the library list is searched at compile time. With CRTRPGMOD, the library list is searched later, when the module is used to create a program or service program.
If BNDDIR is on both the control specification and the command, all the directories are used. The control specification does not override the command.
You cannot use BNDDIR, ACTGRP or STGMDL when creating a program with DFTACTGRP(*YES). In a compilation with a free-form ctl-opt that names any of ACTGRP, BNDDIR or STGMDL, DFTACTGRP(*NO) is assumed.

**free
ctl-opt dftactgrp(*no) actgrp('REFDEMO') bnddir('REFBND');

dcl-pr refDouble int(10);
  inNumber int(10) const;
end-pr;

dsply ('Result: ' + %char(refDouble(21)));
*inlr = *on;

The control specification names the directory. The binder uses it only for the unresolved import REFDOUBLE, and binds the service program that exports it.

Commands

Task	Command	Notes
Create	`CRTBNDDIR`	An empty directory
Add an entry	`ADDBNDDIRE`	Up to 50 entries in one command
Remove an entry	`RMVBNDDIRE`
Display	`DSPBNDDIR`
Work with	`WRKBNDDIR`, `WRKBNDDIRE`
Delete	`DLTBNDDIR`

ADDBNDDIRE

Parameter	Values	Default
`BNDDIR`	Qualified name of the directory	Required
`OBJ`	Object name (or `*ALL`, or a generic name), type and activation, each entry with its library	Required
Object type	`SRVPGM`, `MODULE`	`*SRVPGM`
Activation	`IMMED`, `DEFER`	`*IMMED`
`POSITION`	`LAST`, `FIRST`, or `AFTER`, `BEFORE`, `*REPLACE` with an entry	`*LAST`

Activation applies to the service program once bound. *IMMED means the service program is activated when the program or service program that was created from the directory is activated. *DEFER means activation may wait until a function it exports is called.

CRTBNDDIR BNDDIR(MYLIB/REFBND)
ADDBNDDIRE BNDDIR(MYLIB/REFBND) OBJ((MYLIB/REFUTIL *SRVPGM))
DSPBNDDIR BNDDIR(MYLIB/REFBND)
RMVBNDDIRE BNDDIR(MYLIB/REFBND) OBJ((MYLIB/REFUTIL *SRVPGM))

Binding directory or BNDSRVPGM

	`BNDSRVPGM`	`BNDDIR`
What it names	Service programs	Modules and service programs
Searched	After the `MODULE` list	After `BNDSRVPGM`
Best for	A few service programs one program needs	A set that many programs share
Maintained	In each create command	Once, in the directory

Unresolved imports

When an import cannot be resolved, check in this order:

The prototype name matches the exported name. RPGLE exports in upper case, so refDouble is REFDOUBLE.
The service program or module has an entry in a directory the create command names, or is named on BNDSRVPGM or MODULE.
The library in the entry is on the library list at bind time, or the entry names the library.
The service program really exports the symbol. Use DSPSRVPGM DETAIL(*PROCEXP).
Rerun with DETAIL(*EXTENDED) and read the binder listing.

Common mistakes

Expecting a binding directory to bind an object that supplies no needed export. It is only searched.
Adding an object and not naming the directory on the create command or control specification.
Using DFTACTGRP(*YES) with BNDDIR.
Relying on *LIBL entries and then binding from a job with a different library list.
Letting a directory grow with unused entries, which lengthens binding.
Assuming a control-specification BNDDIR replaces the command’s.
Expecting the directory to be consulted again at run time. Binding happens when the program is created.

FAQ

What does a binding directory do?

It gives the binder a list of names to search for exports that the modules and service programs you named do not already supply.

Is a binding directory required?

No. It is optional. You can list every module and service program on the create command instead.

Does a binding directory contain the service programs?

No. It holds names, so the objects need not exist when the entry is added.

Does the order of entries matter?

Yes. The binder examines entries in the listed order and binds an object only if it is needed to resolve an import.

Summary

A *BNDDIR is a list of module and service program names, searched only for unresolved imports.
Order of search: MODULE, then BNDSRVPGM, then BNDDIR, then the directories listed by bound modules.
Name one in RPGLE with ctl-opt bnddir(...) or the BNDDIR parameter. Neither works with DFTACTGRP(*YES).
Maintain entries with CRTBNDDIR, ADDBNDDIRE and RMVBNDDIRE.
Related: the RPGLE Service Programs Reference, the RPGLE Binder Language and Signatures Reference and the RPGLE Activation Groups Reference.

Sources: IBM i 7.5 ILE Concepts (Binding Directory, Binding Directory Processing), the IBM i 7.5 ILE RPG Reference (BNDDIR and DFTACTGRP control keywords) and the IBM i 7.5 command pages for ADDBNDDIRE and CRTBNDRPG. The examples have been reviewed against that text. They have not been compiled or run.