Re: [sqlite] think I need better error-handling guidance in the C API

[James K. Lowden]

On Sat, 5 Jul 2014 17:48:41 +0100
Klaas V  wrote:

> James K. Lowden wrote:
> 
> >If the answer to every question, concern, and suggestion is that it
> >already works for millions of programs, there is no point in
> >discussion or further development.  Just use what's there because
> >it's already perfect. 
> 
> Permission to differ, James!

Granted, Klass!  ;-) 

> Since there is no such thing as a perfect application, because no
> living perfect developer exists except probably (the) God(s). SQLite
> however comes pretty close, that's why it has millions of users, fans
> if you like to call them like that. 

I don't understand.  You latched onto "perfect".  Do you maintain your
point if I withdraw it and say only, "Just use what's there because
it's good enough for them"?  

Let me explain why "millions" is not, ipso facto, an argument.  

The set of people who will voice reasonable but rare
documentation complaints on this list might be expressed as

N = U ? K ? D ? S ? V

where
U is the set of SQLite programmers
K is the set knowledgable enough to see a flaw 
  (not just a missing feature or pet peeve)
D is the set who care about documentation
S is the set who subscribe to this list
V is the set who will voice their concern

N might be very small, even if U is measured in millions, if D, S, and
V are small subsets.  We know S, D, and V to be small relative to U. 
We hardly need make assertions about K.  

Relieve any of those constraints, say, K, and you have a larger set.
The number of people who do not see a real flaw grows with the knowledge
necessary to understand it.  The fact that no one has mentioned a
concern previously could be an indication it is not valid.  It
could also just be an indication it's not apparent to D ? S ? V.  

So, you see, perfection is not relevant and millions is not many!  

--jkl
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Eric Rubin-Smith]

Klaas V wrote: 

> BTW (someone else wrote this): to call a program 'crappy' sounds a wee 
> bit megalomanic...  

:-) Are you denying that crappy programs exist in the world, or are you 
saying that they do exist but that stating something true about them 
is megalomaniacal?  Keeping in mind that I include most of the code 
I write among that which is crappy.  And that the very reason for my 
post was to avoid the very real danger that I am about to undertake the 
creation of more such crappy code (the result of which will no doubt be 
that this unfortunate forum will be subjected to more of my ridiculous 
questions).  

Also, I was trying to be funny.  Which I thought I was making pretty 
clear.  Apparently I need to add some of my jokes, and my writing 
ability in general, to the list of crappy things in the world.  

Even if I *were* a megalomaniac, and even if all those zillion programs 
*were* of perfect quality, that would *still* not be a refutation of my 
very narrow point, which is that the docs are lacking in the specific 
ways that I enumerated.  

If they are not lacking in those ways because I misread the docs or 
missed one of the pages outright, then I'm asking with apologies to be 
corrected and directed to what I missed or misread.  

But people familiar with the library mostly seem to agree with my 
material point.  

So!  Just looking for a ticket, so the relevant material can be added at 
the pleasure and convenience of the docs maintainers.  

-- 
Eric A. Rubin-Smith

___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Klaas V]

James K. Lowden wrote:

>If the answer to every question, concern, and suggestion is that it
>already works for millions of programs, there is no point in discussion
>or further development.  Just use what's there because it's already
>perfect. 

Permission to differ, James!

Since there is no such thing as a perfect application, because no living 
perfect developer exists except probably (the) God(s).
SQLite however comes pretty
 close, that's why it has millions of users, fans if you like to call them like 
that. 

BTW (someone else wrote this): to call a program 'crappy' sounds a wee bit 
megalomanic...

No body is perfect, but some are more perfect than other.

 

Kind regards | Cordiali saluti | Vriendelijke groeten | Freundliche Grüsse,
Klaas `Z4us` V  - OrcID -0001-7190-2544
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[James K. Lowden]

On Thu, 03 Jul 2014 19:00:21 +0200
RSmith  wrote:

