Binder Source (also known as binder language) is the mechanism ILE uses to allow the designer the ability to export individual sub-procedures from a given service program. Additionally, binder language provides the ability to support a 'service program signature,' which serves a similar role as the record format level check between the service program and the consumer of sub-procedures from that service program. Finally, binder language allows one to support multiple signatures, providing support for previous releases of the service program.
Binder language is documented in the ILE Concepts guide (V5R4).
To use binder language, specify
EXPORT(*SRCFILE) on the CRTSRVPGM command. Note that this is not the default. The default,
EXPORT(*ALL) tells the system to generate a signature automatically, and that signature is a hexadecimal string much like the record format level is. The generated signature is based on the names of the exports and their order.
Binder source is stored in a source file. The default name is
QSRVSRC record length 92. There are three binder language parameters:
The simplest form of binder language has a single
EXPORT for each export and a single
ENDPGMEXP. An example (from the manual) looks like this:
STRPGMEXP PGMLVL(*CURRENT) EXPORT SYMBOL('Term') EXPORT SYMBOL('Rate') EXPORT SYMBOL('Amount') EXPORT SYMBOL('Payment') ENDPGMEXP
STRPGMEXP we see that this is the current signature (all consumers must have this signature or suffer a signature violation at run-time) and that the system will generate the actual 16 byte signature (because we did not specify one.)
4 procedures are exported (made available for consumers to use.) The quotes are significant: without them, the actual exported symbol name would be uppercased. Wrapped in quotes, the mixed case name is preserved. Be very aware that the consumer MUST match the case exactly!
ENDPGMEXP tells the binder that there are no more exports for this signature.
A slightly more advanced version would specify the signature, rather than let the system generate it.
STRPGMEXP PGMLVL(*CURRENT) SIGNATURE('01.00 2008.05.29') EXPORT SYMBOL('Term') EXPORT SYMBOL('Rate') EXPORT SYMBOL('Amount') EXPORT SYMBOL('Payment') ENDPGMEXP
The signature can be up to 16 bytes long. If shorter, the binder will issue a warning that it was padded. If longer, the binder will issue a warning that it was truncated. Hyphens (the dash character) are not allowed (as in 2008-05-29) but slashes are (2008/05/29).
There are two broad views on the concept of signatures.
1) The designer doesn't know or care about the signature. Every time a change is made to the service program, the system generates a new signature and all consumers are re-compiled to match the new signature.
2) The designer specifies a signature and carefully manages the binder source to avoid creating problems when the service program is updated/re-created. This is very easy to do. Follow these rules:
- Never remove an export
- Never insert an export in the middle of the existing list, but only at the bottom
- Never re-arrange the order of the exports (say, to alphabetise them)
- Never rename an export
If these rules are followed, it's very possible to use a single signature for every version of the service program. That is, only one single
STR/ENDPGMEXP block, with new procedure exports added at the bottom during maintenance. This is not illustrated in the ILE Concepts guide. The examples there have a separate
STR/ENDPGMEXP block for each version, with a different signature for each one. This might have some value if you don't have a source/version control system because the signatures (in plain language) are easily viewed via DSPPGM and DSPSRVPGM.