RE: Passing Parms

[Scott Klement <rpg400-l@xxxxxxxxxxxxxxxx>]

> When IBM changes an API, which use data structures/formats, do you have 
> to recompile all of your applications?
No, you don't. If you read my message again, you'll see that I stated 
that fact.  Never once have I said that it's impossible to maintain 
backward compatibilty with DSes, I've only said that it's *easier* with 
individual parms.
Externally defining the data structure makes it even more difficult to 
maintain 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 IBM 
provides 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 DS 
without breaking backward compatibility.
Before assigning any data to a field in the DS, they check to make sure 
that the field was passed by checking the length of the DS, and making 
sure it extends at least as far as the end of the field that they'd like 
to 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 those 
callers won't pass long enough DSes to get the extra fields.
b) IBM always includes a "format" field that keeps track of the version of 
the DS.  If they want to make more sophisticated changes to the DS besides 
just adding a field to the end, they pass a different format name.  That 
way, 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 compatibility 
without any concern about breaking compatibility in the future.
Why do I think that individual parameters provide the same capability, but 
make it easier?
a) In IBM's scenario, the calling program has to fill in the "size of 
receiver variable" field (or "bytes provided" or whatever it's called). 
That requires an extra step for the caller, and they have to be careful to 
make sure that they get it right.
With individual parameters, you can use %PARMS to check to see if 
parameters were/weren't passed, thus eliminating the need for the caller 
to 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 your 
program receives the format name, it needs to handle every format 
separately.  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 can 
give the procedures more friendly, easy to remember names, instead of 
using some obscure abbreviation followed by a number.
For example, instead of passing 18 formats to getCustInfo(), have 18 
different 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're 
calling a different subprocedure.  New callers have a choice of which 
procedure to call.
And the procedure names are easier to remember than CSTI0100, CSTI0200, 
etc.