> > A vague citation to a million anonymous programs of unknown quality
> > is not a convincing reason to think otherwise.  And you and I both
> > know that a random sample of 1 million programs will contain
> > roughly 999000 crappy ones.  :-)
> >
> 
> The citation is not vague, he did not mean *any* selection of a
> million programs, but indeed all of the millions of programs
> commercially available running sqlite on many billions of devices
> (refer: www.sqlite.org home page) - I would contend that it will be
> hard to find even 1% really bad programs among a million of these
> that do sqlite an injustice for merely existing - but that is just a
> contention since I have no resources to prove it and your estimate of
> "crappy" is unquantifiable. 

If the answer to every question, concern, and suggestion is that it
already works for millions of programs, there is no point in discussion
or further development.  Just use what's there because it's already
perfect.  

Mr. Rubin-Smith is asking a semantic question: what does each error
code *mean*?  Does the error indicate malformed input,
resource contention, constraint violation, program logic error, or
system failure?  Is it within the user's capacity to correct?  Will the
same operation, retried later with the same input, possibly succeed?  

If his question is unusual, then it's fair to say so too are such
programmers unusual.  I would guess the number of programmers who
understand what is meant by "the semantics of the function" tracks
closely with the number who've studied section 2 of the Unix manual.
Depending on what "studied" means, that might well be 1% of the
programming population; I'd venture, two guesses deep, that 20% is
generous.  Otherwise Haskell would be popular and multithreading never
would have been invented.  

Look back again at his requirements.  He's not keeping games scores for
an address book on an iPhone.  He won't have (I suppose) millions of
users and billions of devices.  What he will have, SQLite permitting,
is a single, vital, rock-solid application.  If I were in his position,
I'd be asking the same questions.  I could only hope to use the same
degree of tact.  

By the way, they're good questions.  If answered in the documentation,
the lives of those millions of programmers will be improved, whether or
not they notice.  

A productive answer to his query would be, gee, a table or three.  

functions
-
function
error

errors
--
error
type

error_types
--
type
description

That might work.  AFAIK an error means the same thing no matter which
function it is returned by or what global configuration is in force.  If
that proves not to be the case, the functions table would need to be
more elaborate.  

By way of example, cf.
http://technet.microsoft.com/en-us/library/aa937495(v=sql.80).aspx.
DB-Library associates a severity with each error.  The notation
"DBPROCESS is dead" indicates the connection handle cannot be used
anymore.  The programmer knows, per the severity, how to proceed with
each error.  

--jkl
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Eric Rubin-Smith]

RSmith wrote:

> I do hope your request is escalated to a ticket.

Yet a third person who completely agrees with me in every way! :-)

How 'bout it, SQLite devs?

> You seem well-versed in these matters, I believe there is a need for a
> documentation specialist in the sqlite dev team, apply online.  :)

Hehe well I'd be more than happy to do that, if I understood the API...

--
Eric A. Rubin-Smith

___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[RSmith]

On 2014/07/03 18:19, Eric Rubin-Smith wrote:

The fact that (literally) millions of applications get written despite
any perceived shortcomings in the documentation suggests that the docs are
at least "adequate," if not "perfect."

Your argument is analogous to an argument that the Earth is the center
of the universe because lots of people think so.  Nevermind what we
actually observe with our own eyes.


No, his argument is not analogous to that at all. It's always fun when a simple question devolves into debate-style philosophy, and 
good to see someone well-versed in it, if a little overzealous to impose it on an honest reply that did not mean to incite a debate. 
Since we are in debate realms now, allow me to point out that his argument is flawed, but not in the way that you propose, his 
argument is not an appeal to the masses or an appeal to authority, it does not even propose the veracity of a statement but simply 
demonstrates the absence of conflict. Your remark in answer is however a straw-man since it imposes a different paradigm as the 
object of the contention to what the original post refers or implies.


In layman's terms: He did not say "the documents are perfect because it works for everyone else", he did say that "nobody else 
registered the shortcoming, it may however still be a shortcoming (in fact he professed that it is so in his opinion too) but since 
the lack of it seems to not discomfort anyone, it is probably unfair to proclaim it "inadequate".


The difference is slight but important. Where his argument is flawed is in that he addresses the subjective and not the object of 
discussion. i.e he did not show adequacy, simply inferred perception of it - but then, he was not trying to make an argument.




