1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
|
<HTML>
<HEAD>
<TITLE>prguide.htm</TITLE>
<LINK REL="ToC" HREF="httoc.htm">
<LINK REL="Index" HREF="htindex.htm">
<LINK REL="Next" HREF="prguide4.htm">
<LINK REL="Previous" HREF="prguide2.htm"></HEAD>
<BODY BGCOLOR="#FFFFFF">
<P ALIGN=CENTER>
<A HREF="prguide2.htm" TARGET="_self"><IMG SRC="graprev.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Previous Page"></A>
<A HREF="httoc.htm" TARGET="_self"><IMG SRC="gratoc.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="TOC"></A>
<A HREF="htindex.htm" TARGET="_self"><IMG SRC="graindex.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Index"></A>
<A HREF="prguide4.htm" TARGET="_self"><IMG SRC="granext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>
<HR ALIGN=CENTER>
<P>
<UL>
<LI>
<A HREF="#E9E4" >Guidelines for Calling Functions</A>
<UL>
<LI>
<A HREF="#E10E14" >General Information</A>
<LI>
<A HREF="#E10E15" >Determining Driver Conformance Levels</A>
<UL>
<UL>
<LI>
<A HREF="#E12E3" >Determining API Conformance Levels</A>
<LI>
<A HREF="#E12E4" >Determining SQL Conformance Levels</A></UL></UL>
<LI>
<A HREF="#E10E16" >Using the Driver Manager</A>
<LI>
<A HREF="#E10E17" >Calling ODBC Functions</A>
<UL>
<LI>
<A HREF="#E11E13" >Buffers</A>
<UL>
<LI>
<A HREF="#E12E5" >Input Buffers</A>
<LI>
<A HREF="#E12E6" >Output Buffers</A></UL>
<LI>
<A HREF="#E11E14" >Environment, Connection, and Statement Handles</A>
<LI>
<A HREF="#E11E15" >Using Data Types</A>
<LI>
<A HREF="#E11E16" >ODBC Function Return Codes</A></UL></UL></UL>
<HR ALIGN=CENTER>
<A NAME="E9E4"></A>
<H1>
<FONT FACE="Arial"><B>GUIDELINES FOR CALLING FUNCTIONS</B><A NAME="I2"></A></FONT></H1>
<BR>
<BLOCKQUOTE>
<P>This chapter describes the general characteristics of ODBC functions, determining driver conformance levels, the role of the Driver Manager, ODBC function arguments, and the values ODBC functions return.
</BLOCKQUOTE>
<A NAME="E10E14"></A>
<H2>
<FONT FACE="Arial"><B>General Information</B><A NAME="I3"></A></FONT></H2>
<BLOCKQUOTE>
<P>Each SOLID <I>SQL API</I> and ODBC function name starts with the prefix "SQL." Each function accepts one or more arguments. Arguments are defined as input (to the driver) or output (from the the driver).<A NAME="I4"></A><A NAME="I5"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>C programs that call ODBC functions must include the SQL.H, SQLEXT.H, and WINDOWS.H header files. These files define Windows and ODBC constants and types and provide function prototypes for all ODBC functions.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>C programs that call SOLID <I>SQL API</I> functions must include the CLI0CORE.H, CLI0DEFS.H, CLI0ENV.H and CLI01EXT1.H header files. These files define constants and types and provide function prototypes for all SOLID <I>SQL API</I> functions.
</BLOCKQUOTE>
<A NAME="E10E15"></A>
<H2>
<FONT FACE="Arial"><B>Determining Driver Conformance Levels</B><A NAME="I6"></A><A NAME="I7"></A></FONT></H2>
<BLOCKQUOTE>
<P>ODBC defines conformance levels for drivers in two areas: the ODBC API and the ODBC SQL grammar (which includes the ODBC SQL data types). These levels establish standard sets of functionality. By inquiring the conformance levels supported by a driver, an application can easily determine if the driver provides the necessary functionality. For a complete discussion of ODBC conformance levels, see "ODBC Conformance Levels" in Chapter 1, "ODBC Theory of Operation."
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note The following sections refer to <B>SQLGetInfo</B> and <B>SQLGetTypeInfo</B>, which are part of the Level 1 API conformance level. Although it is strongly recommended that drivers support this conformance level, drivers are not required to do so. If these functions are not supported, an application developer must consult the driver documentation to determine its conformance levels.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E3"></A>
<H4>
<FONT>Determining API Conformance Levels<A NAME="I8"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>ODBC functions are divided into core functions, which are defined in the X/Open and SQL Access Group Call Level Interface specification, and two levels of extension functions, with which ODBC extends this specification. To determine the function conformance level of a driver, an application calls <B>SQLGetInfo</B> with the SQL_ODBC_SAG_CLI_CONFORMANCE and SQL_ODBC_API_CONFORMANCE flags. Note that a driver can support one or more extension functions but not conform to ODBC extension Level 1 or 2. To determine if a driver supports a particular function, an application calls <B>SQLGetFunctions</B>. Note that <B>SQLGetFunctions</B> is implemented by the Driver Manager and can be called for any driver, regardless of its level.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E4"></A>
<H4>
<FONT>Determining SQL Conformance Levels<A NAME="I9"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The ODBC SQL grammar, which includes SQL data types, is divided into a minimum grammar, a core grammar, which corresponds to the X/Open and SQL Access Group SQL CAE specification (1992), and an extended grammar, which provides common extensions to SQL. To determine the SQL conformance level of a driver, an application calls <B>SQLGetInfo</B> with the SQL_ODBC_SQL_CONFORMANCE flag. To determine whether a driver supports a specific SQL extension, an application calls <B>SQLGetInfo</B> with a flag for that extension. For more information, see Appendix C, "SQL Grammar." To determine whether a driver supports a specific SQL data type, an application calls <B>SQLGetTypeInfo</B>.
</BLOCKQUOTE>
<A NAME="E10E16"></A>
<H2>
<FONT FACE="Arial"><B>Using the Driver Manager</B><A NAME="I10"></A></FONT></H2>
<BLOCKQUOTE>
<P>The Driver Manager is a DLL that provides access to ODBC drivers. An application typically links with the Driver Manager import library (ODBC.LIB) to gain access to the Driver Manager.
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Application accessing SOLID <I>SQL API</I> directly bypass the Driver Manager and cannot therefore use ODBC functions that are implemented in the Driver Manager.<A NAME="I11"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Whenever an application calls an ODBC function, the Driver Manager performs one of the following actions:<A NAME="I12"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>For <B>SQLDataSources</B> and <B>SQLDrivers</B>, the Driver Manager processes the call. It does not pass the call to the driver.<A NAME="I13"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For <B>SQLGetFunctions</B>, the Driver Manager passes the call to the driver associated with the connection. If the driver does not support <B>SQLGetFunctions</B>, the Driver Manager processes the call.<A NAME="I14"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For <B>SQLAllocEnv</B>, <B>SQLAllocConnect</B>, <B>SQLSetConnectOption</B>, <B>SQLFreeConnect</B>, and <B>SQLFreeEnv</B>, the Driver Manager processes the call. The Driver Manager calls <B>SQLAllocEnv</B>, <B>SQLAllocConnect</B>, and <B>SQLSetConnectOption</B> in the driver when the application calls a function to connect to the data source (<B>SQLConnect</B>, <B>SQLDriverConnect</B>, or <B>SQLBrowseConnect</B>). The Driver Manager calls <B>SQLFreeConnect</B> and <B>SQLFreeEnv</B> in the driver when the application calls <B>SQLDisconnect</B>.<A NAME="I15"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For <B>SQLConnect</B>, <B>SQLDriverConnect</B>, <B>SQLBrowseConnect</B>, and <B>SQLError</B>, the Driver Manager performs initial processing then passes the call to the driver associated with the connection.<A NAME="I16"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For any other ODBC function, the Driver Manager passes the call to the driver associated with the connection.<A NAME="I17"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>If requested, the Driver Manager records each called function in a trace file. The name of each function is recorded, along with the values of the input arguments and the names of the output arguments (as listed in the function definitions).
</BLOCKQUOTE>
<A NAME="E10E17"></A>
<H2>
<FONT FACE="Arial"><B>Calling ODBC Functions</B><A NAME="I18"></A></FONT></H2>
<BLOCKQUOTE>
<P>The following paragraphs describe general characteristics of ODBC functions.
</BLOCKQUOTE>
<A NAME="E11E13"></A>
<H3>
<FONT FACE="Arial">Buffers<A NAME="I19"></A><A NAME="I20"></A><A NAME="I21"></A><A NAME="I22"></A><A NAME="I23"></A><A NAME="I24"></A></FONT></H3>
<BLOCKQUOTE>
<P>An application passes data to a driver in an input buffer. The driver returns data to an application in an output buffer. The application must allocate memory for both input and output buffers. (If the application will use the buffer to retrieve string data, the buffer must contain space for the null termination byte.)<A NAME="I25"></A><A NAME="I26"></A><A NAME="I27"></A><A NAME="I28"></A><A NAME="I29"></A><A NAME="I30"></A><A NAME="I31"></A><A NAME="I32"></A><A NAME="I33"></A><A NAME="I34"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Note that some functions accept pointers to buffers that are later used by other functions. The application must ensure that these pointers remain valid until all applicable functions have used them. For example, the argument <I>rgbValue</I> in <B>SQLBindCol</B> points to an output buffer in which <B>SQLFetch</B> returns the data for a column.
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Caution ODBC does not require drivers to correctly manage buffers that cross segment boundaries in Windows 3.1. The Driver Manager supports the use of such buffers, since it passes buffer addresses to drivers and does not operate on buffer contents. If a driver supports buffers that cross segment boundaries, the documentation for the driver should clearly state this.
<BR>
<BR>For maximum interoperability, applications that use buffers that cross segment boundaries should pass them in pieces to ODBC functions. None of these pieces can cross a segment boundary. For example, suppose a data source contains 100 kilobytes of bitmap data. A Windows 3.1 application can safely allocate 100K of memory (beginning at a segment boundary) and retrieve the data in two pieces (64K and 36K), each of which begins on a segment boundary.<A NAME="I35"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E5"></A>
<H4>
<FONT>Input Buffers<A NAME="I36"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application passes the address and length of an input buffer to a driver. The length of the buffer must be one of the following values:<A NAME="I37"></A><A NAME="I38"></A><A NAME="I39"></A><A NAME="I40"></A><A NAME="I41"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>A length greater than or equal to zero. This is the actual length of the data in the input buffer. For character data, a length of zero indicates that the data is an empty (zero length) string. Note that this is different from a null pointer. If the application specifies the length of character data, the character data does not need to be null-terminated.<A NAME="I42"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>SQL_NTS. This specifies that a character data value is null-terminated.<A NAME="I43"></A><A NAME="I44"></A><A NAME="I45"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>SQL_NULL_DATA. This tells the driver to ignore the value in the input buffer and use a NULL data value instead. It is only valid when the input buffer is used to provide the value of a parameter in an SQL statement.<A NAME="I46"></A><A NAME="I47"></A><A NAME="I48"></A><A NAME="I49"></A><A NAME="I50"></A><A NAME="I51"></A><A NAME="I52"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>The operation of ODBC functions on character data containing embedded null characters is undefined, and is not recommended for maximum interoperability.<A NAME="I53"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Unless it is specifically prohibited in a function description, the address of an input buffer may be a null pointer. When the address of an input buffer is a null pointer, the value of the corresponding buffer length argument is ignored.<A NAME="I54"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information about input buffers, see "Converting Data from C to SQL Data Types" in Appendix D, "Data Types."
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E6"></A>
<H4>
<FONT>Output Buffers<A NAME="I55"></A><A NAME="I56"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application passes the following arguments to a driver, so that it can return data in an output buffer:<A NAME="I57"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>The address of the buffer in which the driver returns the data (the output buffer). Unless it is specifically prohibited in a function description, the address of an output buffer can be a null pointer. In this case, the driver does not return anything in the buffer and, in the absence of other errors, returns SQL_SUCCESS.<A NAME="I58"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI> If necessary, the driver converts data before returning it. The driver always null-terminates character data before returning it.<A NAME="I59"></A><A NAME="I60"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The length of the buffer. This is ignored by the driver if the returned data has a fixed length in C, such as an integer, real number, or date structure.<A NAME="I61"></A><A NAME="I62"></A><A NAME="I63"></A><A NAME="I64"></A><A NAME="I65"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The address of a variable in which the driver returns the length of the data (the length buffer). The returned length of the data is SQL_NULL_DATA if the data is a NULL value in a result set. Otherwise, it is the number of bytes of data available to return. If the driver converts the data, it is the number of bytes after the conversion. For character data, it does not include the null termination byte added by the driver.<A NAME="I66"></A><A NAME="I67"></A><A NAME="I68"></A><A NAME="I69"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>If the output buffer is too small, the driver attempts to truncate the data. If the truncation does not cause a loss of significant data, the driver returns the truncated data in the output buffer, returns the length of the available data (as opposed to the length of the truncated data) in the length buffer, and returns SQL_SUCCESS_WITH_INFO. If the truncation causes a loss of significant data, the driver leaves the output and length buffers untouched and returns SQL_ERROR. The application calls <B>SQLError</B> to retrieve information about the truncation or the error.<A NAME="I70"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information about output buffers, see "Converting Data from SQL to C Data Types" in Appendix D, "Data Types."
</BLOCKQUOTE>
<A NAME="E11E14"></A>
<H3>
<FONT FACE="Arial">Environment, Connection, and Statement Handles<A NAME="I71"></A><A NAME="I72"></A><A NAME="I73"></A><A NAME="I74"></A><A NAME="I75"></A><A NAME="I76"></A><A NAME="I77"></A></FONT></H3>
<BLOCKQUOTE>
<P>When so requested by an application, the Driver Manager and each driver allocate storage for information about the ODBC environment, each connection, and each SQL statement. The handles to these storage areas are returned to the application. The application then uses one or more of them in each call to an ODBC function.<A NAME="I78"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The ODBC interface defines three types of handles:<A NAME="I79"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>The <B>environment handle </B>identifies memory storage for global information, including the valid connection handles and the current active connection handle. ODBC defines the environment handle as a variable of type HENV. An application uses a single environment handle; it must request this handle prior to connecting to a data source.<A NAME="I80"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>Connection handles </B>identify memory storage for information about a particular connection. ODBC defines connection handles as variables of type HDBC. An application must request a connection handle prior to connecting to a data source. Each connection handle is associated with the environment handle. The environment handle can, however, have multiple connection handles associated with it.<A NAME="I81"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>Statement handles </B>identify memory storage for information about an SQL statement. ODBC defines statement handles as variables of type HSTMT. An application must request a statement handle prior to submitting SQL requests. Each statement handle is associated with exactly one connection handle. Each connection handle can, however, have multiple statement handles associated with it.<A NAME="I82"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>For more information about requesting a connection handle, see Chapter 5, "Connecting to a Data Source." For more information about requesting a statement handle, see Chapter 6, "Executing SQL Statements."
</BLOCKQUOTE>
<A NAME="E11E15"></A>
<H3>
<FONT FACE="Arial">Using Data Types<A NAME="I83"></A><A NAME="I84"></A></FONT></H3>
<BLOCKQUOTE>
<P>Data stored on a data source has an SQL data type, which may be specific to that data source. A driver maps data source–specific SQL data types to ODBC SQL data types, which are defined in the ODBC SQL grammar, and driver-specific SQL data types. (A driver returns these mappings through <B>SQLGetTypeInfo</B>. It also uses the ODBC SQL data types to describe the data types of columns and parameters in <B>SQLColAttributes</B>, <B>SQLDescribeCol</B>, and <B>SQLDescribeParam</B>.)<A NAME="I85"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Each SQL data type corresponds to an ODBC C data type. By default, the driver assumes that the C data type of a storage location corresponds to the SQL data type of the column or parameter to which the location is bound. If the C data type of a storage location is not the <I>default</I> C data type, the application can specify the correct C data type with the <I>fCType</I> argument in <B>SQLBindCol</B>, <B>SQLGetData</B>, or <B>SQLBindParameter</B>. Before returning data from the data source, the driver converts it to the specified C data type. Before sending data to the data source, the driver converts it from the specified C data type.<A NAME="I86"></A><A NAME="I87"></A><A NAME="I88"></A><A NAME="I89"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information about data types, see Appendix D, "Data Types." The C data types are defined in SQL.H and SQLEXT.H.
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE> The C data types of SOLID <I>SQL API</I> and defined in CLI0DEFS.H.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<A NAME="E11E16"></A>
<H3>
<FONT FACE="Arial">ODBC Function Return Codes<A NAME="I90"></A></FONT></H3>
<BLOCKQUOTE>
<P>When an application calls an ODBC function, the driver executes the function and returns a predefined code. These return codes indicate success, warning, or failure status. The return codes are:
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SUCCESS
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SUCCESS_WITH_INFO
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NO_DATA_FOUND
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_ERROR
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_INVALID_HANDLE
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_STILL_EXECUTING
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NEED_DATA<A NAME="I91"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR, the application can call <B>SQLError</B> to retrieve additional information about the error. For a complete description of return codes and error handling, see Chapter 8, "Retrieving Status and Error Information."
</BLOCKQUOTE><P ALIGN=CENTER>
<A HREF="prguide2.htm" TARGET="_self"><IMG SRC="graprev.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Previous Page"></A>
<A HREF="httoc.htm" TARGET="_self"><IMG SRC="gratoc.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="TOC"></A>
<A HREF="htindex.htm" TARGET="_self"><IMG SRC="graindex.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Index"></A>
<A HREF="prguide4.htm" TARGET="_self"><IMG SRC="granext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>
<center><p><font SIZE=-2>Copyright © 1992-1997 Solid Information Technology Ltd All rights reserved.</font></p></center>
</BODY></HTML>
|
