Skip to Content.
Sympa Menu

freetds - [freetds] error handling

freetds AT lists.ibiblio.org

Subject: FreeTDS Development Group

List archive

Chronological Thread  
  • From: "Lowden, James K" <LowdenJK AT bernstein.com>
  • To: 'TDS Development Group' <freetds AT lists.ibiblio.org>
  • Subject: [freetds] error handling
  • Date: Thu, 18 Dec 2003 17:09:13 -0500

Today's little adventure in error handling leads me to try to summarize what
I know on the subject, so we can think more clearly about it. Perhaps you,
dear reader, are completely clear on the point, or don't care, in which case
you can skip to the next message....

The messages I'm talking about are generated by the library; they are not
transmitted from the server. db-lib calls these, unfortunately, "error"
messages. ct-lib more clearly calls them "client-messages". I'm not sure
ODBC distinguishes.

Here's the stack:

1. Application
2. Client library (db/ct lib)
3. libtds <== maybe, depending on origin of the error
4. Application's error handler

ct-lib and db-lib share a capability to centralize the handling of these
messages by installing a callback function.

db-lib: EHANDLEFUNC dberrhandle(EHANDLEFUNC handler);
ct-lib: CS_RETCODE ct_callback(CS_CONTEXT * ctx, CS_CONNECTION * con,
CS_INT action, CS_INT type, CS_VOID * func);

They also have a shared sense of what the handler may return, although they
also also have nonshared senses. The handler's return code is an
instruction to the library as to how the calling function -- the function
that caused the handler to be invoked -- should behave. Remember MS-DOS?
Welcome home to a)bort, r)etry, i)gnore, f)ail.

1. Abort. Print a message and exit. db-lib calls this INT_EXIT. ct-lib
has no equivalent.
2. Retry. For timeout errors, give it one more go and, if it still times
out, call the error handler again. db-lib calls this INT_CONTINUE; ct-lib
calls it CS_SUCCEED.
3. Ignore. Proceed normally. ct-lib calls this CS_SUCCEED, except for
timeouts (cf. #2). db-lib has no equivalent.
4. Fail. Cause the calling function to return a failure status. db-lib
calls this INT_CANCEL; ct-lib has no precise equivalent. Instead, ct-lib
uses CS_FAIL to abandon processing on the connection and mark it dead. The
application can re-open it, if it so chooses.

Note how once again the ct-lib designers improved on db-lib.

For db-lib, timeouts create a special context. INT_CONTINUE means retry.
(For other types of errors, it's treated as INT_CANCEL.) Microsoft says
INT_CANCEL means call dbcancel() and proceed. Only if dbcancel fails is the
connection broken. Sybase says it will "kill the dbproc". That's the
theory, anyway.

For ct-lib, timeouts are not particularly special: CS_SUCCEED means retry,
CS_FAIL means don't (and shut down the link).

It's important to realize that db-lib error handlers, per the documentation,
can't return an OK status. That's why the bcp library mustn't invoke the
error handler with informational messages.

Equally important, the tds layer cannot interpret the return code from the
handler. Each API has a different idea about what to do. The best that can
be done is to pass the return code back up to the calling library for
evaluation.

+++

One last point, while I'm making notes. ct-lib has a rigorous error message
structure that, afaict, is a superset of db-lib's. When one day we get
around to restructuring this, we should implement a ct-lib-like system in
libtds, and let the calling library interpret the codes according to its
conventions.

--jkl

-----------------------------------------
The information contained in this transmission may contain privileged and
confidential information and is intended only for the use of the person(s)
named above. If you are not the intended recipient, or an employee or agent
responsible for delivering this message to the intended recipient, any
review, dissemination, distribution or duplication of this communication is
strictly prohibited. If you are not the intended recipient, please contact
the sender immediately by reply e-mail and destroy all copies of the original
message. Please note that we do not accept account orders and/or instructions
by e-mail, and therefore will not be responsible for carrying out such orders
and/or instructions.





  • [freetds] error handling, Lowden, James K, 12/18/2003

Archive powered by MHonArc 2.6.24.

Top of Page