|
A Practical Way to Add Exports to a Service Program
Published: October 15, 2008
by Ted Holt
My life was confusing enough already. Then along came IBM with binder language, the CL-like language we use to define the list of exports of a service program. Awhile back I sat down to try to find an effective way to deal with service program exports. Here's what I came up with.
When you create a service program, you must list the exports, that is, the data and/or modules that are available to callers. There is a shortcut. If you specify EXPORT(*ALL) in the Create Service Program (CRTSRVPGM) command, the system will generate the list of exports for you. However, you don't have any guarantee that the generated list will be compatible with existing callers, therefore you will need to rebind the newly created service program to existing callers. You can use binder language to avoid the rebinding process, because binder language gives you a way to order the list of exports.
Binder language is stored in physical file members, like RPG, CL, and DDS source code. Create a source physical file called QSRVSRC. I recommend you put it and the source code for all the modules in the same library.
The first line of a binder language source member is the Start Program Export (STRPGMEXP) command. The last line is the End Program Export (ENDPGMEXP) command. Between the two, use the EXPORT command to list each export. Here's an example:
strpgmexp pgmlvl(*current) lvlchk(*yes) signature('BR549')
export symbol('JUNIOR')
export symbol('SAMPLES')
endpgmexp
Notice that the STRPGMEXP command has three parameters:
- PGMLVL (program level) may be *CURRENT, to indicate that the list of exports is the current list of exports, or *PRV, to indicate that the list of exports is that of a previous version of the service program. You may have one *CURRENT list and one or more *PRV lists.
- LVLCHK (level check) determines whether callers will perform level checking on a service program at run-time (*YES) or not (*NO). If a caller finds that the list of exports for a service program has been changed, it issues message MCH443 (program signature violation).
- In the SIGNATURE parameter, You may specify a signature of 16 bytes or less, or you may use the special value *GEN to tell the system to generate a signature. SIGNATURE(*GEN) is required with LVLCHK(*NO).
Suppose we have a service program, NUMBERS, which is made of one module, also called NUMBERS, which consists of two subprocedures, THREE and FOUR.
H nomain
D/copy prototypes,numbers
P Three b export
D pi 5i 0
/free
return 3;
/end-free
P e
* =========================================
P Four b export
D pi 5i 0
/free
return 4;
/end-free
P e
For completeness, here's the prototype referred to in the source.
D Three pr 5i 0
D Four pr 5i 0
Which of the various combinations of the STRPGMEXP parameters would be most conducive to change? That is, what binder language would be easy to add exports to? What binder language would not require that callers be rebound to the service program? Here's one possibility:
strpgmexp pgmlvl(*current) lvlchk(*yes) signature('NUMBERS')
export symbol('THREE')
export symbol('FOUR')
endpgmexp
Suppose I decide to add three more subprocedures--ONE, TWO, and FIVE--to this module and service program.
H nomain
D/copy prototypes,numbers
P One b export
D pi 5i 0
/free
return 1;
/end-free
P e
* ==========================================
P Two b export
D pi 5i 0
/free
return 2;
/end-free
P e
* ==========================================
P Three b export
D pi 5i 0
/free
return 3;
/end-free
P e
* ==========================================
P Four b export
D pi 5i 0
/free
return 4;
/end-free
P e
* ==========================================
P Five b export
D pi 5i 0
/free
return 5;
/end-free
P e
After I recreate the module, I am ready to recreate the service program. How should I modify the binder language?
I could change the previous binder language to a *PRV signature, and add a new current signature, like this:
strpgmexp pgmlvl(*current) lvlchk(*yes) signature(*gen)
export symbol('ONE')
export symbol('TWO')
export symbol('THREE')
export symbol('FOUR')
export symbol('FIVE')
endpgmexp
strpgmexp pgmlvl(*prv) lvlchk(*yes) signature(*gen)
export symbol('THREE')
export symbol('FOUR')
endpgmexp
But guess what? This binder language won't work. When I run a program that calls this service program, calls to THREE return 1 and calls to FOUR return 2. To ensure that the callers continue to work correctly, I have to add the new exports to the end of the list, like this:
strpgmexp pgmlvl(*current) lvlchk(*yes) signature(*gen)
export symbol('THREE')
export symbol('FOUR')
export symbol('ONE')
export symbol('TWO')
export symbol('FIVE')
endpgmexp
strpgmexp pgmlvl(*prv) lvlchk(*yes) signature(*gen)
export symbol('THREE')
export symbol('FOUR')
endpgmexp
According to my tests, I can add the subprocedures anywhere in the module. The only thing that matters to callers is that the new exports be added to the end of the list.
But if the new exports must be added to the end of the list, why fool around with *PRV lists anyway? For that reason, I use only a *CURRENT signature, to which I give a name, and I add new exports to the end of the list.
strpgmexp pgmlvl(*current) lvlchk(*yes) signature('NUMBERS')
export symbol('THREE')
export symbol('FOUR')
export symbol('ONE')
export symbol('TWO')
export symbol('FIVE')
endpgmexp
The result is the same, and I have less complexity to deal with.
To sum it up:
- Create one *CURRENT signature only.
- Do not create *PRV signatures.
- Name the signature, instead of letting the system generate a name.
- Add new exports to the bottom of the list.
 Post this story to del.icio.us
 Post this story to Digg
 Post this story to Slashdot
|
