Exports and Signature in Service Program for IBM i

如果你遇到过“Program signature violation” 这样的错误，那么这个文章值得你一读。

 

Exports and Signature in Service Program

 

Have you been hit by the message MCH4431 “Program signature violation” on OS/400?   If so, how do you do?  DSPMSGD MCH4431 says that the source program specifies a signature which is not supported by service program. The cause is that the service program interface has changed. The recovery method of the system suggestion is rebinding source program. However, sometimes, it is possible that a service program is bound by hundreds to thousands of programs. If the service program has changed, do we have to re-compile all those hundreds or thousands of programs? The answer is NOT. It is possible to update a service program without having to re-create the other ILE programs or service programs that use the updated service program. The programmer making the changes to the service program can control whether the change is compatible with the existing support.  For we achieve this objective, we need understand exports and signature in service program.

 

 

1. Exports

 

A service program is a collection of runnable procedures and available data items

easily and directly accessible by other ILE programs or service programs.  It likes an inventory of procedures or data items.  For other programs or service programs can access these procedures or data items in the service program, the service program need list a public interface. The public interface can be also called exports.  All procedures or data items can be exported to be known to other ILE objects.  Of cause, the programmer should has the decision to specify which procedures or data items can be known to other ILE objects. Therefore, a service program can have hidden or private procedures and data that are not available to any other ILE object.

 

If the programmer doesn’t want to specify the exports in service program, then he can leave the option EXPORT to ‘*ALL’ when creating service program (using CRTSRVPGM). If the programmer want to specify the exports in service program, then he need edit a source file named binder language to specify those procedures and data items which need be exported in the service program, then he can need select the option EXPORT to ‘*SRCFILE’  and  specify the edited binder language as export source file when using CRTSRVPGM.  

 

We can display the exports of procedures or data items in a service program using the command:

 DSPSRVPGM SRVPGM(SVRPGMNAME) DETAIL(*PROCEXP)

 DSPSRVPGM SRVPGM(SVRPGMNAME) DETAIL(*DTAEXP)

 

 

 

2. Binder Language

 

The binder language is a small set of nonrunnable commands that defines the

exports for a service program. The binder language can be specified with a BND source type in order that the input can be checked and validated by the SEU syntax checker. The binder language consists of only 3 commands:

(1). Start Program Export (STRPGMEXP) command, which identifies the beginning

of a list of exports from a service program

(2). Export Symbol (EXPORT) commands, each of which identifies a symbol name

available to be exported from a service program

(3). End Program Export (ENDPGMEXP) command, which identifies the end of a

list of exports from a service program

 

For example, the binder language for the several procedures looks like the following:

 

FILE: MYLIB/QSRVSRC MEMBER: FINANCIAL

 

STRPGMEXP PGMLVL(*CURRENT)

EXPORT SYMBOL('Term')

EXPORT SYMBOL('Rate')

EXPORT SYMBOL('Amount')

EXPORT SYMBOL('Payment')

ENDPGMEXP

 

Between a STRPGMEXP and ENDPGMEXP pair can be called an export block. A binder source file may have many export block for one service program.  We can also use the command RTVBNDSRC to retrieve the binder language to a binder source file to edit with a service program.

 

 

3. Signature

 

The symbols identified between a STRPGMEXP PGMLVL(*CURRENT) and

ENDPGMEXP pair define the public interface to a service program. That public

interface is represented by a signature. A signature is a value that identifies the

interface supported by a service program.

 

 The signature can be specified explicitly with the command like: STRPGMEXP PGMLVL(*CURRENT) SIGNATURE(‘signature string’).  If you choose not to specify an explicit signature, the binder generates a signature from the list of procedure and data item names to be exported and from the order in which they are specified. Therefore, a signature provides an easy and convenient way to validate the public interface to a service program. A signature does not validate the interface to a particular procedure within a service program.

 

 

 

4. Signature Violations

 

If the signature for a service program has changed, then it is incompatible with other ILE objects. If an incompatible change is made to a service program, exiting programs

that remain bound to it may no longer work correctly,and signature violation occurs when running the programs.  Then MCH4431 suggests to re-bind the programs. To avoid ‘Program signature violation”, we need keep the service program signature compatible when changing the service program.  To keep signature compatible, first, we cannot let the option EXPORT to ‘*ALL’ when creating service program, because that would generate incompatible signature when a new procedure or a new data item added, or the name of a procedure or a data item changed.

 

Service programs can be replaced without affecting the ILE programs or service

programs that use them, as long as previous signatures are still supported. In order to avoid generating incompatible signature, we need specify the exports and satisfy some conditions. We need create and edit a binder source file. There are two ways to edit the binder source file to keep the signature compatible:

 

(1) Specify a signature explicitly in the command STRPGMEXP. To avoid making incompatible changes to a service program, existing procedure and data item names must not be removed or rearranged in the binder language source. Additional symbols must be added only to the end of the list.

 

(2) As one service program may have many signatures, so we can keep the old signature to keep the signature compatible, as the existing ILE programs or service programs that use the service program to remain unchanged.  For new changes, we can generate a new signature. To achieve this, we can duplicate the export block and change the old export block PGMLVL(*CURRENT) to PGMLVL(*PRV). In the export block that contains PGMLVL(*CURRENT), add to the end of the list the new procedures or data items to be exported.  For example, the binder language looks like this:

 

FILE: MYLIB/QSRVSRC MEMBER: FINANCIAL

 

STRPGMEXP PGMLVL(*CURRENT)

EXPORT SYMBOL('Term')

EXPORT SYMBOL('Rate')

EXPORT SYMBOL('Amount')

EXPORT SYMBOL('Payment')

EXPORT SYMBOL('OpenAccount')   <- new added

EXPORT SYMBOL('CloseAccount')  <- new added

EXPORT SYMBOL(‘NewTerm’)   <- changed

ENDPGMEXP

 

STRPGMEXP PGMLVL(*PRV)

EXPORT SYMBOL('Term')

EXPORT SYMBOL('Rate')

EXPORT SYMBOL('Amount')

EXPORT SYMBOL('Payment')

ENDPGMEXP

Save the binder language source code changes, and select the option EXPORT to ‘*SRCFILE’ and specify the binder language source file&member name in the option SRCFILE&SRCMBR, like the following:

 

CRTSRVPGM SRVPGM(MYLIB/FINANCIAL)

MODULE(MYLIB/MONEY MYLIB/RATES MYLIB/CALCS)

EXPORT(*SRCFILE)

SRCFILE(MYLIB/QSRVSRC)

SRCMBR(*SRVPGM)

 

Then we can create compatible service programs, the message ‘Program signature violation’ would not occur.