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
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
|
<HTML>
<HEAD>
<TITLE>prguide.htm</TITLE>
<LINK REL="ToC" HREF="httoc.htm">
<LINK REL="Index" HREF="htindex.htm">
<LINK REL="Next" HREF="prguide6.htm">
<LINK REL="Previous" HREF="prguide4.htm"></HEAD>
<BODY BGCOLOR="#FFFFFF">
<P ALIGN=CENTER>
<A HREF="prguide4.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="prguide6.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="#E9E6" >Connecting to a Data Source</A>
<UL>
<LI>
<A HREF="#E10E18" >About Data Sources</A>
<LI>
<A HREF="#E10E19" >Initializing the ODBC Environment</A>
<LI>
<A HREF="#E10E20" >Allocating a Connection Handle</A>
<LI>
<A HREF="#E10E21" >Connecting to a Data Source</A>
<LI>
<A HREF="#E10E22" >ODBC Extensions for Connections</A>
<UL>
<LI>
<A HREF="#E11E17" >Connecting to a Data Source With SQLDriverConnect</A>
<LI>
<A HREF="#E11E18" >Connection Browsing With SQLBrowseConnect</A>
<UL>
<LI>
<A HREF="#E12E7" >Connection Browsing Example for SQL Server</A>
<LI>
<A HREF="#E12E8" >Connection Browsing Example for DAL</A></UL>
<LI>
<A HREF="#E11E19" >Translating Data</A>
<LI>
<A HREF="#E11E20" >Additional Extension Functions</A></UL></UL></UL>
<HR ALIGN=CENTER>
<A NAME="E9E6"></A>
<H1>
<FONT FACE="Arial"><B>CONNECTING TO A DATA SOURCE</B><A NAME="I2"></A></FONT></H1>
<BR>
<BLOCKQUOTE>
<P>This chapter briefly introduces data sources. It then describes how to establish a connection to a data source.
</BLOCKQUOTE>
<A NAME="E10E18"></A>
<H2>
<FONT FACE="Arial"><B>About Data Sources</B><A NAME="I3"></A></FONT></H2>
<BLOCKQUOTE>
<P>A data source consists of the data a user wants to access, its associated DBMS, the platform on which the DBMS resides, and the network (if any) used to access that platform. Each data source requires that a driver provide certain information in order to connect to it. At the core level, this is defined to be the name of the data source, a user ID, and a password. ODBC extensions allow drivers to specify additional information such as a network address or additional passwords.
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>If the used data source name can be interpreted as a valid SOLID <I>Server</I> network name, the client first connects using the information given in the data source name. A valid network name consists of a <I>communication </I><I>protocol</I>, and optional <I>host computer name</I> and a <I>server name</I>.<I> </I>See <B>SOLID </B><B><I>Server</I></B><B> Administrator's Guide</B> for more information about listen names.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>If the data source name is not a valid SOLID <I>Server</I> listen name, the information needed to locate a server in the network is read from the ODBC.INI file or registry.<A NAME="I4"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The connection information for each data source is stored in the ODBC.INI file or registry, which is created during installation and maintained with an administration program. A section in this file lists the available data sources. Additional sections describe each data source in detail, specifying the driver name, a description, and any additional information the driver needs in order to connect to the data source.
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Applications that directly access the SOLID <I>SQL API</I> must connect to the server using a valid listen name. If the data source name is not a valid SOLID <I>Server</I> listen name, all SOLID client applications search for a valid listen name from
<BR>1) the SOLID.INI file
<BR>2) the ODBC.INI or registry
<BR>See <B>SOLID </B><B><I>Server</I></B><B> Administrator's Guide</B> for more information about the use of data source names.<A NAME="I5"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For example, suppose a user has five data sources: 1)Personnel and 2)Inventory, which use an Rdb DBMS, 3)Payroll, which uses an SQL Server DBMS, 4)tcp spiff 1313, which uses the SOLID <I>Server</I> network name to specify the server to connect to, and 5)Test, which uses a Logical Data Source Name. The section that lists the data sources might be:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>[ODBC Data Sources]
<BR>Personnel=Rdb
<BR>Inventory=Rdb
<BR>Payroll=SQL Server
<BR>tcp spiff 1313=SOLID Server
<BR>Test=SOLID Server<A NAME="I6"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>Suppose also that an Rdb driver needs the ID of the last user to log in, a server name, and a schema declaration statement. The section that describes the Personnel data source might be:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>[Personnel]
<BR>Driver=c:\windows\system\rdb.dll
<BR>Description=Personnel database: CURLY
<BR>Lastuid=smithjo
<BR>Server=curly
<BR>Schema=declare schema personnel filename "sys$sysdevice:[corpdata]personnel.rdb"</PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>The sections that describe the SOLID <I>Server</I> data sources might be:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>[tcp spiff 1313]
<BR>Driver=c:\windows\system\scliw16.dll
<BR>Description=Customer database
<BR>NetworkName=
[Test]
<BR>Driver=c:\windows\system\scliw16.dll
<BR>Description=Test database: Local
<BR>NetworkName=shmem solid</PRE></BLOCKQUOTE>
<A NAME="E10E19"></A>
<H2>
<FONT FACE="Arial"><B>Initializing the ODBC Environment</B><A NAME="I7"></A><A NAME="I8"></A><A NAME="I9"></A></FONT></H2>
<BLOCKQUOTE>
<P>Before an application can use any other ODBC function, it must initialize the ODBC interface and associate an environment handle with the environment. To initialize the interface and allocate an environment handle, an application:<A NAME="I10"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Declares a variable of the type HENV. For example, the application could use the declaration:
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<PRE> HENV henv1;<A NAME="I11"></A></PRE></BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>2. Calls <B>SQLAllocEnv</B> and passes it the address of the variable. The driver initializes the ODBC environment, allocates memory to store information about the environment, and returns the environment handle in the variable.<A NAME="I12"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>These steps should be performed only once by an application; <B>SQLAllocEnv</B> supports one or more connections to data sources.
</BLOCKQUOTE>
<A NAME="E10E20"></A>
<H2>
<FONT FACE="Arial"><B>Allocating a Connection Handle</B><A NAME="I13"></A><A NAME="I14"></A></FONT></H2>
<BLOCKQUOTE>
<P>Before an application can connect to a driver, it must allocate a handle for the connection. To allocate a connection handle, an application:<A NAME="I15"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Declares a variable of the type HDBC. For example, the application could use the declaration:
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<PRE> HDBC hdbc1;<A NAME="I16"></A></PRE></BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>2. Calls <B>SQLAllocConnect</B> and passes it the address of the variable. The driver allocates memory to store information about the connection and returns the connection handle in the variable.
</BLOCKQUOTE></UL>
<A NAME="E10E21"></A>
<H2>
<FONT FACE="Arial"><B>Connecting to a Data Source</B><A NAME="I17"></A><A NAME="I18"></A></FONT></H2>
<BLOCKQUOTE>
<P>Next, the application specifies a specific driver and data source. It passes the following information to the driver in a call to <B>SQLConnect</B>:<A NAME="I19"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI><B>Data source name</B> The name of the data source being requested by the application.<A NAME="I20"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>User ID</B> The login ID or account name for access to the data source if appropriate (optional).<A NAME="I21"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>Authentication string (password)</B> A character string associated with the user ID that allows access to the data source (optional).<A NAME="I22"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>When an application calls <B>SQLConnect</B>, the Driver Manager uses the data source name to read the name of the driver DLL from the appropriate section of the ODBC.INI file or registry. It then loads the driver DLL and passes the <B>SQLConnect</B> arguments to it. If the driver needs additional information to connect to the data source, it reads this information from the same section of the ODBC.INI file.<A NAME="I23"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application specifies a data source name that is not in the ODBC.INI file or registry, or if the application does not specify a data source name, the Driver Manager searches for the default data source specification. If it finds the default data source, it loads the default driver DLL and passes the application-specified data source name to it. If there is no default data source, the Driver Manager returns an error.
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>When an application uses SOLID <I>SQL API</I> directly and calls <B>SQLConnect</B> and does not specify a SOLID <I>Server</I> network name, it is read from the parameter Connect in the [Com] section of the SOLID.INI file. The SOLID.INI file must reside in the current working directory of the application or in path specified by the SOLIDDIR environment variable.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<A NAME="E10E22"></A>
<H2>
<FONT FACE="Arial"><B>ODBC Extensions for Connections</B><A NAME="I24"></A></FONT></H2>
<BLOCKQUOTE>
<P>ODBC extends the X/Open and SQL Access Group Call Level Interface to provide additional functions related to connections, drivers, and data sources. The remainder of this chapter describes these functions. To determine if a driver supports a specific function, an application calls <B>SQLGetFunctions</B>.
</BLOCKQUOTE>
<A NAME="E11E17"></A>
<H3>
<FONT FACE="Arial">Connecting to a Data Source With SQLDriverConnect<A NAME="I25"></A></FONT></H3>
<BLOCKQUOTE>
<P><B>SQLDriverConnect</B> supports:<A NAME="I26"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Data sources that require more connection information than the three arguments in <B>SQLConnect</B>.<A NAME="I27"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Dialog boxes to prompt the user for all connection information.<A NAME="I28"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Data sources that are not defined in the ODBC.INI file or registry.<A NAME="I29"></A><A NAME="I30"></A><A NAME="I31"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P><B>SQLDriverConnect</B> uses a connection string to specify the information needed to connect to a driver and data source.<A NAME="I32"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>A connection string contains the following information:<A NAME="I33"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Data source name or driver description<A NAME="I34"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Zero or more user IDs<A NAME="I35"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Zero or more passwords<A NAME="I36"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Zero or more data source-specific parameter values<A NAME="I37"></A><A NAME="I38"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>The connection string is a more flexible interface than the data source name, user ID, and password used by <B>SQLConnect</B>. The application can use the connection string for multiple levels of login authorization or to convey other data source-specific connection information.<A NAME="I39"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application calls <B>SQLDriverConnect</B> in one of three ways:<A NAME="I40"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Specifies a connection string that contains a data source name. The Driver Manager retrieves the full path of the driver DLL associated with the data source from the ODBC.INI file or registry. To retrieve a list of data source names, an application calls <B>SQLDataSources</B>.<A NAME="I41"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Specifies a connection string that contains a driver description. The Driver Manager retrieves the full path of the driver DLL. To retrieve a list of driver descriptions, an application calls <B>SQLDrivers</B>.<A NAME="I42"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Specifies a connection string that does not contain a data source name or a driver description. The Driver Manager displays a dialog box from which the user selects a data source name. The Driver Manager then retrieves the full path of the driver DLL associated with the data source.<A NAME="I43"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>The Driver Manager then loads the driver DLL and passes the <B>SQLDriverConnect</B> arguments to it.<A NAME="I44"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The application may pass all the connection information the driver needs. It may also request that the driver always prompt the user for connection information or only prompt the user for information it needs. Finally, if a data source is specified, the driver may read connection information from the appropriate section of the ODBC.INI file or registry.<A NAME="I45"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>After the driver connects to the data source, it returns the connection information to the application. The application may store this information for future use.<A NAME="I46"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application specifies a data source name that is not in the ODBC.INI file or registry, the Driver Manager searches for the default data source specification. If it finds the default data source, it loads the default driver DLL and passes the application-specified data source name to it. If there is no default data source, the Driver Manager returns an error.<A NAME="I47"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The Driver Manager displays the following dialog box if the application calls <B>SQLDriverConnect</B> and requests that the user be prompted for information.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>
<IMG SRC="prguide2.gif" WIDTH = 181 HEIGHT = 165 ALT="Undisplayed Graphic"><A NAME="I48"></A><A NAME="I49"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>On request from the application, the driver displays a dialog box similar to the following to retrieve login information.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>
<IMG SRC="prguide3.gif" WIDTH = 395 HEIGHT = 88 ALT="Undisplayed Graphic">
</BLOCKQUOTE>
<A NAME="E11E18"></A>
<H3>
<FONT FACE="Arial">Connection Browsing With SQLBrowseConnect<A NAME="I50"></A><A NAME="I51"></A><A NAME="I52"></A><A NAME="I53"></A></FONT></H3>
<BLOCKQUOTE>
<P><B>SQLBrowseConnect </B>supports an iterative method of listing and specifying the attributes and attribute values required to connect to a data source. For each level of a connection, an application calls <B>SQLBrowseConnect</B> and specifies the connection attributes and attribute values for that level. First level connection attributes always include the data source name or driver description; the connection attributes for later levels are data source dependent but might include the host, user name, and database.<A NAME="I54"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Each time <B>SQLBrowseConnect</B> is called, it validates the current attributes, returns the next level of attributes, and returns a user-friendly name for each attribute. It may also return a list of valid values for those attributes. (Note, however, that for some drivers and attributes, this list may not be complete.) After an application has specified each level of attributes and values, <B>SQLBrowseConnect</B> connects to the data source and returns a complete connection string. This string can be used in conjunction with <B>SQLDriverConnect</B> to connect to the data source at a later time.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E7"></A>
<H4>
<FONT>Connection Browsing Example for SQL Server<A NAME="I55"></A><A NAME="I56"></A><A NAME="I57"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The following example shows how <B>SQLBrowseConnect</B> might be used to browse the connections available with a driver for Microsoft’s SQL Server. Although other drivers may require different connection attributes, this example illustrates the connection browsing model. (For the syntax of browse request and result strings, see <B>SQLBrowseConnect</B> in Chapter 13, <I>Function </I><I>Reference</I>.)<A NAME="I58"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>First, the application requests a connection handle:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SQLAllocConnect(henv, &hdbc);<A NAME="I59"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>Next, the application calls <B>SQLBrowseConnect</B> and specifies a data source name:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SQLBrowseConnect(hdbc, "DSN=MySQLServer", SQL_NTS, szBrowseResult, 100, &cb);<A NAME="I60"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>Because this is the first call to <B>SQLBrowseConnect</B>, the Driver Manager locates the data source name (MySQLServer) in the ODBC.INI file and loads the corresponding driver DLL (SQLSRVR.DLL). The Driver Manager then calls the driver’s <B>SQLBrowseConnect</B> function with the same arguments it received from the application.<A NAME="I61"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The driver determines that this is the first call to <B>SQLBrowseConnect</B> and returns the second level of connection attributes: server, user name, password, and application name. For the server attribute, it returns a list of valid server names. The return code from <B>SQLBrowseConnect</B> is SQL_NEED_DATA. The browse result string is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>"SERVER:Server={red,blue,green,yellow};UID:Login ID=?;PWD:Password=?;*APP:AppName=?;*WSID:WorkStation ID=?"<A NAME="I62"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>Note that each keyword in the browse result string is followed by a colon and one or more words before the equal sign. These words are the user-friendly name that an application can use as a prompt in a dialog box.<A NAME="I63"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>In its next call to <B>SQLBrowseConnect</B>, the application must supply a value for the <B>SERVER</B>, <B>UID</B>, and <B>PWD</B> keywords. Because they are prefixed by an asterisk, the <B>APP</B> and <B>WSID</B> keywords are optional and may be omitted. The value for the <B>SERVER</B> keyword may be one of the servers returned by <B>SQLBrowseConnect</B> or a user-supplied name.<A NAME="I64"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The application calls <B>SQLBrowseConnect</B> again, specifying the green server and omitting the <B>APP</B> and <B>WSID</B> keywords and the user-friendly names after each keyword:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SQLBrowseConnect(hdbc, "SERVER=green;UID=Smith;PWD=Sesame", SQL_NTS, szBrowseResult, 100, &cb);<A NAME="I65"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>The driver attempts to connect to the green server. If there are any nonfatal errors, such as a missing keyword-value pair, <B>SQLBrowseConnect</B> returns SQL_NEED_DATA and remains in the same state as prior to the error. The application can call <B>SQLError</B> to determine the error. If the connection is successful, the driver returns SQL_NEED_DATA and returns the browse result string:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>"*DATABASE:Database={master,model,pubs,tempdb}; *LANGUAGE:Language={us_english,Français}"<A NAME="I66"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>Since the attributes in this string are optional, the application can omit them. However, the application must call <B>SQLBrowseConnect</B> again. If the application chooses to omit the database name and language, it specifies an empty browse request string. In this example, the application chooses the pubs database and calls <B>SQLBrowseConnect</B> a final time, omitting the <B>LANGUAGE</B> keyword and the asterisk before the <B>DATABASE</B> keyword:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SQLBrowseConnect(hdbc, "DATABASE=pubs", SQL_NTS, szBrowseResult, 100, &cb);<A NAME="I67"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>Since the <B>DATABASE</B> attribute is the final connection attribute of the data source, the browsing process is complete, the application is connected to the data source, and <B>SQLBrowseConnect</B> returns SQL_SUCCESS. <B>SQLBrowseConnect</B> also returns the complete connection string as the browse result string:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>"DSN=MySQLServer;SERVER=green;UID=Smith;PWD=Sesame;
<BR>DATABASE=pubs"<A NAME="I68"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>The final connection string returned by the driver does not contain the user-friendly names after each keyword, nor does it contain optional keywords not specified by the application. The application can use this string with <B>SQLDriverConnect</B> to reconnect to the data source on the current <I>hdbc</I> (after disconnecting) or to connect to the data source on a different <I>hdbc</I>:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SQLDriverConnect(hdbc, szBrowseResult, SQL_NTS, szConnStrOut, 100, &cb, SQL_DRIVER_NOPROMPT);</PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E8"></A>
<H4>
<FONT>Connection Browsing Example for DAL<A NAME="I69"></A><A NAME="I70"></A><A NAME="I71"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The following example shows how <B>SQLBrowseConnect</B> might be used in conjunction with a driver that uses Apple’s Data Access Language (DAL) to access an Oracle host. To browse the available connections, an application repeatedly calls <B>SQLBrowseConnect</B>:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>retcode = SQLBrowseConnect(hdbc, szConnStrIn, SQL_NTS, szConnStrOut, 200, &cb);<A NAME="I72"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>In the first call, the application specifies a data source name in <I>szConnStrIn</I>. In each subsequent call, the application bases the value of <I>szConnStrIn</I> on the value of <I>szConnStrOut</I> returned by the previous call. The application continues to call <B>SQLBrowseConnect</B> as long as the function returns SQL_NEED_DATA. The following list shows, for each call to <B>SQLBrowseConnect</B>, the value that the application specifies for <I>szConnStrIn</I> and the values that the driver returns for <I>retcode</I> and <I>szConnStrOut</I>. (For the syntax of the strings used in <I>szConnStrIn</I> and <I>szConnStrOut</I>, see <B>SQLBrowseConnect</B> in Chapter 13, <I>Function Reference</I>.)
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>szConnStrIn : "DSN=DAL"
szConnStrOut: "HOST:Host={MyVax,Direct,Unix};UID1:Host User Name=?;PWD1:Password=?"
retcode : SQL_NEED_DATA
szConnStrIn : "HOST=MyVax;UID1=Smith;PWD1=Sesame"
szConnStrOut: "DBMS:DBMS={Oracle,Informix,Sybase};UID2:DBMS User Name=?;PWD2:Password=?"
retcode : SQL_NEED_DATA
szConnStrIn : "DBMS=Oracle;UID2=John;PWD2=Lion"
szConnStrOut: "DATABASE:Database={DalDemo,Personnel,Production};*ALIAS:Alias=?;*UID3:User Name=?;*PWD3:Password=?"
retcode : SQL_NEED_DATA
szConnStrIn : "DATABASE=DalDemo;ALIAS=Demo"
szConnStrOut: "DSN=DAL;HOST=MyVax;UID1=Smith;PWD1=Sesame;DBMS=Oracle;UID2=John;PWD2=Lion;DATABASE=DalDemo;ALIAS=Demo"
retcode : SQL_SUCCESS<A NAME="I73"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>Note that the database alias, database user name, and database password are optional, as indicated by the asterisk before those attribute names. The application chooses not to specify the user name and password.
</BLOCKQUOTE>
<A NAME="E11E19"></A>
<H3>
<FONT FACE="Arial">Translating Data<A NAME="I74"></A><A NAME="I75"></A><A NAME="I76"></A><A NAME="I77"></A><A NAME="I78"></A></FONT></H3>
<BLOCKQUOTE>
<P>An application and a data source can store data in different formats. For example, the application might use a different character set than the data source. ODBC provides a mechanism by which a driver can translate all data (data values, SQL statements, table names, row counts, and so on) that passes between the driver and the data source.<A NAME="I79"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The driver translates data by calling functions in a translation DLL. A default translation DLL can be specified for the data source in the ODBC.INI file or registry; the application can override this by calling <B>SQLSetConnectOption</B>. When the driver connects to the data source, it loads the translation DLL (if one has been specified). After the driver has connected to the data source, the application may specify a new translation DLL by calling <B>SQLSetConnectOption</B>. <A NAME="I80"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Translation functions may support several different types of translation. For example, a function that translates data from one character set to another might support a variety of character sets. To specify a particular type of translation, an application can pass an option flag to the translation functions with <B>SQLSetConnectOption</B>.
</BLOCKQUOTE>
<A NAME="E11E20"></A>
<H3>
<FONT FACE="Arial">Additional Extension Functions<A NAME="I81"></A></FONT></H3>
<BLOCKQUOTE>
<P>ODBC also provides the following functions related to connections, drivers, and data sources. For more information about these functions, see Chapter 13, <I>Function Reference</I>.
</BLOCKQUOTE>
<TABLE WIDTH=600>
<TR>
<TD WIDTH=156 VALIGN=top >
<BLOCKQUOTE>
<P><B>Function</B>
</BLOCKQUOTE></TD>
<TD WIDTH=300 VALIGN=top >
<A NAME="E7E17"></A>
<P><B>Description</B></TD>
</TR>
<TR>
<TD WIDTH=156 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLDataSources</B>
</BLOCKQUOTE></TD>
<TD WIDTH=300 VALIGN=top >
<A NAME="E7E18"></A>
<P>Retrieves a list of available data sources. The Driver Manager retrieves this information from the ODBC.INI file or registry. An application can present this information to a user or automatically select a data source.</TD>
</TR>
<TR>
<TD WIDTH=156 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLDrivers</B>
</BLOCKQUOTE></TD>
<TD WIDTH=300 VALIGN=top >
<A NAME="E7E19"></A>
<P>Retrieves a list of installed drivers and their attributes. The Driver Manager retrieves this information from the ODBCINST.INI file or registry. An application can present this information to a user or automatically select a driver.</TD>
</TR>
<TR>
<TD WIDTH=156 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLGetFunctions</B>
</BLOCKQUOTE></TD>
<TD WIDTH=300 VALIGN=top >
<A NAME="E7E20"></A>
<P>Retrieves functions supported by a driver. This function allows an application to determine at run time whether a particular function is supported by a driver.</TD>
</TR>
<TR>
<TD WIDTH=156 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLGetInfo</B>
</BLOCKQUOTE></TD>
<TD WIDTH=300 VALIGN=top >
<A NAME="E7E21"></A>
<P>Retrieves general information about a driver and data source, including filenames, versions, conformance levels, and capabilities.</TD>
</TR>
<TR>
<TD WIDTH=156 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLGetTypeInfo</B>
</BLOCKQUOTE></TD>
<TD WIDTH=300 VALIGN=top >
<A NAME="E7E22"></A>
<P>Retrieves the SQL data types supported by a driver and data source.</TD>
</TR>
<TR>
<TD WIDTH=156 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSetConnectOption</B>
<BR><B>SQLGetConnectOption</B>
</BLOCKQUOTE></TD>
<TD WIDTH=300 VALIGN=top >
<A NAME="E7E23"></A>
<P>These functions set or retrieve connection options, such as the data source access mode, automatic transaction commitment, timeout values, function tracing, data translation options, and transaction isolation.</TD></TR></TABLE>
<P ALIGN=CENTER>
<A HREF="prguide4.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="prguide6.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>
|
