RTFM - between the lines

Writing documentation sucks.

Sometimes it's next to impossible to convey all the information you need to help people understand your product. If something is large and complicated, the new user is likely going to miss things and there's nothing you can do to change that. We all learn differently, so regardless of how hard you try, some concept is going to slip through the cracks and be misunderstood by somebody.

I mention all this because I learned something fairly important about the MySQL C API today: the return value from most functions is fairly meaningless and should be treated as a boolean. Most functions return an int which a robust application should examine. What the robust application shouldn't do is assume that the return values means anything other than "zero good, non-zero bad", and that one needs to call mysql_errno() to retrieve the real error code.

At first I was a little pissed off that the manual wasn't more explicit about this; there are two sentences at the bottom of one page of the documentation that mention you should use mysql_errno() or mysql_error() to find out what went wrong. I felt that there should have been some large, obvious declaration somewhere stating "The Return Values Don't Mean Shit, Newbie. We've Provided You With The Means To Get The Information, So Use It".

Upon further reflection, it occurs to me that I'm full of shit. The manual does state in black and white that one should call mysql_errno() to find out what went wrong. The fact that I hadn't read that portion of the manual is nobody's fault but my own. Secondly (and probably more importantly), I'm a Win32 programmer; return values in that realm generally don't mean anything either, and you're obligated to call the ubiquitous GetLastError() to find out what happened.

I told you that story to tell you this one.

In my last two test runs with LokiJr, I discovered that he became unresponsive after a couple of days. The first time I wasn't sure why, because I wasn't capturing any debug information. The second time I did, and the problem revealed itself as a lost connection to the database. Not surprised that he lost his database connection; sooner or later the server is going to close an unused socket. However, I thought I'd provided for that case. I check for the corresponding error codes and reconnect if necessary, but Jr wasn't attempting to reconnect - he just failed to execute the query and reported that the server had gone away. Odd... why wouldn't he reconnect when he can plainly see that the server has gone away?

Finally occurs to me that I was checking the return value of mysql_real_query() instead of mysql_errno(), and that I was using mysql_error() to get an error string from the server, which is why he "knew" what the problem was, but didn't react properly. Inserting a call to mysql_errno() and checking that value gives us the correct behaviour, even if one restarts the MySQL server.

So remember kids, don't shoot the messenger; sometimes the designers of the software have told you what you need to know, they just didn't print it on a billboard.