RE: Passing Parms -- RPG400-L

When IBM changes an API, which use data structures/formats, do you haveto recompile all of your applications?

No, you don't. If you read my message again, you'll see that I statedthat fact. Never once have I said that it's impossible to maintainbackward compatibilty with DSes, I've only said that it's *easier* withindividual parms.

Externally defining the data structure makes it even more difficult tomaintain compatibility.

Using data structures correctly and appropratly is easier to maintain than a
huge list of data elements. The opperative word here is appropratly...
We build many of our procedures using the IBM API interface as a base.

As an example we have a getCustomerInfo procedure, currently it has 18
structures/formats it returns and 6 structures/formats it accepts as keys.


IBM doesn't use externally defined DSes, that solves part of the problem.

Rather than assume that everyone who reads this understands how IBMprovides backward compatibility in the APIs, let me explain how they work,and then I'll explain why individual parameters simplify it:

a) IBM always passes a "bytes provided" or "size of receiver variable"field. What this does is allow them to add fields to the end of the DSwithout breaking backward compatibility.

Before assigning any data to a field in the DS, they check to make surethat the field was passed by checking the length of the DS, and makingsure it extends at least as far as the end of the field that they'd liketo populate.

If the DS isn't long enough to include the field, they don't populate it.Therefore, newly added fields don't affect old callers, since thosecallers won't pass long enough DSes to get the extra fields.

b) IBM always includes a "format" field that keeps track of the version ofthe DS. If they want to make more sophisticated changes to the DS besidesjust adding a field to the end, they pass a different format name. Thatway, only callers who passed the new format name will use the new format.The old ones won't be affected at all.

These two features make it possible to maintain backward compatibilitywithout any concern about breaking compatibility in the future.

Why do I think that individual parameters provide the same capability, butmake it easier?

a) In IBM's scenario, the calling program has to fill in the "size ofreceiver variable" field (or "bytes provided" or whatever it's called).That requires an extra step for the caller, and they have to be careful tomake sure that they get it right.

With individual parameters, you can use %PARMS to check to see ifparameters were/weren't passed, thus eliminating the need for the callerto fill in this length field.

A caller can choose to omit a field that it's not interested by passing*OMIT instead of a parameter. This is not possible with a data structure.

b) The different format names make the code more complicated. When yourprogram receives the format name, it needs to handle every formatseparately. In the end, that'll turn into multiple routines, like this:


    select;
    when format = 'FMT00100';
      callp UseFormatFMT00100(parm1: parm2: parm3);
    when format = 'FMT00200';
      callp UseFormatFMT00200(parm1: parm2: parm3);
    when format = 'FMT00300';
      callp UseFormatFMT00300(parm1: parm2: parm3);
    endsl;

In situations like this, it makes more sense to me to export 3 procedures,since you have to write 3 different routines anyway. and then you cangive the procedures more friendly, easy to remember names, instead ofusing some obscure abbreviation followed by a number.

For example, instead of passing 18 formats to getCustInfo(), have 18different subprocedures named for what they do.


     getCustInfo() -- the original
     getCustInfoPostnet() -- the original, with extra info for postnet
                               barcodes (added later)
     getCustInfoSales() -- same info, but with information about the
                               sales rep in our company that works with
                               the customer

And so on... Existing callers don't have to change because they'recalling a different subprocedure. New callers have a choice of whichprocedure to call.

And the procedure names are easier to remember than CSTI0100, CSTI0200,etc.