Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!seismo!mcvax!cernvax!ethz!marti
From: marti@ethz.UUCP (Robert Marti)
Newsgroups: comp.databases
Subject: Quality of Oracle Doc
Message-ID: <195@bernina.UUCP>
Date: Tue, 8-Sep-87 03:44:45 EDT
Article-I.D.: bernina.195
Posted: Tue Sep  8 03:44:45 1987
Date-Received: Thu, 10-Sep-87 06:44:46 EDT
Organization: ETH Zuerich, Switzerland
Lines: 48

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!marti