File: prguid16.htm

package info (click to toggle)
solid-doc 2.2-1
links: PTS
area: non-free
in suites: potato, slink
size: 3,436 kB
ctags: 11,371
sloc: makefile: 58; sh: 2
file content (2022 lines) | stat: -rw-r--r-- 66,942 bytes
parent folder | download | duplicates (2)
<HTML>
<HEAD>
<TITLE>prguide.htm</TITLE>
<LINK REL="ToC" HREF="httoc.htm">
<LINK REL="Index" HREF="htindex.htm">
<LINK REL="Next" HREF="prguid17.htm">
<LINK REL="Previous" HREF="prguid15.htm"></HEAD>
<BODY BGCOLOR="#FFFFFF">
<P ALIGN=CENTER>
<A HREF="prguid15.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="prguid17.htm" TARGET="_self"><IMG SRC="granext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>
<HR ALIGN=CENTER>
<P>
<UL>
<UL>
<LI>
<A HREF="#E74E3" >SQLConnect (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E107" >Syntax</A>
<LI>
<A HREF="#E11E108" >Returns</A>
<LI>
<A HREF="#E11E109" >Diagnostics</A>
<LI>
<A HREF="#E11E110" >Comments</A>
<UL>
<LI>
<A HREF="#E12E46" >Driver Manager Guidelines</A></UL>
<LI>
<A HREF="#E11E111" >Code Example</A>
<LI>
<A HREF="#E11E112" >Related Functions</A></UL>
<LI>
<A HREF="#E10E72" >SQLDataSources (ODBC 1.0, Level 2)</A>
<UL>
<LI>
<A HREF="#E11E113" >Syntax</A>
<LI>
<A HREF="#E11E114" >Returns</A>
<LI>
<A HREF="#E11E115" >Diagnostics</A>
<LI>
<A HREF="#E11E116" >Comments</A>
<LI>
<A HREF="#E11E117" >Related Functions</A></UL>
<LI>
<A HREF="#E10E73" >SQLDescribeCol (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E118" >Syntax</A>
<LI>
<A HREF="#E11E119" >Returns</A>
<LI>
<A HREF="#E11E120" >Diagnostics</A>
<LI>
<A HREF="#E11E121" >Comments</A>
<LI>
<A HREF="#E11E122" >Related Functions</A></UL>
<LI>
<A HREF="#E10E74" >SQLDescribeParam (ODBC 1.0, Level 2)</A>
<UL>
<LI>
<A HREF="#E11E123" >Syntax</A>
<LI>
<A HREF="#E11E124" >Returns</A>
<LI>
<A HREF="#E11E125" >Diagnostics</A>
<LI>
<A HREF="#E11E126" >Comments</A>
<LI>
<A HREF="#E11E127" >Related Functions</A></UL>
<LI>
<A HREF="#E10E75" >SQLDisconnect (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E128" >Syntax</A>
<LI>
<A HREF="#E11E129" >Returns</A>
<LI>
<A HREF="#E11E130" >Diagnostics</A>
<LI>
<A HREF="#E11E131" >Comments</A>
<LI>
<A HREF="#E11E132" >Code Example</A>
<LI>
<A HREF="#E11E133" >Related Functions</A></UL></UL></UL>
<HR ALIGN=CENTER>
<A NAME="E74E3"></A>
<H2>
<FONT FACE="Arial"><B>SQLConnect (ODBC 1.0, Core)</B><A NAME="I2"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLConnect</B> loads a driver and establishes a connection to a data source. The connection handle references storage of all information about the connection, including status, transaction state, and error information.
</BLOCKQUOTE>
<A NAME="E11E107"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLConnect</B>(<I>hdbc</I>, <I>szDSN</I>, <I>cbDSN</I>, <I>szUID</I>, <I>cbUID</I>, <I>szAuthStr</I>, <I>cbAuthStr</I>)<A NAME="I3"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLConnect</B> function accepts the following arguments.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E474"></A>
<P>Argument
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E474"></A>
<P>Use
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E474"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>HDBC
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E475"></A>
<P><I>hdbc</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E475"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E475"></A>
<P>Connection handle.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E476"></A>
<P><I>szDSN</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E476"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E476"></A>
<P>Data source name.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E477"></A>
<P><I>cbDSN</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E477"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E477"></A>
<P>Length of <I>szDSN</I>.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E478"></A>
<P><I>szUID</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E478"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E478"></A>
<P>User identifier.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E479"></A>
<P><I>cbUID</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E479"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E479"></A>
<P>Length of <I>szUID</I>.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E480"></A>
<P><I>szAuthStr</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E480"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E480"></A>
<P>Authentication string (typically the password).</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E481"></A>
<P><I>cbAuthStr</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E481"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E481"></A>
<P>Length of <I>szAuthStr</I>.</TD></TR></TABLE>
<A NAME="E11E108"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I4"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E109"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I5"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLConnect</B> returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling <B>SQLError</B>. The following table lists the SQLSTATE values commonly returned by <B>SQLConnect </B>and explains each one in the context of this function; the notation &quot;(DM)&quot; precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E482"></A>
<P>Error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E482"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E483"></A>
<P>General warning
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E483"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>08001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E484"></A>
<P>Unable to connect to data source
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E484"></A>
<P>The driver was unable to establish a connection with the data source.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>08002
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E485"></A>
<P>Connection in use
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E485"></A>
<P>(DM) The specified <I>hdbc</I> had already been used to establish a connection with a data source and the connection was still open.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>08004
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E486"></A>
<P>Data source rejected establishment of connection
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E486"></A>
<P>The data source rejected the establishment of the connection for implementation-defined reasons.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>08S01
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E487"></A>
<P>Communication link failure
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E487"></A>
<P>The communication link between the driver and the data source to which the driver was attempting to connect failed before the function completed processing.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>28000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E488"></A>
<P>Invalid authorization specification
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E488"></A>
<P>The value specified for the argument <I>szUID</I> or the value specified for the argument <I>szAuthStr</I> violated restrictions defined by the data source.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E489"></A>
<P>Driver does not support this function
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E489"></A>
<P>(DM) The driver specified by the data source name does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM002
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E490"></A>
<P>Data source not found and no default driver specified
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E490"></A>
<P>(DM) The data source name specified in the argument <I>szDSN</I> was not found in the ODBC.INI file or registry, nor was there a default driver specification.
<BLOCKQUOTE>
<P>(DM) The ODBC.INI file could not be found.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM003
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E491"></A>
<P>Specified driver could not be loaded
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E491"></A>
<P>(DM) The driver listed in the data source specification in the ODBC.INI file or registry was not found or could not be loaded for some other reason.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM004
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E492"></A>
<P>Driver&#146;s SQLAllocEnv failed
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E492"></A>
<P>(DM) During <B>SQLConnect</B>, the Driver Manager called the driver&#146;s <B>SQLAllocEnv</B> function and the driver returned an error.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM005
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E493"></A>
<P>Driver&#146;s SQLAllocConnect failed
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E493"></A>
<P>(DM) During <B>SQLConnect</B>, the Driver Manager called the driver&#146;s <B>SQLAllocConnect</B> function and the driver returned an error.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM006
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E494"></A>
<P>Driver&#146;s SQLSetConnectOption failed
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E494"></A>
<P>(DM) During <B>SQLConnect</B>, the Driver Manager called the driver&#146;s <B>SQLSetConnectOption</B> function and the driver returned an error. (Function returns SQL_SUCCESS_WITH_INFO).</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM009
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E495"></A>
<P>Unable to load translation DLL
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E495"></A>
<P>The driver was unable to load the translation DLL that was specified for the data source.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E496"></A>
<P>General error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E496"></A>
<P>An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by <B>SQLError</B> in the argument <I>szErrorMsg</I> describes the error and its cause.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E497"></A>
<P>Memory allocation failure
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E497"></A>
<P>(DM) The Driver Manager was unable to allocate memory required to support execution or completion of the function.
<BLOCKQUOTE>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1090
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E498"></A>
<P>Invalid string or buffer length 
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E498"></A>
<P>(DM) The value specified for argument <I>cbDSN</I> was less than 0, but not equal to SQL_NTS.
<BLOCKQUOTE>
<P>(DM) The value specified for argument <I>cbDSN</I> exceeded the maximum length for a data source name.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top ><BR></TD>
<TD WIDTH=120 VALIGN=top ><BR></TD>
<TD WIDTH=240 VALIGN=top >
<BLOCKQUOTE>
<P>(DM) The value specified for argument <I>cbUID</I> was less than 0, but not equal to SQL_NTS.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top ><BR></TD>
<TD WIDTH=120 VALIGN=top ><BR></TD>
<TD WIDTH=240 VALIGN=top >
<BLOCKQUOTE>
<P>(DM) The value specified for argument <I>cbAuthStr</I> was less than 0, but not equal to SQL_NTS.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1T00
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E499"></A>
<P>Timeout expired
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E499"></A>
<P>The timeout period expired before the connection to the data source completed. The timeout period is set through <B>SQLSetConnectOption</B>, SQL_LOGIN_TIMEOUT.</TD></TR></TABLE>
<A NAME="E11E110"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I6"></A><A NAME="I7"></A><A NAME="I8"></A><A NAME="I9"></A><A NAME="I10"></A></FONT></H3>
<BLOCKQUOTE>
<P>The Driver Manager does not load a driver until the application calls a function (<B>SQLConnect</B>, <B>SQLDriverConnect</B>, or <B>SQLBrowseConnect</B>) to connect to the driver. Until that point, the Driver Manager works with its own handles and manages connection information. When the application calls a connection function, the Driver Manager checks if a driver is currently loaded for the specified <I>hdbc</I>:<A NAME="I11"></A><A NAME="I12"></A><A NAME="I13"></A><A NAME="I14"></A><A NAME="I15"></A><A NAME="I16"></A><A NAME="I17"></A><A NAME="I18"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>If a driver is not loaded, the Driver Manager loads the driver and calls <B>SQLAllocEnv</B>, <B>SQLAllocConnect</B>, <B>SQLSetConnectOption</B> (if the application specified any connection options), and the connection function in the driver. The Driver Manager returns SQLSTATE IM006 (Driver&#146;s SQLSetConnectOption failed) and SQL_SUCCESS_WITH_INFO for the connection function if the driver returned an error for <B>SQLSetConnectOption</B>.<A NAME="I19"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the specified driver is already loaded on the <I>hdbc</I>, the Driver Manager only calls the connection function in the driver. In this case, the driver must ensure that all connection options for the <I>hdbc</I> maintain their current settings.<A NAME="I20"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If a different driver is loaded, the Driver Manager calls <B>SQLFreeConnect</B> and <B>SQLFreeEnv</B> in the loaded driver and then unloads that driver. It then performs the same operations as when a driver is not loaded.<A NAME="I21"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>The driver then allocates handles and initializes itself.<A NAME="I22"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note To resolve the addresses of the ODBC functions exported by the driver, the Driver Manager checks if the driver exports a dummy function with the ordinal 199. If it does not, the Driver Manager resolves the addresses by name. If it does, the Driver Manager resolves the addresses of the ODBC functions by ordinal, which is faster. The ordinal values of the ODBC functions must match the values of the <I>fFunction</I> argument in <B>SQLGetFunctions</B>; all other exported functions (such as <B>WEP</B>) must have ordinal values outside the range 1&#150;199.<A NAME="I23"></A><A NAME="I24"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>When the application calls <B>SQLDisconnect</B>, the Driver Manager calls <B>SQLDisconnect</B> in the driver. However, it does not unload the driver. This keeps the driver in memory for applications that repeatedly connect to and disconnect from a data source. When the application calls <B>SQLFreeConnect</B>, the Driver Manager calls <B>SQLFreeConnect</B> and <B>SQLFreeEnv</B> in the driver and then unloads the driver.<A NAME="I25"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An ODBC application can establish more than one connection.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E46"></A>
<H4>
<FONT>Driver Manager Guidelines<A NAME="I26"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The contents of <I>szDSN</I> affect how the Driver Manager and a driver work together to establish a connection to a data source.<A NAME="I27"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>If <I>szDSN</I> contains a valid data source name, the Driver Manager locates the corresponding data source specification in the ODBC.INI file or registry and loads the associated driver DLL. The Driver Manager passes each <B>SQLConnect</B> argument to the driver.<A NAME="I28"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the data source name cannot be found or <I>szDSN</I> is a null pointer, the Driver Manager locates the default data source specification and loads the associated driver DLL. The Driver Manager passes each <B>SQLConnect</B> argument to the driver.<A NAME="I29"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the data source name cannot be found or <I>szDSN</I> is a null pointer, and the default data source specification does not exist, the Driver Manager returns SQL_ERROR with SQLSTATE IM002 (Data source name not found and no default driver specified).<A NAME="I30"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>After being loaded by the Driver Manager, a driver can locate its corresponding data source specification in the ODBC.INI file or registry and use driver-specific information from the specification to complete its set of required connection information.<A NAME="I31"></A><A NAME="I32"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If a default translation DLL is specified in the ODBC.INI file or registry for the data source, the driver loads it. A different translation DLL can be loaded by calling <B>SQLSetConnectOption</B> with the SQL_TRANSLATE_DLL option. A translation option can be specified by calling <B>SQLSetConnectOption</B> with the SQL_TRANSLATE_OPTION option.<A NAME="I33"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If a driver supports <B>SQLConnect</B>, the driver keyword section of the ODBC.INF file for the driver must contain the <B>ConnectFunctions</B> keyword with the first character set to &quot;Y&quot;.
</BLOCKQUOTE>
<A NAME="E11E111"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I34"></A><A NAME="I35"></A></FONT></H3>
<BLOCKQUOTE>
<P>In the following example, an application allocates environment and connection handles. It then connects to the EmpData data source with the user ID JohnS and the password Sesame and processes data. When it has finished processing data, it disconnects from the data source and frees the handles.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">HENV    henv;
HDBC    hdbc;
HSTMT   hstmt;
RETCODE retcode;
retcode = SQLAllocEnv(&amp;henv);              /* Environment handle */
if (retcode == SQL_SUCCESS) {
   retcode = SQLAllocConnect(henv, &amp;hdbc); /* Connection handle */
   if (retcode == SQL_SUCCESS) {
      /* Set login timeout to 5 seconds. */
      SQLSetConnectOption(hdbc, SQL_LOGIN_TIMEOUT, 5);
      /* Connect to data source */
      retcode = SQLConnect(hdbc, &quot;EmpData&quot;, SQL_NTS,
<BR>                                 &quot;JohnS&quot;, SQL_NTS,
<BR>                                 &quot;Sesame&quot;, SQL_NTS);
<BR>
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){
         /* Process data after successful connection */
         retcode = SQLAllocStmt(hdbc, &amp;hstmt); /* Statement handle */
         if (retcode == SQL_SUCCESS) {
            ...;
            ...;
            ...;
            SQLFreeStmt(hstmt, SQL_DROP);
         }
         SQLDisconnect(hdbc);
      }
      SQLFreeConnect(hdbc);
   }
   SQLFreeEnv(henv);
}</FONT></PRE></BLOCKQUOTE>
<A NAME="E11E112"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800 >
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E500"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Allocating a connection handle
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E501"></A>
<P><B>SQLAllocConnect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Allocating a statement handle
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E502"></A>
<P><B>SQLAllocStmt</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Discovering and enumerating values required to connect to a data source
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E503"></A>
<P><B>SQLBrowseConnect</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Disconnecting from a data source
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E504"></A>
<P><B>SQLDisconnect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Connecting to a data source using a connection string or dialog box
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E505"></A>
<P><B>SQLDriverConnect</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the setting of a connection option
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E506"></A>
<P><B>SQLGetConnectOption</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Setting a connection option
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E507"></A>
<P><B>SQLSetConnectOption</B> (extension)</TD></TR></TABLE><A NAME="E10E72"></A>
<H2>
<FONT FACE="Arial"><B>SQLDataSources (ODBC 1.0, Level 2)</B><A NAME="I36"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLDataSources</B> lists data source names. This function is implemented solely by the Driver Manager.
</BLOCKQUOTE>
<A NAME="E11E113"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLDataSources</B>(<I>henv</I>, <I>fDirection</I>, <I>szDSN</I>, <I>cbDSNMax</I>, <I>pcbDSN</I>, <I>szDescription</I>, <I>cbDescriptionMax</I>, <I>pcbDescription</I>)<A NAME="I37"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLDataSources</B> function accepts the following arguments:
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E508"></A>
<P>Argument
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E508"></A>
<P>Use
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E508"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HENV
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E509"></A>
<P><I>henv</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E509"></A>
<P>Input
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E509"></A>
<P>Environment handle.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E510"></A>
<P><I>fDirection</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E510"></A>
<P>Input
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E510"></A>
<P>Determines whether the Driver Manager fetches the next data source name in the list (SQL_FETCH_NEXT) or whether the search starts from the beginning of the list (SQL_FETCH_FIRST).</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E511"></A>
<P><I>szDSN</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E511"></A>
<P>Output
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E511"></A>
<P>Pointer to storage for the data source name.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E512"></A>
<P><I>cbDSNMax</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E512"></A>
<P>Input
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E512"></A>
<P>Maximum length of the <I>szDSN</I> buffer; this does not need to be longer than SQL_MAX_DSN_LENGTH + 1.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E513"></A>
<P><I>pcbDSN</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E513"></A>
<P>Output
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E513"></A>
<P>Total number of bytes (excluding the null termination byte) available to return in <I>szDSN</I>. If the number of bytes available to return is greater than or equal to <I>cbDSNMax</I>, the data source name in <I>szDSN</I> is truncated to <I>cbDSNMax </I>&#150; 1 bytes.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E514"></A>
<P><I>szDescription</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E514"></A>
<P>Output
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E514"></A>
<P>Pointer to storage for the description of the driver associated with the data source. For example, dBASE or SQL Server.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E515"></A>
<P><I>cbDescriptionMax</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E515"></A>
<P>Input
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E515"></A>
<P>Maximum length of the <I>szDescription</I> buffer; this should be at least 255 bytes.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E516"></A>
<P><I>pcbDescription</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E516"></A>
<P>Output
</TD><TD WIDTH=181 VALIGN=top >
<A NAME="E7E516"></A>
<P>Total number of bytes (excluding the null termination byte) available to return in <I>szDescription</I>. If the number of bytes available to return is greater than or equal to <I>cbDescriptionMax</I>, the driver description in <I>szDescription</I> is truncated to <I>cbDescriptionMax </I>&#150; 1 bytes.</TD></TR></TABLE>
<A NAME="E11E114"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I38"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E115"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I39"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLDataSources</B> returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling <B>SQLError</B>. The following table lists the SQLSTATE values commonly returned by <B>SQLDataSources </B>and explains each one in the context of this function; the notation &quot;(DM)&quot; precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E517"></A>
<P>Error
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E517"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E518"></A>
<P>General warning
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E518"></A>
<P>(DM) Driver Manager&#150;specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>01004
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E519"></A>
<P>Data truncated
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E519"></A>
<P>(DM) The buffer <I>szDSN</I> was not large enough to return the entire data source name, so the name was truncated. The argument <I>pcbDSN</I> contains the length of the entire data source name. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top ><BR></TD>
<TD WIDTH=120 VALIGN=top ><BR></TD>
<TD WIDTH=246 VALIGN=top >
<BLOCKQUOTE>
<P>(DM) The buffer <I>szDescription</I> was not large enough to return the entire driver description, so the description was truncated. The argument <I>pcbDescription</I> contains the length of the untruncated data source description. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E520"></A>
<P>General error
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E520"></A>
<P>(DM) An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by <B>SQLError</B> in the argument <I>szErrorMsg</I> describes the error and its cause.</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E521"></A>
<P>Memory allocation failure
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E521"></A>
<P>(DM) The Driver Manager was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1090
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E522"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E522"></A>
<P>(DM) The value specified for argument <I>cbDSNMax</I> was less than 0.
<BLOCKQUOTE>
<P>(DM) The value specified for argument <I>cbDescriptionMax</I> was less than 0.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1103
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E523"></A>
<P>Direction option out of range
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E523"></A>
<P>(DM) The value specified for the argument <I>fDirection</I> was not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT.</TD></TR></TABLE>
<A NAME="E11E116"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I40"></A></FONT></H3>
<BLOCKQUOTE>
<P>Because <B>SQLDataSources</B> is implemented in the Driver Manager, it is supported for all drivers regardless of a particular driver&#146;s conformance level.<A NAME="I41"></A><A NAME="I42"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application can call <B>SQLDataSources</B> multiple times to retrieve all data source names. The Driver Manager retrieves this information from the ODBC.INI file or the registry. When there are no more data source names, the Driver Manager returns SQL_NO_DATA_FOUND. If <B>SQLDataSources</B> is called with SQL_FETCH_NEXT immediately after it returns SQL_NO_DATA_FOUND, it will return the first data source name.<A NAME="I43"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If SQL_FETCH_NEXT is passed to <B>SQLDataSources</B> the very first time it is called, it will return the first data source name.<A NAME="I44"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The driver determines how data source names are mapped to actual data sources.
</BLOCKQUOTE>
<A NAME="E11E117"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800 >
<TR>
<TD WIDTH=266 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=186 VALIGN=top >
<A NAME="E7E524"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=266 VALIGN=top >
<BLOCKQUOTE>
<P>Discovering and listing values required to connect to a data source
</BLOCKQUOTE></TD>
<TD WIDTH=186 VALIGN=top >
<A NAME="E7E525"></A>
<P><B>SQLBrowseConnect</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=266 VALIGN=top >
<BLOCKQUOTE>
<P>Connecting to a data source
</BLOCKQUOTE></TD>
<TD WIDTH=186 VALIGN=top >
<A NAME="E7E526"></A>
<P><B>SQLConnect</B></TD>
</TR>
<TR>
<TD WIDTH=266 VALIGN=top >
<BLOCKQUOTE>
<P>Connecting to a data source using a connection string or dialog box
</BLOCKQUOTE></TD>
<TD WIDTH=186 VALIGN=top >
<A NAME="E7E527"></A>
<P><B>SQLDriverConnect</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=266 VALIGN=top >
<BLOCKQUOTE>
<P>Returning driver descriptions and attributes
</BLOCKQUOTE></TD>
<TD WIDTH=186 VALIGN=top >
<A NAME="E7E528"></A>
<P><B>SQLDrivers</B> (extension)</TD></TR></TABLE><A NAME="E10E73"></A>
<H2>
<FONT FACE="Arial"><B>SQLDescribeCol (ODBC 1.0, Core)</B><A NAME="I45"></A><A NAME="I46"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLDescribeCol</B> returns the result descriptor &#151; column name, type, precision, scale, and nullability &#151; for one column in the result set; it cannot be used to return information about the bookmark column (column 0).
</BLOCKQUOTE>
<A NAME="E11E118"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLDescribeCol</B>(<I>hstmt</I>, <I>icol</I>, <I>szColName</I>, <I>cbColNameMax</I>, <I>pcbColName</I>, <I>pfSqlType</I>, <I>pcbColDef</I>, <I>pibScale</I>, <I>pfNullable</I>)
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLDescribeCol</B> function accepts the following arguments.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<A NAME="E7E529"></A>
<P>Argument
</TD><TD WIDTH=78 VALIGN=top >
<A NAME="E7E529"></A>
<P>Use
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E529"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<A NAME="E7E530"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=78 VALIGN=top >
<A NAME="E7E530"></A>
<P>Input
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E530"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<A NAME="E7E531"></A>
<P><I>icol</I>
</TD><TD WIDTH=78 VALIGN=top >
<A NAME="E7E531"></A>
<P>Input
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E531"></A>
<P>Column number of result data, ordered sequentially left to right, starting at 1.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<BLOCKQUOTE>
<P><I>szColName</I>
</BLOCKQUOTE></TD>
<TD WIDTH=78 VALIGN=top >
<A NAME="E7E532"></A>
<P>Output
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E532"></A>
<P>Pointer to storage for the column name. If the column is unnamed or the column name cannot be determined, the driver returns an empty string.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD<A NAME="I47"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<BLOCKQUOTE>
<P><I>cbColNameMax</I>
</BLOCKQUOTE></TD>
<TD WIDTH=78 VALIGN=top >
<A NAME="E7E533"></A>
<P>Input
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E533"></A>
<P>Maximum length of the <I>szColName</I> buffer.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<A NAME="E7E534"></A>
<P><I>pcbColName</I>
</TD><TD WIDTH=78 VALIGN=top >
<A NAME="E7E534"></A>
<P>Output
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E534"></A>
<P>Total number of bytes (excluding the null termination byte) available to return in <I>szColName</I>. If the number of bytes available to return is greater than or equal to <I>cbColNameMax</I>, the column name in <I>szColName</I> is truncated to <I>cbColNameMax </I>&#150; 1 bytes.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *<A NAME="I48"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<BLOCKQUOTE>
<P><I>pfSqlType</I>
</BLOCKQUOTE></TD>
<TD WIDTH=78 VALIGN=top >
<A NAME="E7E535"></A>
<P>Output
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E535"></A>
<P>The SQL data type of the column. This must be one of the following values:
<BLOCKQUOTE>
<P>SQL_BIGINT
<BR>SQL_BINARY
<BR>SQL_BIT
<BR>SQL_CHAR
<BR>SQL_DATE
<BR>SQL_DECIMAL
<BR>SQL_DOUBLE
<BR>SQL_FLOAT
<BR>SQL_INTEGER
<BR>SQL_LONGVARBINARY
<BR>SQL_LONGVARCHAR
<BR>SQL_NUMERIC
<BR>SQL_REAL
<BR>SQL_SMALLINT
<BR>SQL_TIME
<BR>SQL_TIMESTAMP
<BR>SQL_TINYINT
<BR>SQL_VARBINARY
<BR>SQL_VARCHAR
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>or a driver-specific SQL data type. If the data type cannot be determined, the driver returns 0.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information, see &quot;SQL Data Types&quot; in Appendix D, &quot;Data Types.&quot; For information about driver-specific SQL data types, see the driver&#146;s documentation.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UDWORD FAR *<A NAME="I49"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<BLOCKQUOTE>
<P><I>pcbColDef</I>
</BLOCKQUOTE></TD>
<TD WIDTH=78 VALIGN=top >
<A NAME="E7E536"></A>
<P>Output
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E536"></A>
<P>The precision of the column on the data source. If the precision cannot be determined, the driver returns 0. For more information on precision, see &quot;Precision, Scale, Length, and Display Size&quot; in Appendix D, &quot;Data Types.&quot;</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *<A NAME="I50"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<BLOCKQUOTE>
<P><I>pibScale</I>
</BLOCKQUOTE></TD>
<TD WIDTH=78 VALIGN=top >
<A NAME="E7E537"></A>
<P>Output
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E537"></A>
<P>The scale of the column on the data source. If the scale cannot be determined or is not applicable, the driver returns 0. For more information on scale, see &quot;Precision, Scale, Length, and Display Size&quot; in Appendix D, &quot;Data Types.&quot;</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *<A NAME="I51"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=91 VALIGN=top >
<BLOCKQUOTE>
<P><I>pfNullable</I>
</BLOCKQUOTE></TD>
<TD WIDTH=78 VALIGN=top >
<A NAME="E7E538"></A>
<P>Output
</TD><TD WIDTH=183 VALIGN=top >
<A NAME="E7E538"></A>
<P>Indicates whether the column allows NULL values. One of the following values:
<BLOCKQUOTE>
<P>SQL_NO_NULLS: The column does not allow NULL values.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NULLABLE: The column allows NULL values.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NULLABLE_UNKNOWN: The driver cannot determine if the column allows NULL values.</TD></TR></BLOCKQUOTE></TABLE>
<A NAME="E11E119"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I52"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E120"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I53"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLDescribeCol</B> returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling <B>SQLError</B>. The following table lists the SQLSTATE values commonly returned by <B>SQLDescribeCol </B>and explains each one in the context of this function; the notation &quot;(DM)&quot; precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E539"></A>
<P>Error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E539"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E540"></A>
<P>General warning
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E540"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01004
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E541"></A>
<P>Data truncated
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E541"></A>
<P>The buffer <I>szColName</I> was not large enough to return the entire column name, so the column name was truncated. The argument <I>pcbColName</I> contains the length of the untruncated column name. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>24000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E542"></A>
<P>Invalid cursor state
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E542"></A>
<P>The statement associated with the <I>hstmt</I> did not return a result set. There were no columns to describe.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E543"></A>
<P>Driver does not support this function
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E543"></A>
<P>(DM) The driver associated with the <I>hstmt</I> does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E544"></A>
<P>General error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E544"></A>
<P>An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by <B>SQLError</B> in the argument <I>szErrorMsg</I> describes the error and its cause.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E545"></A>
<P>Memory allocation failure
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E545"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1002
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E546"></A>
<P>Invalid column number
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E546"></A>
<P>(DM) The value specified for the argument <I>icol</I> was 0.
<BLOCKQUOTE>
<P>The value specified for the argument <I>icol</I> was greater than the number of columns in the result set.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1008
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E547"></A>
<P>Operation canceled
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E547"></A>
<P>Asynchronous processing was enabled for the <I>hstmt</I>. The function was called and before it completed execution, <B>SQLCancel</B> was called on the <I>hstmt</I>. Then the function was called again on the <I>hstmt</I>.
<BLOCKQUOTE>
<P>The function was called and, before it completed execution, <B>SQLCancel</B> was called on the <I>hstmt</I> from a different thread in a multithreaded application.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E548"></A>
<P>Function sequence error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E548"></A>
<P>(DM) The function was called prior to calling <B>SQLPrepare</B> or <B>SQLExecDirect</B> for the <I>hstmt</I>.
<BLOCKQUOTE>
<P>(DM) An asynchronously executing function (not this one) was called for the <I>hstmt</I> and was still executing when this function was called.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>(DM) <B>SQLExecute</B>, <B>SQLExecDirect</B>, or <B>SQLSetPos</B> was called for the <I>hstmt</I> and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1090
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E549"></A>
<P>Invalid string or buffer length 
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E549"></A>
<P>(DM) The value specified for argument <I>cbColNameMax</I> was less than 0.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1T00
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E550"></A>
<P>Timeout expired
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E550"></A>
<P>The timeout period expired before the data source returned the result set. The timeout period is set through <B>SQLSetStmtOption</B>, SQL_QUERY_TIMEOUT.</TD></TR></TABLE><A NAME="I54"></A>
<BLOCKQUOTE>
<P><B>SQLDescribeCol</B> can return any SQLSTATE that can be returned by <B>SQLPrepare</B> or <B>SQLExecute</B> when called after <B>SQLPrepare</B> and before <B>SQLExecute</B> depending on when the data source evaluates the SQL statement associated with the <I>hstmt</I>.
</BLOCKQUOTE>
<A NAME="E11E121"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I55"></A></FONT></H3>
<BLOCKQUOTE>
<P>An application typically calls <B>SQLDescribeCol</B> after a call to <B>SQLPrepare</B> and before or after the associated call to <B>SQLExecute</B>. An application can also call <B>SQLDescribeCol</B> after a call to <B>SQLExecDirect</B>.<A NAME="I56"></A><A NAME="I57"></A><A NAME="I58"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>SQLDescribeCol</B> retrieves the column name, type, and length generated by a <B>SELECT</B> statement. If the column is an expression, <I>szColName</I> is either an empty string or a driver-defined name.<A NAME="I59"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note. ODBC supports SQL_NULLABLE_UNKNOWN as an extension, even though the X/Open and SQL Access Group Call Level Interface specification does not specify the option for <B>SQLDescribeCol</B>.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<A NAME="E11E122"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800 >
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=205 VALIGN=top >
<A NAME="E7E551"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Assigning storage for a column in a result set
</BLOCKQUOTE></TD>
<TD WIDTH=205 VALIGN=top >
<A NAME="E7E552"></A>
<P><B>SQLBindCol</B></TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Canceling statement processing
</BLOCKQUOTE></TD>
<TD WIDTH=205 VALIGN=top >
<A NAME="E7E553"></A>
<P><B>SQLCancel</B></TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Returning information about a column in a result set
</BLOCKQUOTE></TD>
<TD WIDTH=205 VALIGN=top >
<A NAME="E7E554"></A>
<P><B>SQLColAttributes</B></TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Fetching a row of data
</BLOCKQUOTE></TD>
<TD WIDTH=205 VALIGN=top >
<A NAME="E7E555"></A>
<P><B>SQLFetch</B></TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the number of result set columns
</BLOCKQUOTE></TD>
<TD WIDTH=205 VALIGN=top >
<A NAME="E7E556"></A>
<P><B>SQLNumResultCols</B></TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Preparing a statement for execution
</BLOCKQUOTE></TD>
<TD WIDTH=205 VALIGN=top >
<A NAME="E7E557"></A>
<P><B>SQLPrepare</B></TD></TR></TABLE><A NAME="E10E74"></A>
<H2>
<FONT FACE="Arial"><B>SQLDescribeParam (ODBC 1.0, Level 2)</B><A NAME="I60"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLDescribeParam</B> returns the description of a parameter marker associated with a prepared SQL statement.
</BLOCKQUOTE>
<A NAME="E11E123"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLDescribeParam</B>(<I>hstmt</I>, <I>ipar</I>, <I>pfSqlType</I>, <I>pcbColDef</I>, <I>pibScale</I>, <I>pfNullable</I>)
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLDescribeParam</B> function accepts the following arguments:
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E558"></A>
<P>Argument
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E558"></A>
<P>Use
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E558"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT 
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E559"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E559"></A>
<P>Input
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E559"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E560"></A>
<P><I>ipar</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E560"></A>
<P>Input
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E560"></A>
<P>Parameter marker number ordered sequentially left to right, starting at 1.</TD>
</TR>
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *<A NAME="I61"></A><A NAME="I62"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P><I>pfSqlType</I>
</BLOCKQUOTE></TD>
<TD WIDTH=60 VALIGN=top >
<A NAME="E7E561"></A>
<P>Output
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E561"></A>
<P>The SQL data type of the parameter. This must be one of the following values:
<BLOCKQUOTE>
<P>SQL_BIGINT
<BR>SQL_BINARY
<BR>SQL_BIT
<BR>SQL_CHAR
<BR>SQL_DATE
<BR>SQL_DECIMAL
<BR>SQL_DOUBLE
<BR>SQL_FLOAT
<BR>SQL_INTEGER
<BR>SQL_LONGVARBINARY
<BR>SQL_LONGVARCHAR
<BR>SQL_NUMERIC
<BR>SQL_REAL
<BR>SQL_SMALLINT
<BR>SQL_TIME
<BR>SQL_TIMESTAMP
<BR>SQL_TINYINT
<BR>SQL_VARBINARY
<BR>SQL_VARCHAR
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>or a driver-specific SQL data type.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information, see &quot;SQL Data Types&quot; in Appendix D, &quot;Data Types.&quot; For information about driver-specific SQL data types, see the driver&#146;s documentation.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P>UDWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E562"></A>
<P><I>pcbColDef</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E562"></A>
<P>Output
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E562"></A>
<P>The precision of the column or expression of the corresponding parameter marker as defined by the data source. For further information concerning precision, see &quot;Precision, Scale, Length, and Display Size,&quot; in Appendix D, &quot;Data Types.&quot;</TD>
</TR>
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<A NAME="E7E563"></A>
<P><I>pibScale</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E563"></A>
<P>Output
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E563"></A>
<P>The scale of the column or expression of the corresponding parameter as defined by the data source. For more information on scale, see &quot;Precision, Scale, Length, and Display Size,&quot; in Appendix D, &quot;Data Types.&quot;</TD>
</TR>
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *<A NAME="I63"></A><A NAME="I64"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P><I>pfNullable</I>
</BLOCKQUOTE></TD>
<TD WIDTH=60 VALIGN=top >
<A NAME="E7E564"></A>
<P>Output
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E564"></A>
<P>Indicates whether the parameter allows NULL values. One of the following:
<BLOCKQUOTE>
<P>SQL_NO_NULLS: The parameter does not allow NULL values (this is the default value).
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NULLABLE: The parameter allows NULL values.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NULLABLE_UNKNOWN: The driver cannot determine if the parameter allows NULL values.</TD></TR></BLOCKQUOTE></TABLE>
<A NAME="E11E124"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I65"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E125"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I66"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLDescribeParam</B> returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling <B>SQLError</B>. The following table lists the SQLSTATE values commonly returned by <B>SQLDescribeParam </B>and explains each one in the context of this function; the notation &quot;(DM)&quot; precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E565"></A>
<P>Error
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E565"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E566"></A>
<P>General warning
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E566"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E567"></A>
<P>Driver does not support this function
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E567"></A>
<P>(DM) The driver associated with the <I>hstmt</I> does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E568"></A>
<P>General error
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E568"></A>
<P>An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by <B>SQLError</B> in the argument <I>szErrorMsg</I> describes the error and its cause.</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E569"></A>
<P>Memory allocation error
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E569"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1008
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E570"></A>
<P>Operation canceled
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E570"></A>
<P>Asynchronous processing was enabled for the <I>hstmt</I>. The function was called and before it completed execution, <B>SQLCancel</B> was called on the <I>hstmt</I>. Then the function was called again on the <I>hstmt</I>.
<BLOCKQUOTE>
<P>The function was called and, before it completed execution, <B>SQLCancel</B> was called on the <I>hstmt</I> from a different thread in a multithreaded application.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E571"></A>
<P>Function sequence error
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E571"></A>
<P>(DM) The function was called prior to calling <B>SQLPrepare</B> or <B>SQLExecDirect</B> for the <I>hstmt</I>.
<BLOCKQUOTE>
<P>(DM) An asynchronously executing function (not this one) was called for the <I>hstmt</I> and was still executing when this function was called.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>(DM) <B>SQLExecute</B>, <B>SQLExecDirect</B>, or <B>SQLSetPos</B> was called for the <I>hstmt</I> and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1093
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E572"></A>
<P>Invalid parameter number
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E572"></A>
<P>(DM) The value specified for the argument <I>ipar</I> was 0.
<BLOCKQUOTE>
<P>The value specified for the argument <I>ipar</I> was greater than the number of parameters in the associated SQL statement.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>S1T00
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E573"></A>
<P>Timeout expired
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E573"></A>
<P>The timeout period expired before the data source returned the result set. The timeout period is set through <B>SQLSetStmtOption</B>, SQL_QUERY_TIMEOUT.</TD></TR></TABLE>
<A NAME="E11E126"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I67"></A><A NAME="I68"></A><A NAME="I69"></A></FONT></H3>
<BLOCKQUOTE>
<P>Parameter markers are numbered from left to right in the order they appear in the SQL statement.<A NAME="I70"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>SQLDescribeParam</B> does not return the type (input, input/output, or output) of a parameter in an SQL statement. Except in calls to procedures, all parameters in SQL statements are input parameters. To determine the type of each parameter in a call to a procedure, an application calls <B>SQLProcedureColumns</B>.
</BLOCKQUOTE>
<A NAME="E11E127"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800 >
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E574"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Canceling statement processing
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E575"></A>
<P><B>SQLCancel</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Executing a prepared SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E576"></A>
<P><B>SQLExecute</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Preparing a statement for execution
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E577"></A>
<P><B>SQLPrepare</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Assigning storage for a parameter
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E578"></A>
<P><B>SQLBindParameter</B></TD></TR></TABLE><A NAME="E10E75"></A>
<H2>
<FONT FACE="Arial"><B>SQLDisconnect (ODBC 1.0, Core)</B><A NAME="I71"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLDisconnect</B> closes the connection associated with a specific connection handle.
</BLOCKQUOTE>
<A NAME="E11E128"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLDisconnect</B>(<I>hdbc</I>)<A NAME="I72"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLDisconnect</B> function accepts the following argument.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E579"></A>
<P>Argument
</TD><TD WIDTH=138 VALIGN=top >
<A NAME="E7E579"></A>
<P>Use
</TD><TD WIDTH=134 VALIGN=top >
<A NAME="E7E579"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>HDBC
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E580"></A>
<P><I>hdbc</I>
</TD><TD WIDTH=138 VALIGN=top >
<A NAME="E7E580"></A>
<P>Input
</TD><TD WIDTH=134 VALIGN=top >
<A NAME="E7E580"></A>
<P>Connection handle.</TD></TR></TABLE>
<A NAME="E11E129"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I73"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E130"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I74"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLDisconnect</B> returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling <B>SQLError</B>. The following table lists the SQLSTATE values commonly returned by <B>SQLDisconnect </B>and explains each one in the context of this function; the notation &quot;(DM)&quot; precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E581"></A>
<P>Error
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E581"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E582"></A>
<P>General warning
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E582"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01002
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E583"></A>
<P>Disconnect error
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E583"></A>
<P>An error occurred during the disconnect. However, the disconnect succeeded. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>08003
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E584"></A>
<P>Connection not open
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E584"></A>
<P>(DM) The connection specified in the argument <I>hdbc</I> was not open.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>25000
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E585"></A>
<P>Invalid transaction state
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E585"></A>
<P>There was a transaction in process on the connection specified by the argument <I>hdbc</I>. The transaction remains active.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E586"></A>
<P>Driver does not support this function
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E586"></A>
<P>(DM) The driver associated with the <I>hdbc</I> does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E587"></A>
<P>General error
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E587"></A>
<P>An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by <B>SQLError</B> in the argument <I>szErrorMsg</I> describes the error and its cause.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E588"></A>
<P>Memory allocation failure
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E588"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E589"></A>
<P>Function sequence error
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E589"></A>
<P>(DM) An asynchronously executing function was called for an <I>hstmt</I> associated with the <I>hdbc</I> and was still executing when <B>SQLDisconnect</B> was called.
<BLOCKQUOTE>
<P>(DM) <B>SQLExecute</B>, <B>SQLExecDirect</B>, or <B>SQLSetPos</B> was called for an <I>hstmt</I> associated with the <I>hdbc</I> and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.</TD></TR></BLOCKQUOTE></TABLE>
<A NAME="E11E131"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I75"></A><A NAME="I76"></A></FONT></H3>
<BLOCKQUOTE>
<P>If an application calls <B>SQLDisconnect</B> after <B>SQLBrowseConnect</B> returns SQL_NEED_DATA and before it returns a different return code, the driver cancels the connection browsing process and returns the <I>hdbc</I> to an unconnected state.<A NAME="I77"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If an application calls <B>SQLDisconnect</B> while there is an incomplete transaction associated with the connection handle, the driver returns SQLSTATE 25000 (Invalid transaction state), indicating that the transaction is unchanged and the connection is open. An incomplete transaction is one that has not been committed or rolled back with <B>SQLTransact</B>.<A NAME="I78"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If an application calls <B>SQLDisconnect</B> before it has freed all <I>hstmts</I> associated with the connection, the driver frees those <I>hstmts</I> after it successfully disconnects from the data source. However, if one or more of the <I>hstmts</I> associated with the connection are still executing asynchronously, <B>SQLDisconnect</B> will return SQL_ERROR with a SQLSTATE value of S1010 (Function sequence error).
</BLOCKQUOTE>
<A NAME="E11E132"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I79"></A></FONT></H3>
<BLOCKQUOTE>
<P>See <B>SQLBrowseConnect </B>and <B>SQLConnect</B>.
</BLOCKQUOTE>
<A NAME="E11E133"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800 >
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E590"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Allocating a connection handle
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E591"></A>
<P><B>SQLAllocConnect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Connecting to a data source
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E592"></A>
<P><B>SQLConnect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Connecting to a data source using a connection string or dialog box
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E593"></A>
<P><B>SQLDriverConnect</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Freeing a connection handle
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E594"></A>
<P><B>SQLFreeConnect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Executing a commit or rollback operation
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E595"></A>
<P><B>SQLTransact</B></TD></TR></TABLE><A NAME="E7E595"></A>
<P ALIGN=CENTER>
<A HREF="prguid15.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="prguid17.htm" TARGET="_self"><IMG SRC="granext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>

<center><p><font SIZE=-2>Copyright &copy; 1992-1997 Solid Information Technology Ltd All rights reserved.</font></p></center>
</BODY></HTML>