RPGLE Binder Language and Signatures Reference

Binder language is the small source language that says which procedures and data a service program exports, and in which order. The order and the names produce the signature that callers are checked against. This page is the lookup for the statements, their parameters, the signature rules and the errors the binder reports.

For a worked example that grows a service program from version 1 to version 2, read Build an ILE RPG Service Program. This page is the statement-by-statement reference. For the object model around it, see the RPGLE Service Programs Reference.

The three statements

IBM describes binder language as “a small set of nonrunnable commands that defines the exports for a service program”.

Statement	Purpose
`STRPGMEXP`	Starts a list of exports. One list is one signature
`EXPORT`	Names one symbol, a procedure or a data item, to export
`ENDPGMEXP`	Ends the list

STRPGMEXP PGMLVL(*CURRENT) SIGNATURE('REFUTIL_VERSION1')
  EXPORT SYMBOL('REFDOUBLE')
  EXPORT SYMBOL('REFLABEL')
ENDPGMEXP

Binder source is kept in a source file member (conventionally in QSRVSRC) or a stream file. CRTSRVPGM reads it with EXPORT(*SRCFILE) and SRCFILE and SRCMBR, or SRCSTMF.

STRPGMEXP parameters

Parameter	Values	Default	Rule
`PGMLVL`	`CURRENT`, `PRV`		Only one `STRPGMEXP` can be `CURRENT`, and it need not be first. All others must be `PRV`
`SIGNATURE`	`*GEN`, a character string or a hexadecimal string	`*GEN`	`*GEN` makes the binder generate the signature from the exported names and their order
`LVLCHK`	`YES`, `NO`	`*YES`	`YES` makes the system check the signature at run time. `NO` is to be used with caution, and requires `SIGNATURE(*GEN)`

IBM’s statement for LVLCHK(*YES): the system verifies that the value matches the value known to the service program’s clients. If it does, clients can use the interface without being bound again.

Multiple STRPGMEXP and ENDPGMEXP pairs in one source create multiple signatures, and their order is not significant. The current signature is the one from the *CURRENT block.

EXPORT SYMBOL

Form	Meaning
`EXPORT SYMBOL('Name')`	Exports the symbol exactly as quoted
`EXPORT SYMBOL(name)`	Without apostrophes the name is converted to upper case
Wildcards `<<<` and `>>>`	Match part of a name. See below

If a name contains lower-case letters, put it in apostrophes. RPGLE exports procedure names in upper case unless extproc gives another name, so 'REFDOUBLE' is the usual form. See the RPGLE Modules and NOMAIN Reference.

Wildcards

A wildcard export must resolve to exactly one symbol. The service program is not created if:

no symbol matches the wildcard,
more than one symbol matches, or
a symbol matches but is not available for export.

Substrings in a wildcard are in quotation marks. IBM’s examples, assuming the symbols interest_rate, international and prime_rate:

Specification	Result
`EXPORT SYMBOL("interest">>>)`	Exports `interest_rate`, the only symbol that starts with `interest`
`EXPORT SYMBOL("i">>>"rate">>>)`	Exports `interest_rate`
`EXPORT SYMBOL(<<<"i">>>"rate")`	Error, multiple matches (`prime_rate` and `interest_rate`)
`EXPORT SYMBOL("inter">>>"prime")`	Error, no match
`EXPORT SYMBOL(<<<)`	Error, matches all three

Changing a wildcard changes the signature even if it matches the same symbol. "r">>> and "ra">>> both export rate but produce two signatures. IBM recommends a wildcard as close as possible to the symbol. The SEU syntax checking type BND cannot be used for source that has wildcards or names longer than 254 characters.

How signatures work

A signature identifies the interface a service program supports. It is not a digital object signature. The symbols between STRPGMEXP PGMLVL(*CURRENT) and ENDPGMEXP define the public interface and its signature.

Choice	What happens
`SIGNATURE(*GEN)`	The signature comes from the exported names and their order. You must add a new export block every time you add exports
An explicit signature	You control the value. You need only one export block, and you add new exports to the end of its list

Reasons IBM gives for an explicit signature:

The binder would generate a compatible signature that you do not want. Two blocks with the same exports in the same order give the same signature, but you may know the interfaces are not compatible. A new explicit signature forces clients to be rebuilt.
The binder would generate an incompatible signature that you do not want. If you know two interfaces are compatible, for example a function was renamed, you can give the same signature as before so that clients need no rebinding.

The 16-byte rule

Signature you give	Result	Message type
Shorter than 16 bytes	Padded to 16	Information
Longer than 16 bytes	Only the first 16 bytes are used	Information
Contains characters not in all CCSIDs, for example `\!`	Not created	Serious error
Contains characters that are not valid, for example `"`	Not created	Serious error

IBM’s advice to avoid the messages is to give exactly 16 bytes. Display the signatures with DSPSRVPGM SRVPGM(MYLIB/REFUTIL) DETAIL(*SIGNATURE).

Making compatible changes

IBM’s rules, which apply whether you give an explicit signature or let the binder generate one:

Do not remove or rearrange existing procedure and data item names in the binder language source.
Additional export blocks must contain the same symbols in the same order as existing blocks.
Add new symbols only to the end of the list.
There is no way to remove an export compatibly with existing programs, because a client might need it.

