Binder Source

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.

Documentation

Binder language is documented in the ILE Concepts guide (V5R4).

Use

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:

• STRPGMEXP
• EXPORT
• ENDPGMEXP

The simplest form of binder language has a single STRPGMEXP, one 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

From the 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!

The 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).

Signature concepts

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.

Categories

This article is a stub. You can help by editing it.