RE: CEETSTA API

FYI.

We have designed our interfaces to allow a function to determine how to
access the information requested and how to return it, Much like many of
IBMs APIs.
The standard external interface for our APIs/functions look like this:

ReturnData                        *
ReturnDataSize           9B 0
ReturnDataFormat                10A
KeyData                   *
KeyDataSize                      9B 0
KeyDataFormat           10A
Usec                              *


For our getCustomer API we have several formats of return data, basic
customer info(Customer #, Name, Address, ...) customer fincial info(basic
customer info + amounts owed, credit available, ...), Customer location
info(basic + location address, ...)... and several others.

The key structures contain four formats which allows the return of customer
information by customer#, customer name, with the addition of customer
location to these two formats when requsting customer location information.

This allows us to place all requests for customer information in a single
API interface, getCustomer. It also allows us to expand the functionality of
the API to deal with requesting other types of customer information in the
future, and to place business rules in a single object.

We are building APIs to put data into the databases (putCustomer) so that we
can isolate the databases from the programs that use them. This will allow
us to rebuild the databases (they are very ugly). It also allows us to build
other interfaces (xml and stored procedures) so that processes external to
the iSeries can read/write to the databases through a standard interface.

There are two rules that we follow regarding interfaces:
1. The interface can expand, additional parameters can be passed if
absolutly required, but existing function can not be affected.
2. A format, once implemented, can not be changed. Additional format have to
be created instead.


Think long an hard about the interfaces you are creating for you APIs!!! 

Duane
 

-----Original Message-----
From: Hans Boldt [mailto:boldt@xxxxxxxxxx]
Sent: Tuesday, September 02, 2003 7:27 AM
To: rpg400-l@xxxxxxxxxxxx
Subject: Re: CEETSTA API


Scott Klement wrote:
> ...
> I won't.  I don't like overloading.  I think it's confusing when the
> compiler gives you an error "procedure not found" and the reason turns out
> to be that one of your variables is a "short" and the procedure was
> expecting an "int".   That's not intuitive.
> 
> I don't like it when I search a program for a procedure called "GetCust"
> fix a bug in it, and it has no effect because there's more than one
> procedure called GetCust.
> 
> I don't like having to specify a "mangled" name when creating binder
> source, or when using %paddr().
> 
> The problems of overloading far outweight the minor difficulties of making
> procedure names like "GetCustByName" instead of "GetCustByNumber"
> 

Procedure name overloading is one enhancement that's at or near the 
top of our "proposed enhancements" list. But at the moment we're 
nowhere near having a solid design for such a thing. All we have now 
are ideas tossed about in the hallway. This present discussion, 
therefore, is incredibly useful for us.

Personally, I too am not a big fan of overloading. But there does 
seem some demand for that type of functionality, and can serve to 
bridge the gap in operational descriptor functionality. Since types 
are known at compile time, there's no really good reason programmers 
should have to query types at run time (except to get the length of 
char parameters, but then again you could use VARYING strings).

Perhaps this is still too early to discuss design (or perhaps not), 
but here are some of our (very) preliminary thoughts. One possible 
design would have you code different procedures each with a unique 
name and parameter signature. (For example, "GetCustByName" and 
"GetCustByNumber".) Then, we'd have some syntax that would alias 
them to one name. That is, an overloaded name like "GetCust" would 
be associated with procedures "GetCustByName" and "GetCustByNumber". 
This would probably be the easiest for us to implement since the 
only new syntax would be a list of aliased procedures. You could 
easily interface to procedures written in other languages, and there 
wouldn't be any "magical" name mangling.

Regarding "short" and "int" possibly being two different types, I 
would guess that we would consider all numerics as being of the same 
type.

Cheers! Hans


_______________________________________________
This is the RPG programming on the AS400 / iSeries (RPG400-L) mailing list
To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at http://archive.midrange.com/rpg400-l.



NOTICE: This electronic mail transmission may contain confidential
information and is intended only for the person(s) named.  Any use, copying
or disclosure by any other person is strictly prohibited. If you have
received this transmission in error, please notify the sender via e-mail.