A vague citation to a million anonymous programs of unknown quality is
not a convincing reason to think otherwise.  And you and I both know
that a random sample of 1 million programs will contain roughly 999000
crappy ones.  :-)



The citation is not vague, he did not mean *any* selection of a million programs, but indeed all of the millions of programs 
commercially available running sqlite on many billions of devices (refer: www.sqlite.org home page) - I would contend that it will 
be hard to find even 1% really bad programs among a million of these that do sqlite an injustice for merely existing - but that is 
just a contention since I have no resources to prove it and your estimate of "crappy" is unquantifiable. However, not his statement, 
nor mine in answer to your contention, or any of the above matters in terms of the truth of the premise - I too believe there is a 
benefit to be had for full disclosure of errata and I do hope your request is escalated to a ticket.


You seem well-versed in these matters, I believe there is a need for a documentation specialist in the sqlite dev team, apply 
online.  :)



___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Eric Rubin-Smith]

Stephan Beal wrote: 

> While i do fundamentally agree with your points, in practice it's not 
> as difficult as you seem to be making it out to be.  The rule is really 
> simple: any non-0 code is an error unless the APIs specify otherwise, 
> and the step() API does indeed document 2 non-error, non-0 error codes 
> (SQLITE_STEP and SQLITE_DONE).  Anywhere else in the API, non-0 means Bad 
> News.  There are relatively few cases (locking comes to mind) where an 
> error returned due to something other than a misuse of the API should be 
> considered recoverable (IMO).  

I don't think that answer is satisfactory.  Some errors are recoverable by 
restarting the transaction.  Others may be recoverable by creating a new 
connection.  Others may be recoverable by blowing away the database file 
and starting over (because the database file is corrupt).

SQLite makes an attempt to detect a great variety of such cases and 
return errors when they do happen.  I would like to know in which cases 
they will return such errors, and to which API calls, so that I can know 
how to handle those cases.  

I am not asking more of SQLite than I would ask of a Linux syscall man 
page.  In fact, I'm asking less -- I just want a ticket opened.  Beggars
can't be choosers :-) and I don't have any claim on the devs' time.

E.g. from open(2): 

ERRORS
   EACCES The requested access to the file is not allowed, or search  per-
  mission  is denied for one of the directories in the path prefix
  of pathname, or the file did not exist yet and write  access  to
  the  parent  directory  is  not allowed.  (See also path_resolu-
  tion(7).)

   EEXIST pathname already exists and O_CREAT and O_EXCL were used.

   EFAULT pathname points outside your accessible address space.

   EFBIG  See EOVERFLOW.

   EINTR  While blocked waiting to complete  an  open  of  a  slow  device
  (e.g.,  a FIFO; see fifo(7)), the call was interrupted by a sig-
  nal handler; see signal(7).
   {etc}

Analogous listings in the SQLite function API pages would cure the issue 
completely.  

> The fact that (literally) millions of applications get written despite 
> any perceived shortcomings in the documentation suggests that the docs are 
> at least "adequate," if not "perfect."  

Your argument is analogous to an argument that the Earth is the center 
of the universe because lots of people think so.  Nevermind what we 
actually observe with our own eyes.  

The docs are *not* adequate afaict for the purpose of determining in which 
situations certain error codes will be raised, or what the SQLite authors 
believe is appropriate subsequent client behavior.

A vague citation to a million anonymous programs of unknown quality is 
not a convincing reason to think otherwise.  And you and I both know 
that a random sample of 1 million programs will contain roughly 999000 
crappy ones.  :-) 

-- 
Eric A. Rubin-Smith

___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Stephan Beal]

On Thu, Jul 3, 2014 at 4:44 PM, Stephan Beal  wrote:

> non-error, non-0 error codes (SQLITE_STEP and SQLITE_DONE). Anywhere else
> in the API, non-0 means Bad News. There
>

correction: SQLITE_ROW and SQLITE_DONE

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
"Freedom is sloppy. But since tyranny's the only guaranteed byproduct of
those who insist on a perfect world, freedom will have to do." -- Bigby Wolf
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Stephan Beal]