A version 2 with one added procedure keeps the old list as *PRV. This form assumes version 1 was also built with generated signatures:

STRPGMEXP PGMLVL(*CURRENT)
  EXPORT SYMBOL('REFDOUBLE')
  EXPORT SYMBOL('REFLABEL')
  EXPORT SYMBOL('REFTRIPLE')
ENDPGMEXP

STRPGMEXP PGMLVL(*PRV)
  EXPORT SYMBOL('REFDOUBLE')
  EXPORT SYMBOL('REFLABEL')
ENDPGMEXP

With an explicit signature you could instead keep one block and add REFTRIPLE at the end, as IBM describes. Either way, clients built against the old signature keep working only while a block that produces that signature remains.

This was checked on IBM i V7R5M0. A program bound to version 1 of a service program still ran after the service program was rebuilt with the version 2 list and a *PRV block, and DSPSRVPGM DETAIL(*SIGNATURE) then listed two signatures. After the service program was rebuilt again with only the version 2 list, DSPSRVPGM listed one signature, and calling the old program failed with Program signature violation.

If you make an incompatible change, IBM says it can be made only if every program and service program bound to it is re-created with CRTPGM or CRTSRVPGM.

What a signature does not check

A signature does not validate the interface of a single procedure. If you change a procedure’s parameters so that old callers break, recompile every module that calls it and re-create every program and service program that contains those modules.

Related commands

Command	Use
`RTVBNDSRC`	Generates binder language from the exports of one or more modules or service programs
`DSPSRVPGM DETAIL(*SIGNATURE)`	Shows all signatures of a service program
`DSPSRVPGM DETAIL(*PROCEXP)`	Shows exported procedures
`DSPPGM DETAIL(*SRVPGM)`	Shows the service programs a program is bound to
`CRTSRVPGM` `DETAIL(*EXTENDED)`	Puts the binder language errors in the listing
`UPDSRVPGM` `EXPORT(*CURRENT)`	Keeps the existing variables, procedures and signatures. No new signature

Binder language errors

IBM groups them by severity. With DETAIL(*EXTENDED) or DETAIL(*FULL) on CRTSRVPGM you see them in the spooled listing.

Severity	Messages	What to do
Information	Signature padded, Signature truncated	None needed. Use exactly 16 bytes to avoid them
Warning	Current export block limits interface, Duplicate export block, Duplicate symbol on previous export, Level checking cannot be disabled more than once (ignored), Multiple current export blocks not allowed (previous assumed)	Review the blocks. IBM classes these as warnings, not serious errors
Serious	Current export block is empty, Export block not completed (end of file before `ENDPGMEXP`), Export block not started (`STRPGMEXP` required), Export blocks cannot be nested (`ENDPGMEXP` missing), Exports must exist inside export blocks, Identical signatures for dissimilar export blocks (must change exports), Multiple wildcard matches, No current export block, No wildcard match, Previous export block is empty, Signature contains variant characters, `SIGNATURE(GEN)` required with `LVLCHK(NO)`, Signature syntax not valid, Symbol name required, Symbol not allowed as service program export, Symbol not defined, Syntax not valid	Fix the source and run `CRTSRVPGM` again. IBM states the service program is not created for the cases it illustrates, including wildcard errors, variant characters and invalid syntax

Two that cause most trouble:

Symbol not defined: the name in EXPORT is not a symbol the binder can find. Typically the case differs from the exported name, or the procedure has no export. Check both.
Identical signatures for dissimilar export blocks: two blocks have the same signature but different exports. IBM’s message says to change the exports. If you gave explicit signatures, make them different.

Common mistakes

Quoting 'refdouble' in lower case when the exported name is upper case.
Removing or reordering a symbol in a list that already has a published signature.
Adding a new symbol in the middle of the list.
Using LVLCHK(*NO) with an explicit signature.
Dropping the *PRV block while old programs still use that signature.
Thinking a signature protects a procedure’s parameters. It does not.
Using EXPORT(*ALL) and expecting the signature to stay stable when you add a procedure.

FAQ

What is a signature in ILE?

A value that identifies the interface a service program supports. Programs bound to it record the signature, and the system checks it at run time.

How long is a signature?

16 bytes. Shorter values are padded and longer values are cut to their first 16 bytes.

Do I need binder source?

Not strictly. EXPORT(*ALL) exports everything the modules export, but you give up control of the interface and the signature. Binder source is how you keep compatible versions.

How do I add a procedure without rebinding callers?

Add its EXPORT at the end of the list, and either give an explicit signature and keep it, or add a new *CURRENT block and keep the old list as *PRV.

Summary

Binder language has STRPGMEXP, EXPORT and ENDPGMEXP. One block is one signature.
PGMLVL is *CURRENT for one block and *PRV for the rest. SIGNATURE defaults to *GEN, and LVLCHK defaults to *YES.
Never remove or rearrange exports. Add only at the end.
A signature is 16 bytes and does not check individual procedure interfaces.
Related: the RPGLE Service Programs Reference, the RPGLE Modules and NOMAIN Reference and the RPGLE Binding Directories Reference.

Sources: IBM i 7.5 ILE Concepts (the Binder Language section and Binder Language Errors), and the IBM i 7.5 command pages for CRTSRVPGM, UPDSRVPGM and DSPSRVPGM. The examples have been reviewed against that text. They have not been compiled or run.