Debian Codegraph @

doc/programmers-guide/errorhandling.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <HTML
3 ><HEAD
4 ><TITLE
5 >Error Handling</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="HOME"
10 TITLE="Database Independent Abstraction Layer for C"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="Adding libdbi to your project"
14 HREF="addtoproject.html"><LINK
15 REL="NEXT"
16 TITLE="Connection error numbers and messages"
17 HREF="connerrors.html"></HEAD
18 ><BODY
19 CLASS="CHAPTER"
20 BGCOLOR="#FFFFFF"
21 TEXT="#000000"
22 LINK="#0000FF"
23 VLINK="#840084"
24 ALINK="#0000FF"
25 ><DIV
26 CLASS="NAVHEADER"
27 ><TABLE
28 SUMMARY="Header navigation table"
29 WIDTH="100%"
30 BORDER="0"
31 CELLPADDING="0"
32 CELLSPACING="0"
33 ><TR
34 ><TH
35 COLSPAN="3"
36 ALIGN="center"
37 >Database Independent Abstraction Layer for C: libdbi Programmer's Guide</TH
38 ></TR
39 ><TR
40 ><TD
41 WIDTH="10%"
42 ALIGN="left"
43 VALIGN="bottom"
44 ><A
45 HREF="addtoproject.html"
46 ACCESSKEY="P"
47 >Prev</A
48 ></TD
49 ><TD
50 WIDTH="80%"
51 ALIGN="center"
52 VALIGN="bottom"
53 ></TD
54 ><TD
55 WIDTH="10%"
56 ALIGN="right"
57 VALIGN="bottom"
58 ><A
59 HREF="connerrors.html"
60 ACCESSKEY="N"
61 >Next</A
62 ></TD
63 ></TR
64 ></TABLE
65 ><HR
66 ALIGN="LEFT"
67 WIDTH="100%"></DIV
68 ><DIV
69 CLASS="CHAPTER"
70 ><H1
71 ><A
72 NAME="ERRORHANDLING"
73 ></A
74 >Chapter 4. Error Handling</H1
75 ><DIV
76 CLASS="TOC"
77 ><DL
78 ><DT
79 ><B
80 >Table of Contents</B
81 ></DT
82 ><DT
83 >4.1. <A
84 HREF="connerrors.html"
85 >Connection error numbers and messages</A
86 ></DT
87 ><DT
88 >4.2. <A
89 HREF="errornumbers.html"
90 >Error numbers</A
91 ></DT
92 ></DL
93 ></DIV
94 ><P
95 >Applications should check all libdbi function calls for errors and respond appropriately to avoid entering an undefined status. libdbi uses two mechanisms to indicate errors:</P
96 ><P
97 ></P
98 ><DIV
99 CLASS="VARIABLELIST"
100 ><DL
101 ><DT
102 >Function return values</DT
103 ><DD
104 ><P
105 >Essentially all libdbi functions return a value, a concept not unfamiliar to the seasoned C programmer. For example, the <A
106 HREF="reference-core.html#DBI-INITIALIZE"
107 >dbi_initialize</A
108 > function returns the number of loaded drivers, or -1 if an error occurred. In this case checking the return value is sufficient to detect an error condition. However, other functions like the family of "getters" cannot indicate error conditions with a return value. Consider e.g. the <A
109 HREF="reference-field.html#DBI-RESULT-GET-STRING"
110 >dbi_result_get_string</A
111 > function which is used to retrieve strings from a database. If there was an error in accessing the value, the function will return the string "ERROR". However, this string is a legal value of such a field (the problem is the same for any other conceivable return value, including the empty string and the NULL pointer). Therefore we need an additional mechanism to report errors.</P
112 ></DD
113 ><DT
114 >Error numbers and error messages</DT
115 ><DD
116 ><P
117 >Connections store the status of the most recent operation which can be queried by the accessor function <A
118 HREF="reference-conn.html#DBI-CONN-ERROR"
119 ><CODE
120 CLASS="FUNCTION"
121 >dbi_conn_error</CODE
122 ></A
123 >. This is equivalent to the <CODE
124 CLASS="VARNAME"
125 >errno</CODE
126 > variable of the standard C library which is used by most system calls and can be printed in human-readable form by the <CODE
127 CLASS="FUNCTION"
128 >perror</CODE
129 > system call. This mechanism implies that your program queries the status right after each operation, as the values will be overwritten by subsequent operations.</P
130 ></DD
131 ></DL
132 ></DIV
133 ><P
134 >The return values of all libdbi functions are listed in the <A
135 HREF="reference.html"
136 >reference</A
137 > chapter below. The error numbers will be briefly discussed in the following sections.</P
138 ></DIV
139 ><DIV
140 CLASS="NAVFOOTER"
141 ><HR
142 ALIGN="LEFT"
143 WIDTH="100%"><TABLE
144 SUMMARY="Footer navigation table"
145 WIDTH="100%"
146 BORDER="0"
147 CELLPADDING="0"
148 CELLSPACING="0"
149 ><TR
150 ><TD
151 WIDTH="33%"
152 ALIGN="left"
153 VALIGN="top"
154 ><A
155 HREF="addtoproject.html"
156 ACCESSKEY="P"
157 >Prev</A
158 ></TD
159 ><TD
160 WIDTH="34%"
161 ALIGN="center"
162 VALIGN="top"
163 ><A
164 HREF="index.html"
165 ACCESSKEY="H"
166 >Home</A
167 ></TD
168 ><TD
169 WIDTH="33%"
170 ALIGN="right"
171 VALIGN="top"
172 ><A
173 HREF="connerrors.html"
174 ACCESSKEY="N"
175 >Next</A
176 ></TD
177 ></TR
178 ><TR
179 ><TD
180 WIDTH="33%"
181 ALIGN="left"
182 VALIGN="top"
183 >Adding libdbi to your project</TD
184 ><TD
185 WIDTH="34%"
186 ALIGN="center"
187 VALIGN="top"
188 >&nbsp;</TD
189 ><TD
190 WIDTH="33%"
191 ALIGN="right"
192 VALIGN="top"
193 >Connection error numbers and messages</TD
194 ></TR
195 ></TABLE
196 ></DIV
197 ></BODY
198 ></HTML
199 >