On Thu, Jul 3, 2014 at 4:27 PM, Eric Rubin-Smith  wrote:

> I respectfully re-raise my issue.  The "TLDR" is that the C API docs are
> critically lacking in specificity in a relatively wide range of areas, as
> exemplified below, making it difficult to write correct clients against the
> library.

Do the SQLite authors disagree with my below points about the API docs for
> sqlite3_step(), sqlite3_exec(), and sqlite3_prepare_v2()?  I think the
> criticisms can be extended to other API calls.  If the authors do not
> disagree then can we create a ticket against the docs?
>

(disclaimer: i'm not one of the authors)

While i do fundamentally agree with your points, in practice it's not as
difficult as you seem to be making it out to be. The rule is really simple:
any non-0 code is an error unless the APIs specify otherwise, and the
step() API does indeed document 2 non-error, non-0 error codes (SQLITE_STEP
and SQLITE_DONE). Anywhere else in the API, non-0 means Bad News. There are
relatively few cases (locking comes to mind) where an error returned due to
something other than a misuse of the API should be considered recoverable
(IMO).

The fact that (literally) millions of applications get written despite any
perceived shortcomings in the documentation suggests that the docs are at
least "adequate," if not "perfect."

-- 
- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal
"Freedom is sloppy. But since tyranny's the only guaranteed byproduct of
those who insist on a perfect world, freedom will have to do." -- Bigby Wolf
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Eric Rubin-Smith]

I respectfully re-raise my issue.  The "TLDR" is that the C API docs are
critically lacking in specificity in a relatively wide range of areas, as
exemplified below, making it difficult to write correct clients against the
library.

Do the SQLite authors disagree with my below points about the API docs for
sqlite3_step(), sqlite3_exec(), and sqlite3_prepare_v2()?  I think the
criticisms can be extended to other API calls.  If the authors do not
disagree then can we create a ticket against the docs?


On Mon, Jun 30, 2014 at 2:47 PM, Eric Rubin-Smith  wrote:

> I've been using the sqlite Tcl API for about 3 million years, with much
> delight.  I'm venturing now into the C API -- hoping to put sqlite into a
> large monolithic "always on" C++ daemon.  I would like to use the API in a
> way perfectly in line with how the authors intended.
>
> But it's sort of hard to figure out exactly what the authors intended in
> some cases.
>
> Consider the man page for sqlite3_step() (
> http://sqlite.org/c3ref/step.html):
>
> "With the "v2" interface, any of the other result codes
>  or extended result codes
>  might be returned as
> well SQLITE_ERROR  means that a
> run-time error (such as a constraint violation) has occurred.
> sqlite3_step() should not be called again on the VM. More information may
> be found by calling sqlite3_errmsg()
> . With the legacy interface, a more
> specific error code (for example, SQLITE_INTERRUPT
> , SQLITE_SCHEMA
> , SQLITE_CORRUPT
> , and so forth) can be obtained by
> calling sqlite3_reset()  on the prepared
> statement . In the "v2" interface, the
> more specific error code is returned directly by sqlite3_step()."
>
> I am a big fan generally of the clarity of the sqlite docs.  But this page
> could use another section detailing all the possible result codes' specific
> semantics under sqlite3_step(), and in particular what the client should do
> in those circumstances.  Similar to how your normal linux system call man
> page details such things.
>
> The page bites a bit of that off, as you see above.  But consider e.g.
> (from http://sqlite.org/c3ref/c_abort.html):
>
> #define SQLITE_NOTICE  27   /* Notifications from sqlite3_log() */
>
> Am I supposed to look for that?  What am I supposed to do with it if I get
> it?  How about SQLITE_CANTOPEN?  Seems like that shouldn't be a possibility
> by the time we hit sqlite3_step(), but the docs are silent on the matter.
> So what am I to do?
>
> If I get SQLITE_IOERR, is that always permanent, or do I need to look for
> things like SQLITE_IOERR_LOCK and if that bit is set then rollback and
> retry?
>
>
> sqlite3_exec() has the same issue: it's hard to say from reading the docs
> exactly which of the error codes might be returned, and what the caller
> should do in those cases.
>
> sqlite3_prepare_v2() again has the same issue:
>
> "On success, the sqlite3_prepare() family of routines return SQLITE_OK
> ; otherwise an error code
>  is returned."
>
> Again, can *any* of those error codes be returned?  Which of them is
> permanent and which are temporary in the case of prepare_v2()?
>
> And so on.
>
> Apologies if I have missed some of the docs.  Any pointers, or especially
> example C code that the SQLite devs consider perfectly robust and complete
> API usage, are much appreciated.
>
> Eric
>
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Simon Slavin]

On 1 Jul 2014, at 2:22am, Keith Medcalf  wrote:

> IF ResultCode == A_OK YipeeKiAiii else OhShitItDidntWork;
> 
> Seems pretty straightforward to me.  You handle the result codes you know 
> what to do with, and everything that remains means your program should 
> explode immediately and very very loudly dumping ALL relevant information 
> (ie, error code, statement, inout data, output data, etc.)
> 
> In other words, there is no point checking for error conditions which you 
> cannot handle. Instead you just die.

Okay, right.  Now, where in the documentation does it tell us "what to do with" 
each error ?  Or alternatively, how should my app die ?

Suppose _step() gets a result of SQLITE_PROTOCOL.  Can I just execute _step() 
again and assume I didn't miss a row ?  Or will the next _step() always just 
return SQLITE_DONE ?  Should I actually _reset() and start again ?  Or is my 
statement so messed up I can only _finalize() it ?  Is it necessary to 
_finalize() it ?  Or is my whole database connection now invalid and I should 
quit without having to even _close() ?

It's this sort of documentation which is not present.  And it's that sort of 
thing that I think Eric is asking about.

Simon.
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Eric Rubin-Smith]

