marti@ethz.UUCP (Robert Marti) (09/08/87)
I am currently studiyng call interfaces to DBMSs and have been
looking into the Oracle Pro*C Users' Guide, Version 1.1. Their
C call interface looks more or less OK, but -- to put it mildly
-- the quality of the documentation did not impress me at all.
If you'd type in their C example programs in Appendices D, E,
and F, I'd be surprised if you'd get them past any C compiler
without error messages, and even more surprised if they worked
as intended ...
First, the or operator || is consistently printed as !!.
Similarly, the not operator ! is printed as ].
And that's not all! Take this code fragment from page 244:
if (osql3(...)
!! odsc(...)
!! odfinn(C1, 1, dept = malloc(deptl+1), deptl+1, CHRST,
(short *)0, (char *)0, -1, -1, (short *)0, (short * 0) )
{
...
}
Apart from the misprinted or operator, this fragment of code has
no less than 4 errors or inaccuracies with respect to the documentation:
1. The relevant documentation of the function odfinn does not
specify the type of function odfinn - presumably it's
int odfinn() -- nor what the meaning of the returned integer
value is.
2. The parameter CHRST is not #defined or declared anywhere in their
example program. I assume it should read CHRSTR instead, since
this symbol is #defined earlier in the code.
3. The last parameter should read (short *)0 -- the closing parens
is missing.
4. The documentation for odfinn lists 7 parameters, but 11 parameters
are passed to odfinn in the above code fragment! Upon further
digging it turns out that odfinn is actually an old function supplied
for compatibility reasons. The name of its replacment is odefin
which has -- wait for it -- 12 parameters!!
All I can say is that this kind of documentation doesn't instill a
great deal of confidence about the quality of Oracle products into
me. Should it?
--
Robert Marti Phone: +41 1 256 52 36
Institut fur Informatik
ETH Zentrum/SOT CSNET/ARPA: marti%ifi.ethz.ch@relay.cs.net
CH-8092 Zurich, Switzerland UUCP: ...seismo!mcvax!ethz!martibradbury@oracle.UUCP (Robert Bradbury) (09/10/87)
In article <195@bernina.UUCP>, marti@ethz.UUCP (Robert Marti) writes: > I am currently studiyng call interfaces to DBMSs and have been > looking into the Oracle Pro*C Users' Guide, Version 1.1. Their > C call interface looks more or less OK, but -- to put it mildly > -- the quality of the documentation did not impress me at all. > > ... examples of the problems ... > > All I can say is that this kind of documentation doesn't instill a > great deal of confidence about the quality of Oracle products into > me. Should it? > One should not draw parallels between code quality and documentation quality in any organization. They are almost always done by different groups with different managers (in organizations with any size). I've forwarded your comments to the Product Line Manager responsible for the documentation and will personally rake him over the coals for not having a programmer review the final print of the documentation. As a general recomendation people planning to interface from a programming language to a RDBMS should use the embedded SQL syntax which is documented in the ANSI X3H2 SQL standard. (I'm not sure if there is an ISO reference number). Using embedded SQL results in a fairly portable application program which you could move from DBMS vendor to DBMS vendor as the RDBMS performance wheel turns. In practice this isn't possible right now because of minor differences in vendors embedded SQL but it is the direction in which we all are headed. Using a function call interface locks you into one vendors product. (Of course if you think IMS or MVS are good things to have around then you probably would prefer function call interfaces :-)) People who read advertisements or benchmarks with performance figures should make sure they determine what interface is used to the database. Several RDBMS vendors have low level interfaces which can result in higher performance than an embedded SQL interface. Such interfaces are likely to violate Codd's "Nonsubversion" rule and therefore disqualify the product as a "relational" DBMS. With Oracle we recomend that people use the embedded SQL interface as it will generally provide better performance than the function call interface. This is because the embedded SQL interface makes use of an undocumented interface which can insert/retrieve multiple rows at a time. The interface is undocumented to allow us flexibility in optimizing it and to eliminate the potential for support headaches with customers using a complicated interface. (It also eliminates the possiblity of people posting the documentation errors to the net :-)). -- Robert Bradbury Oracle Corporation (206) 364-1442 hplabs!oracle!bradbury
marti@ethz.UUCP (Robert Marti) (09/12/87)
In article <325@oracle.UUCP>, bradbury@oracle.UUCP (Robert Bradbury) writes: > One should not draw parallels between code quality and documentation > quality in any organization. They are almost always done by different > groups with different managers (in organizations with any size). Agreed. Still, technical people tend to look at the documentation first, so it should be at least passable. Then again, technical people are not always the ones who decide which product is bought ... > As a general recomendation people planning to interface from a > programming language to a RDBMS should use the embedded SQL > syntax which is documented in the ANSI X3H2 SQL standard. I don't think embedded SQL in particular or pre-compilation in general is a very good idea. But even if I did, who offers an embedded pre-compiler for Modula-2 -- or CLU, CommonLISP, Prolog, Smalltalk-80, for that matter? > Using a function call interface locks you into one vendors product. We plan to define our own call interface and build a thin veneer which maps the vendors interface to ours so this problem is minimized. Besides, portability is not that much of an issue in a research product. (If it were, we'd use C instead of Modula-2 ...) > ... Such [low-level] interfaces are > likely to violate Codd's "Nonsubversion" rule and therefore > disqualify the product as a "relational" DBMS. I have a high regard for Ted Codd and his achievements in the database field. All the same, I am more interested if a product meets my requirements than whether it is truly relational or not. In fact, we built a research "RDBMS" with referential integrity before Codd coined the term in eqrly 1979. (We called the concept "dynamic domain" at the time.) > Robert Bradbury > Oracle Corporation > (206) 364-1442 hplabs!oracle!bradbury -- Robert Marti Phone: +41 1 256 52 36 Institut fur Informatik ETH Zentrum/SOT CSNET/ARPA: marti%ifi.ethz.ch@relay.cs.net CH-8092 Zurich, Switzerland UUCP: ...seismo!mcvax!ethz!marti