Keith Medcalf wrote: 

> IF ResultCode == A_OK YipeeKiAiii else OhShitItDidntWork; 
> 
> Seems pretty straightforward to me.  You handle the result codes you 
> know what to do with, 

There is a difference between things I don't personally know how to 
handle and things that the SQLite authors would consider "permanent" 
errors (where "permanent" is appropriately scoped e.g.  to the level of 
the function call, the sqlite3_stmt*, the sqlite3*, or so on).  

My ignorance of the API details is not a justification for writing a 
crappy client.  I would like to cure my ignorance, and the docs are 
insufficient in that regard AFAICT.  Hence my question to this forum.  

> and everything that remains means your program should explode 
> immediately and very very loudly dumping ALL relevant information (ie, 
> error code, statement, inout data, output data, etc.)  

SQLite is not the center of my universe.  The layer using it is not at 
the center of the program in which it resides.  The program I am writing 
is a high-availability, mission-critical system.  Barfing because of an 
SQLite error is unacceptable in my case, especially if the only reason 
the program is barfing is because the programmer who wrote it was a 
dummy (or at least more of a dummy than he should have been:-).  

And whether it barfs is sort of beside the point.  If I restart my 
program and give SQLite the same series of commands, should I expect 
it to fail in the exact same way, or should I expect its behavior 
to change?  Depends of course on the state of the system and on the 
particular series of calls.  If the documentation were sufficient, then 
it would allow me to reach the appropriate conclusion.  

I would first like to know exactly what the *authors* expect to be 
returned in various cases, so that I can code to that expectation.  

> In other words, there is no point checking for error conditions 
> which you cannot handle.  Instead you just die.  Quickly, noisily, 
> and immediately.  There is no point checking for the error message 
> SQLITE3_CPU_REGISTER_HIT_BY_COSMIC_RAY if there is nothing that you can 
> do about it.  Every error that you cannot handle is a fatal error, and you 
> should die accordingly.  

I can handle every kind of error.  It's just a question of how.  I 
don't know how in many cases, because I don't understand the semantics 
of the error codes, in turn because (I think) the documentation is 
insufficient.  It is not healthy to bake such ignorance into the 
application if I can help it -- again, I would rather just cure my 
ignorance (preferably not by digging through the code and reaching
my own flawed conclusions about it).  

-- 
Eric A. Rubin-Smith

___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Keith Medcalf]

IF ResultCode == A_OK YipeeKiAiii else OhShitItDidntWork;

Seems pretty straightforward to me.  You handle the result codes you know what 
to do with, and everything that remains means your program should explode 
immediately and very very loudly dumping ALL relevant information (ie, error 
code, statement, inout data, output data, etc.)

In other words, there is no point checking for error conditions which you 
cannot handle.  Instead you just die.  Quickly, noisily, and immediately.  
There is no point checking for the error message 
SQLITE3_CPU_REGISTER_HIT_BY_COSMIC_RAY if there is nothing that you can do 
about it.  Every error that you cannot handle is a fatal error, and you should 
die accordingly.

>-Original Message-
>From: sqlite-users-boun...@sqlite.org [mailto:sqlite-users-
>boun...@sqlite.org] On Behalf Of Eric Rubin-Smith
>Sent: Monday, 30 June, 2014 12:47
>To: General Discussion of SQLite Database
>Subject: [sqlite] think I need better error-handling guidance in the C
>API
>
>I've been using the sqlite Tcl API for about 3 million years, with much
>delight.  I'm venturing now into the C API -- hoping to put sqlite into a
>large monolithic "always on" C++ daemon.  I would like to use the API in
>a
>way perfectly in line with how the authors intended.
>
>But it's sort of hard to figure out exactly what the authors intended in
>some cases.
>
>Consider the man page for sqlite3_step()
>(http://sqlite.org/c3ref/step.html
>):
>
>"With the "v2" interface, any of the other result codes
><http://sqlite.org/c3ref/c_abort.html> or extended result codes
><http://sqlite.org/c3ref/c_abort_rollback.html> might be returned as
>well SQLITE_ERROR <http://sqlite.org/c3ref/c_abort.html> means that a
>run-time error (such as a constraint violation) has occurred.
>sqlite3_step() should not be called again on the VM. More information may
>be found by calling sqlite3_errmsg()
><http://sqlite.org/c3ref/errcode.html>.
>With the legacy interface, a more specific error code (for example,
>SQLITE_INTERRUPT <http://sqlite.org/c3ref/c_abort.html>, SQLITE_SCHEMA
><http://sqlite.org/c3ref/c_abort.html>, SQLITE_CORRUPT
><http://sqlite.org/c3ref/c_abort.html>, and so forth) can be obtained by
>calling sqlite3_reset() <http://sqlite.org/c3ref/reset.html> on the
>prepared
>statement <http://sqlite.org/c3ref/stmt.html>. In the "v2" interface, the
>more specific error code is returned directly by sqlite3_step()."
>
>I am a big fan generally of the clarity of the sqlite docs.  But this
>page
>could use another section detailing all the possible result codes'
>specific
>semantics under sqlite3_step(), and in particular what the client should
>do
>in those circumstances.  Similar to how your normal linux system call man
>page details such things.
>
>The page bites a bit of that off, as you see above.  But consider e.g.
>(from http://sqlite.org/c3ref/c_abort.html):
>
>#define SQLITE_NOTICE  27   /* Notifications from sqlite3_log() */
>
>Am I supposed to look for that?  What am I supposed to do with it if I
>get
>it?  How about SQLITE_CANTOPEN?  Seems like that shouldn't be a
>possibility
>by the time we hit sqlite3_step(), but the docs are silent on the matter.
>So what am I to do?
>
>If I get SQLITE_IOERR, is that always permanent, or do I need to look for
>things like SQLITE_IOERR_LOCK and if that bit is set then rollback and
>retry?
>
>
>sqlite3_exec() has the same issue: it's hard to say from reading the docs
>exactly which of the error codes might be returned, and what the caller
>should do in those cases.
>
>sqlite3_prepare_v2() again has the same issue:
>
>"On success, the sqlite3_prepare() family of routines return SQLITE_OK
><http://sqlite.org/c3ref/c_abort.html>; otherwise an error code
><http://sqlite.org/c3ref/c_abort.html> is returned."
>
>Again, can *any* of those error codes be returned?  Which of them is
>permanent and which are temporary in the case of prepare_v2()?
>
>And so on.
>
>Apologies if I have missed some of the docs.  Any pointers, or especially
>example C code that the SQLite devs consider perfectly robust and
>complete
>API usage, are much appreciated.
>
>Eric
>___
>sqlite-users mailing list
>sqlite-users@sqlite.org
>http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users



___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

Re: [sqlite] think I need better error-handling guidance in the C API

[Simon Slavin]

On 30 Jun 2014, at 7:47pm, Eric Rubin-Smith  wrote:

> I am a big fan generally of the clarity of the sqlite docs.  But this page
> could use another section detailing all the possible result codes' specific
> semantics under sqlite3_step(), and in particular what the client should do
> in those circumstances.

I agree with this, and want to extend it to other calls.  Many of the API calls 
could usefully do with an explanation of non _OK results, what they mean, and 
how a typical app might react to them (including other sqlite3_ calls that 
might be used).

I have tried three times to explain the combinations of things that might lead 
to ROLLBACK, which calls to use, and how to react to failure of the ROLLBACK 
command.  I failed, because I lack detailed understanding of what might cause 
ROLLBACK to fail and what it's still safe to try.

There's also an unfortunate consequence of SQLite trying to be helpful.  In 
strict SQL the programmer has to issue BEGIN before any operation and ROLLBACK 
or END after it.  So if you issue ROLLBACK the SQL engine can safely ignore 
anything until it sees another BEGIN.  But SQLite automatically wraps 
individual operations in transactions.  So it can see another command before 
the END and it has to do it.  Which can be nasty.

Simon.
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

[sqlite] think I need better error-handling guidance in the C API

[Eric Rubin-Smith]

I've been using the sqlite Tcl API for about 3 million years, with much
delight.  I'm venturing now into the C API -- hoping to put sqlite into a
large monolithic "always on" C++ daemon.  I would like to use the API in a
way perfectly in line with how the authors intended.

But it's sort of hard to figure out exactly what the authors intended in
some cases.

Consider the man page for sqlite3_step() (http://sqlite.org/c3ref/step.html
):

"With the "v2" interface, any of the other result codes
 or extended result codes
 might be returned as
well SQLITE_ERROR  means that a
run-time error (such as a constraint violation) has occurred.
sqlite3_step() should not be called again on the VM. More information may
be found by calling sqlite3_errmsg() .
With the legacy interface, a more specific error code (for example,
SQLITE_INTERRUPT , SQLITE_SCHEMA
, SQLITE_CORRUPT
, and so forth) can be obtained by
calling sqlite3_reset()  on the prepared
statement . In the "v2" interface, the
more specific error code is returned directly by sqlite3_step()."

I am a big fan generally of the clarity of the sqlite docs.  But this page
could use another section detailing all the possible result codes' specific
semantics under sqlite3_step(), and in particular what the client should do
in those circumstances.  Similar to how your normal linux system call man
page details such things.

The page bites a bit of that off, as you see above.  But consider e.g.
(from http://sqlite.org/c3ref/c_abort.html):

#define SQLITE_NOTICE  27   /* Notifications from sqlite3_log() */

Am I supposed to look for that?  What am I supposed to do with it if I get
it?  How about SQLITE_CANTOPEN?  Seems like that shouldn't be a possibility
by the time we hit sqlite3_step(), but the docs are silent on the matter.
So what am I to do?

If I get SQLITE_IOERR, is that always permanent, or do I need to look for
things like SQLITE_IOERR_LOCK and if that bit is set then rollback and
retry?


sqlite3_exec() has the same issue: it's hard to say from reading the docs
exactly which of the error codes might be returned, and what the caller
should do in those cases.

sqlite3_prepare_v2() again has the same issue:

"On success, the sqlite3_prepare() family of routines return SQLITE_OK
; otherwise an error code
 is returned."

Again, can *any* of those error codes be returned?  Which of them is
permanent and which are temporary in the case of prepare_v2()?

And so on.

Apologies if I have missed some of the docs.  Any pointers, or especially
example C code that the SQLite devs consider perfectly robust and complete
API usage, are much appreciated.

Eric
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users