File: prguid15.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 (3022 lines) | stat: -rw-r--r-- 109,629 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="prguid16.htm">
<LINK REL="Previous" HREF="prguid14.htm"></HEAD>
<BODY BGCOLOR="#FFFFFF">
<P ALIGN=CENTER>
<A HREF="prguid14.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="prguid16.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="#E74E2" >SQLBrowseConnect (ODBC 1.0, Level 2)</A>
<UL>
<LI>
<A HREF="#E11E79" >Syntax</A>
<LI>
<A HREF="#E11E80" >Returns</A>
<LI>
<A HREF="#E11E81" >Diagnostics</A>
<LI>
<A HREF="#E11E82" >Comments</A>
<UL>
<LI>
<A HREF="#E12E40" >szConnStrIn Argument</A>
<LI>
<A HREF="#E12E41" >szConnStrOut Argument</A>
<LI>
<A HREF="#E12E42" >Using SQLBrowseConnect</A></UL>
<LI>
<A HREF="#E11E83" >Code Example</A>
<LI>
<A HREF="#E11E84" >Related Functions</A></UL>
<LI>
<A HREF="#E10E68" >SQLCancel (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E85" >Syntax</A>
<LI>
<A HREF="#E11E86" >Returns</A>
<LI>
<A HREF="#E11E87" >Diagnostics</A>
<LI>
<A HREF="#E11E88" >Comments</A>
<UL>
<LI>
<A HREF="#E12E43" >Canceling Asynchronous Processing</A>
<LI>
<A HREF="#E12E44" >Canceling Functions that Need Data</A>
<LI>
<A HREF="#E12E45" >Canceling Functions in Multithreaded Applications</A></UL>
<LI>
<A HREF="#E11E89" >Related Functions</A></UL>
<LI>
<A HREF="#E10E69" >SQLColAttributes (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E90" >Syntax</A>
<LI>
<A HREF="#E11E91" >Returns</A>
<LI>
<A HREF="#E11E92" >Diagnostics</A>
<LI>
<A HREF="#E11E93" >Comments</A>
<LI>
<A HREF="#E11E94" >Related Functions</A></UL>
<LI>
<A HREF="#E10E70" >SQLColumnPrivileges (ODBC 1.0, Level 2)</A>
<UL>
<LI>
<A HREF="#E11E95" >Syntax</A>
<LI>
<A HREF="#E11E96" >Returns</A>
<LI>
<A HREF="#E11E97" >Diagnostics</A>
<LI>
<A HREF="#E11E98" >Comments</A>
<LI>
<A HREF="#E11E99" >Code Example</A>
<LI>
<A HREF="#E11E100" >Related Functions</A></UL>
<LI>
<A HREF="#E10E71" >SQLColumns (ODBC 1.0, Level 1)</A>
<UL>
<LI>
<A HREF="#E11E101" >Syntax</A>
<LI>
<A HREF="#E11E102" >Returns</A>
<LI>
<A HREF="#E11E103" >Diagnostics</A>
<LI>
<A HREF="#E11E104" >Comments</A>
<LI>
<A HREF="#E11E105" >Code Example</A>
<LI>
<A HREF="#E11E106" >Related Functions</A></UL></UL></UL>
<HR ALIGN=CENTER>
<A NAME="E74E2"></A>
<H2>
<FONT FACE="Arial"><B>SQLBrowseConnect (ODBC 1.0, Level 2)</B><A NAME="I2"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLBrowseConnect</B> supports an iterative method of discovering and enumerating the attributes and attribute values required to connect to a data source. Each call to <B>SQLBrowseConnect</B> returns successive levels of attributes and attribute values. When all levels have been enumerated, a connection to the data source is completed and a complete connection string is returned by <B>SQLBrowseConnect</B>. A return code of SQL_SUCCESS or SQL_SUCCESS_WITH_INFO indicates that all connection information has been specified and the application is now connected to the data source.<!-- -->
</BLOCKQUOTE>
<A NAME="E11E79"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLBrowseConnect</B>(<I>hdbc</I>, <I>szConnStrIn</I>, <I>cbConnStrIn</I>, <I>szConnStrOut</I>, <I>cbConnStrOutMax</I>, <I>pcbConnStrOut</I>)<A NAME="I3"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLBrowseConnect</B> function accepts the following arguments:
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E285"></A>
<P>Argument
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E285"></A>
<P>Use
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E285"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>HDBC
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E286"></A>
<P><I>hdbc</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E286"></A>
<P>Input
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E286"></A>
<P>Connection handle.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR * 
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E287"></A>
<P><I>szConnStrIn</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E287"></A>
<P>Input
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E287"></A>
<P>Browse request connection string (see &quot;szConnStrIn Argument&quot; in &quot;Comments&quot;).</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E288"></A>
<P><I>cbConnStrIn</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E288"></A>
<P>Input
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E288"></A>
<P>Length of <I>szConnStrIn</I>.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E289"></A>
<P><I>szConnStrOut</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E289"></A>
<P>Output
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E289"></A>
<P>Pointer to storage for the browse result connection string (see &quot;szConnStrOut Argument&quot; in &quot;Comments&quot;).</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E290"></A>
<P><I>cbConnStrOutM</I><I>ax</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E290"></A>
<P>Input
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E290"></A>
<P>Maximum length of the <I>szConnStrOut</I> buffer.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E291"></A>
<P><I>pcbConnStrOut</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E291"></A>
<P>Output
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E291"></A>
<P>The total number of bytes (excluding the null termination byte) available to return in <I>szConnStrOut</I>. If the number of bytes available to return is greater than or equal to <I>cbConnStrOutMax</I>, the connection string in <I>szConnStrOut</I> is truncated to <I>cbConnStrOutMax </I>&#150; 1 bytes.</TD></TR></TABLE>
<A NAME="E11E80"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I4"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E81"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I5"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLBrowseConnect</B> returns SQL_ERROR, SQL_SUCCESS_WITH_INFO, or SQL_NEED_DATA, an associated SQLSTATE value may be obtained by calling <B>SQLError</B>. The following table lists the SQLSTATE values commonly returned by <B>SQLBrowseConnect </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=100 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E292"></A>
<P>Error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E292"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E293"></A>
<P>General warning
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E293"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01004
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E294"></A>
<P>Data truncated
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E294"></A>
<P>The buffer <I>szConnStrOut</I> was not large enough to return entire browse result connection string, so the string was truncated. The argument <I>pcbConnStrOut</I> contains the length of the untruncated browse result connection string. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01S00
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E295"></A>
<P>Invalid connection string attribute
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E295"></A>
<P>An invalid attribute keyword was specified in the browse request connection string (<I>szConnStrIn</I>). (Function returns SQL_NEED_DATA.)
<BLOCKQUOTE>
<P>An attribute keyword was specified in the browse request connection string (<I>szConnStrIn</I>) that does not apply to the current connection level. (Function returns SQL_NEED_DATA.)</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>08001
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E296"></A>
<P>Unable to connect to data source
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E296"></A>
<P>The driver was unable to establish a connection with the data source.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>08002
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E297"></A>
<P>Connection in use
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E297"></A>
<P>(DM) The specified <I>hdbc</I> had already been used to establish a connection with a data source and the connection was open.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>08004
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E298"></A>
<P>Data source rejected establishment of connection
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E298"></A>
<P>The data source rejected the establishment of the connection for implementation defined reasons.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>08S01
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E299"></A>
<P>Communication link failure
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E299"></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=100 VALIGN=top >
<BLOCKQUOTE>
<P>28000
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E300"></A>
<P>Invalid authorization specification
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E300"></A>
<P>Either the user identifier or the authorization string or both as specified in the browse request connection string (<I>szConnStrIn</I>) violated restrictions defined by the data source.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E301"></A>
<P>Driver does not support this function
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E301"></A>
<P>(DM) The driver corresponding to the specified data source name does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM002
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E302"></A>
<P>Data source not found and no default driver specified
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E302"></A>
<P>(DM) The data source name specified in the browse request connection string (<I>szConnStrIn</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=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM003
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E303"></A>
<P>Specified driver could not be loaded
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E303"></A>
<P>(DM) The driver listed in the data source specification in the ODBC.INI file or registry, or specified by the <B>DRIVER</B> keyword was not found or could not be loaded for some other reason.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM004
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E304"></A>
<P>Driver&#146;s SQLAllocEnv failed
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E304"></A>
<P>(DM) During <B>SQLBrowseConnect</B>, the Driver Manager called the driver&#146;s <B>SQLAllocEnv</B> function and the driver returned an error.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM005
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E305"></A>
<P>Driver&#146;s SQLAllocConnect failed
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E305"></A>
<P>(DM) During <B>SQLBrowseConnect</B>, the Driver Manager called the driver&#146;s <B>SQLAllocConnect</B> function and the driver returned an error.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM006
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E306"></A>
<P>Driver&#146;s SQLSetConnectOption failed
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E306"></A>
<P>(DM) During <B>SQLBrowseConnect</B>, the Driver Manager called the driver&#146;s <B>SQLSetConnectOption</B> function and the driver returned an error.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM009
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E307"></A>
<P>Unable to load translation DLL
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E307"></A>
<P>The driver was unable to load the translation DLL that was specified for the data source or for the connection.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM010
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E308"></A>
<P>Data source name too long
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E308"></A>
<P>(DM) The attribute value for the DSN keyword was longer than SQL_MAX_DSN_LENGTH characters.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM011
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E309"></A>
<P>Driver name too long
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E309"></A>
<P>(DM) The attribute value for the DRIVER keyword was longer than 255 characters.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM012
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E310"></A>
<P>DRIVER keyword syntax error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E310"></A>
<P>(DM) The keyword-value pair for the DRIVER keyword contained a syntax error.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E311"></A>
<P>General error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E311"></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=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E312"></A>
<P>Memory allocation failure
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E312"></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=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1090
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E313"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E313"></A>
<P>(DM) The value specified for argument <I>cbConnStrIn</I> was less than 0 and was not equal to SQL_NTS.
<BLOCKQUOTE>
<P>(DM) The value specified for argument <I>cbConnStrOutMax</I> was less than 0.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1T00
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E314"></A>
<P>Timeout expired
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E314"></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="E11E82"></A>
<H3>
<FONT FACE="Arial">Comments</FONT></H3>
<BLOCKQUOTE>
<A NAME="E12E40"></A>
<H4>
<FONT>szConnStrIn Argument<A NAME="I6"></A><A NAME="I7"></A><A NAME="I8"></A><A NAME="I9"></A><A NAME="I10"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>A browse request connection string has the following syntax:<A NAME="I11"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><I>connection-string</I> ::= <I>attribute</I>[;] | <I>attribute</I>; <I>connection-string</I>
<BR><I>attribute</I> ::= <I>attribute-keyword</I>=<I>attribute-value</I> |  DRIVER={<I>attribute-value</I>}
<BR>(The braces are literal; the application must specify them.)
<BR><I>attribute-keyword</I> ::= DSN | UID | PWD | <I>driver-defined-attribute-keyword</I>
<BR><I>attribute-value</I> ::= <I>character-string</I>
<BR><I>driver-defined-attribute-keyword</I> ::= <I>identifier</I><A NAME="I12"></A><A NAME="I13"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>where <I>character-string</I> has zero or more characters; <I>identifier</I> has one or more characters; <I>attribute-keyword</I> is case insensitive; <I>attribute-value</I> may be case sensitive; and the value of the <B>DSN</B> keyword does not consist solely of blanks. Because of connection string and initialization file grammar, keywords and attribute values that contain the characters <B>[]{}(),;?*=!@</B> should be avoided. Because of the registry grammar, keywords and data source names cannot contain the backslash (\) character.<A NAME="I14"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note The <B>DRIVER</B> keyword was introduced in ODBC 2.0 and is not supported by ODBC 1.0 drivers.<A NAME="I15"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If any keywords are repeated in the browse request connection string, the driver uses the value associated with the first occurrence of the keyword. If the <B>DSN</B> and <B>DRIVER</B> keywords are included in the same browse request connection string, the Driver Manager and driver use whichever keyword appears first.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E41"></A>
<H4>
<FONT>szConnStrOut Argument<A NAME="I16"></A><A NAME="I17"></A><A NAME="I18"></A><A NAME="I19"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The browse result connection string is a list of connection attributes. A connection attribute consists of an attribute keyword and a corresponding attribute value. The browse result connection string has the following syntax:<A NAME="I20"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><I>connection-string</I> ::= <I>attribute</I>[;] | <I>attribute</I>;<I> connection-string</I>
<BR><I>attribute</I> ::= [*]<I>attribute-keyword=attribute-value</I>
<BR><I>attribute-keyword</I> ::= <I>ODBC-attribute-keyword</I> |
<BR>   <I>driver-defined-attribute-keyword</I>
<BR><I>ODBC-attribute-keyword</I> = {UID | PWD}[:<I>localized-identifier</I>]
<BR><I>driver-defined-attribute-keyword</I> ::=<I> identifer</I>[:<I>localized-identifier</I>]
<BR><I>attribute-value</I> ::= {<I>attribute-value-list</I>} | ?
<BR>(The braces are literal; they are returned by the driver.)
<BR><I>attribute-value-list</I> ::= <I>character-string</I> |
<BR>   <I>character-string</I>, <I>attribute-value-list</I><A NAME="I21"></A><A NAME="I22"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>where <I>character-string</I> has zero or more characters; <I>identifier</I> and <I>localized-identifier</I> have one or more characters;<I>attribute-keyword</I> is case insensitive; and <I>attribute-value</I> may be case sensitive. Because of connection string and initialization file grammar, keywords, localized identifiers, and attribute values that contain the characters <B>[]{}(),;?*=!@</B> should be avoided. Because of the registry grammar, keywords and data source names cannot contain the backslash (\) character.<A NAME="I23"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The browse result connection string syntax is used according to the following semantic rules:<A NAME="I24"></A><A NAME="I25"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>If an asterisk (*) precedes an <I>attribute-keyword</I>, the <I>attribute</I> is optional, and may be omitted in the next call to <B>SQLBrowseConnect</B>.<A NAME="I26"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The attribute keywords <B>UID</B> and <B>PWD</B> have the same meaning as defined in <B>SQLDriverConnect</B>.<A NAME="I27"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>A <I>driver-defined-attribute-keyword</I> names the kind of attribute for which an attribute value may be supplied. For example, it might be <B>SERVER</B>, <B>DATABASE</B>, <B>HOST</B>, or <B>DBMS</B>.<A NAME="I28"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><I>ODBC-attribute-keywords</I> and <I>driver-defined-attribute-keywords</I> include a localized or user-friendly version of the keyword. This might be used by applications as a label in a dialog box. However, <B>UID</B>, <B>PWD</B>, or the <I>identifier</I> alone must be used when passing a browse request string to the driver.<A NAME="I29"></A><A NAME="I30"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The {<I>attribute-value-list</I>} is an enumeration of actual values valid for the corresponding <I>attribute-keyword</I>. Note that the braces ({}) do not indicate a list of choices; they are returned by the driver. For example, it might be a list of server names or a list of database names.<A NAME="I31"></A><A NAME="I32"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the <I>attribute-value</I> is a single question mark (?), a single value corresponds to the <I>attribute-keyword</I>. For example, UID=JohnS; PWD=Sesame.<A NAME="I33"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Each call to <B>SQLBrowseConnect</B> returns only the information required to satisfy the next level of the connection process. The driver associates state information with the connection handle so that the context can always be determined on each call.
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<A NAME="E12E42"></A>
<H4>
<FONT>Using SQLBrowseConnect<A NAME="I34"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>SQLBrowseConnect</B> requires an allocated <I>hdbc</I>. The Driver Manager loads the driver that was specified in or that corresponds to the data source name specified in the initial browse request connection string; for information on when this occurs, see the &quot;Comments&quot; section in <B>SQLConnect</B>. It may establish a connection with the data source during the browsing process. If <B>SQLBrowseConnect</B> returns SQL_ERROR, outstanding connections are terminated and the <I>hdbc</I> is returned to an unconnected state.<A NAME="I35"></A><A NAME="I36"></A><A NAME="I37"></A><A NAME="I38"></A><A NAME="I39"></A><A NAME="I40"></A><A NAME="I41"></A><A NAME="I42"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>When <B>SQLBrowseConnect</B> is called for the first time on an <I>hdbc</I>, the browse request connection string must contain the <B>DSN</B> keyword or the <B>DRIVER</B> keyword. If the browse request connection string contains the <B>DSN</B> keyword, the Driver Manager locates a corresponding data source specification in the ODBC.INI file or registry:<A NAME="I43"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>If the Driver Manager finds the corresponding data source specification, it loads the associated driver DLL; the driver can retrieve information about the data source from the ODBC.INI file or registry.<A NAME="I44"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the Driver Manager cannot find the corresponding data source specification, it locates the default data source specification and loads the associated driver DLL; the driver can retrieve information about the default data source from the ODBC.INI file or registry.<A NAME="I45"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the Driver Manager cannot find the corresponding data source specification and there is no default data source specification, it returns SQL_ERROR with SQLSTATE IM002 (Data source not found and no default driver specified).<A NAME="I46"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>If the browse request connection string contains the <B>DRIVER</B> keyword, the Driver Manager loads the specified driver; it does not attempt to locate a data source in the ODBC.INI file or registry. Because the <B>DRIVER</B> keyword does not use information from the ODBC.INI file or registry, the driver must define enough keywords so that a driver can connect to a data source using only the information in the browse request connection strings.<A NAME="I47"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>On each call to <B>SQLBrowseConnect</B>, the application specifies the connection attribute values in the browse request connection string. The driver returns successive levels of attributes and attribute values in the browse result connection string; it returns SQL_NEED_DATA as long as there are connection attributes that have not yet been enumerated in the browse request connection string. The application uses the contents of the browse result connection string to build the browse request connection string for the next call to <B>SQLBrowseConnect</B>. Note that the application cannot use the contents of previous browse result connection strings when building the current browse request connection string; that is, it cannot specify different values for attributes set in previous levels.<A NAME="I48"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>When all levels of connection and their associated attributes have been enumerated, the driver returns SQL_SUCCESS, the connection to the data source is complete, and a complete connection string is returned to the application. The connection string is suitable to use in conjunction with <B>SQLDriverConnect</B> with the SQL_DRIVER_NOPROMPT option to establish another connection.<A NAME="I49"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>SQLBrowseConnect</B> also returns SQL_NEED_DATA if there are recoverable, nonfatal errors during the browse process, for example, an invalid password supplied by the application or an invalid attribute keyword supplied by the application. When SQL_NEED_DATA is returned and the browse result connection string is unchanged, an error has occurred and the application must call <B>SQLError</B> to return the SQLSTATE for browse-time errors. This permits the application to correct the attribute and continue the browse.<A NAME="I50"></A><A NAME="I51"></A><A NAME="I52"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application may terminate the browse process at any time by calling <B>SQLDisconnect</B>. The driver will terminate any outstanding connections and return the <I>hdbc</I> to an unconnected state.<A NAME="I53"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information, see &quot;Connection Browsing With SQLBrowseConnect&quot; in Chapter 5, &quot;Establishing Connections.&quot;<A NAME="I54"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If a driver supports <B>SQLBrowseConnect</B>, the driver keyword section of the ODBC.INF file for the driver must contain the <B>ConnectFunctions</B> keyword with the third character set to &quot;Y&quot;.
</BLOCKQUOTE>
<A NAME="E11E83"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I55"></A></FONT></H3>
<BLOCKQUOTE>
<P><A NAME="I56"></A>In the following example, an application calls <B>SQLBrowseConnect</B> repeatedly. Each time <B>SQLBrowseConnect</B> returns SQL_NEED_DATA, it passes back information about the data it needs in <I>szConnStrOut</I>. The application passes <I>szConnStrOut</I> to its routine <B>GetUserInput</B> (not shown). <B>GetUserInput</B> parses the information, builds and displays a dialog box, and returns the information entered by the user in <I>szConnStrIn</I>. The application passes the user&#146;s information to the driver in the next call to <B>SQLBrowseConnect</B>. After the application has provided all necessary information for the driver to connect to the data source, <B>SQLBrowseConnect</B> returns SQL_SUCCESS and the application proceeds.<A NAME="I57"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For example, to connect to the data source My Source, the following actions might occur. First, the application passes the following string to <B>SQLBrowseConnect</B>:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">&quot;DSN=My Source&quot;<A NAME="I58"></A></FONT></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>The Driver Manager loads the driver associated with the data source My Source. It then calls the driver&#146;s <B>SQLBrowseConnect</B> function with the same arguments it received from the application. The driver returns the following string in <I>szConnStrOut</I>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">&quot;HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?&quot;<A NAME="I59"></A></FONT></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>The application passes this string to its <B>GetUserInput</B> routine, which builds a dialog box that asks the user to select the red, blue, or green server, and to enter a user ID and password. The routine passes the following user-specified information back in <I>szConnStrIn</I>, which the application passes to <B>SQLBrowseConnect</B>:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">&quot;HOST=red;UID=Smith;PWD=Sesame&quot;<A NAME="I60"></A></FONT></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>SQLBrowseConnect</B> uses this information to connect to the red server as Smith with the password Sesame, then returns the following string in <I>szConnStrOut</I>:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">&quot;*DATABASE:Database={master,model,empdata}&quot;<A NAME="I61"></A></FONT></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>The application passes this string to its <B>GetUserInput</B> routine, which builds a dialog box that asks the user to select a database. The user selects empdata and the application calls <B>SQLBrowseConnect</B> a final time with the string:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">&quot;DATABASE=empdata&quot;<A NAME="I62"></A></FONT></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>This is the final piece of information the driver needs to connect to the data source; <B>SQLBrowseConnect</B> returns SQL_SUCCESS and <I>szConnStrOut</I> contains the completed connection string:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">&quot;DSN=My Source;HOST=red;UID=Smith;PWD=Sesame;DATABASE=empdata&quot;
#define BRWS_LEN 100
HENV    henv;
HDBC    hdbc;
HSTMT   hstmt;
RETCODE retcode;
UCHAR   szConnStrIn[BRWS_LEN], szConnStrOut[BRWS_LEN];
SWORD   cbConnStrOut;
retcode = SQLAllocEnv(&amp;henv);                 /* Environment handle */
if (retcode == SQL_SUCCESS) {
   retcode = SQLAllocConnect(henv, &amp;hdbc);    /* Connection handle  */
   if (retcode == SQL_SUCCESS) {
      /* Call SQLBrowseConnect until it returns a value other than */
      /* SQL_NEED_DATA (pass the data source name the first time). */
      /* If SQL_NEED_DATA is returned, call GetUserInput (not      */
      /* shown) to build a dialog from the values in szConnStrOut. */
      /* The user-supplied values are returned in szConnStrIn,     */
      /* which is passed in the next call to SQLBrowseConnect.     */
      lstrcpy(szConnStrIn, &quot;DSN=MyServer&quot;);
      do {
         retcode = SQLBrowseConnect(hstmt, szConnStrIn, SQL_NTS,
                               szConnStrOut, BRWS_LEN, &amp;cbConnStrOut)
         if (retcode == SQL_NEED_DATA)
            GetUserInput(szConnStrOut, szConnStrIn);
      } while (retcode == SQL_NEED_DATA);
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){
         /* Process data after successful connection */
         retcode = SQLAllocStmt(hdbc, &amp;hstmt);
         if (retcode == SQL_SUCCESS) {
            ...;
            ...;
            ...;
            SQLFreeStmt(hstmt, SQL_DROP);
         }
         SQLDisconnect(hdbc);
      }
   }
   SQLFreeConnect(hdbc);
}
SQLFreeEnv(henv);</FONT></PRE></BLOCKQUOTE>
<A NAME="E11E84"></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="E7E315"></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="E7E316"></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="E7E317"></A>
<P><B>SQLConnect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Disconnecting from a data source
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E318"></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="E7E319"></A>
<P><B>SQLDriverConnect</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning driver descriptions and attributes
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E320"></A>
<P><B>SQLDrivers</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="E7E321"></A>
<P><B>SQLFreeConnect</B></TD></TR></TABLE><A NAME="E10E68"></A>
<H2>
<FONT FACE="Arial"><B>SQLCance</B><B>l (ODBC 1.0, Core)</B><A NAME="I63"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLCancel</B> cancels the processing on an <I>hstmt</I>.
</BLOCKQUOTE>
<A NAME="E11E85"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLCancel</B>(<I>hstmt</I>)<A NAME="I64"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLCancel</B> function accepts the following argument.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E322"></A>
<P>Argument
</TD><TD WIDTH=113 VALIGN=top >
<A NAME="E7E322"></A>
<P>Use
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E322"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E323"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=113 VALIGN=top >
<A NAME="E7E323"></A>
<P>Input
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E323"></A>
<P>Statement handle.</TD></TR></TABLE>
<A NAME="E11E86"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I65"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E87"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I66"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLCancel</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>SQLCancel </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=100 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=146 VALIGN=top >
<A NAME="E7E324"></A>
<P>Error
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E324"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=146 VALIGN=top >
<A NAME="E7E325"></A>
<P>General warning
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E325"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>70100
</BLOCKQUOTE></TD>
<TD WIDTH=146 VALIGN=top >
<A NAME="E7E326"></A>
<P>Operation aborted
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E326"></A>
<P>The data source was unable to process the cancel request.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=146 VALIGN=top >
<A NAME="E7E327"></A>
<P>Driver does not support this function
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E327"></A>
<P>(DM) The driver associated with the <I>hstmt</I> does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=146 VALIGN=top >
<A NAME="E7E328"></A>
<P>General error
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E328"></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=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=146 VALIGN=top >
<A NAME="E7E329"></A>
<P>Memory allocation failure
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E329"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD></TR></TABLE>
<A NAME="E11E88"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I67"></A><A NAME="I68"></A></FONT></H3>
<BLOCKQUOTE>
<P><B>SQLCancel</B> can cancel the following types of processing on an <I>hstmt</I>:<A NAME="I69"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>A function running asynchronously on the <I>hstmt</I>.<A NAME="I70"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>A function on an <I>hstmt</I> that needs data.<A NAME="I71"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>A function running on the <I>hstmt</I> on another thread.<A NAME="I72"></A><A NAME="I73"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>If an application calls <B>SQLCancel</B> when no processing is being done on the <I>hstmt</I>, <B>SQLCancel</B> has the same effect as <B>SQLFreeStmt</B> with the SQL_CLOSE option; this behavior is defined only for completeness and applications should call <B>SQLFreeStmt</B> to close cursors.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E43"></A>
<H4>
<FONT>Canceling Asynchronous Processing<A NAME="I74"></A><A NAME="I75"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>After an application calls a function asynchronously, it calls the function repeatedly to determine whether it has finished processing. If the function is still processing, it returns SQL_STILL_EXECUTING. If the function has finished processing, it returns a different code.<A NAME="I76"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>After any call to the function that returns SQL_STILL_EXECUTING, an application can call <B>SQLCancel</B> to cancel the function. If the cancel request is successful, the driver returns SQL_SUCCESS. This message does not indicate that the function was actually canceled; it indicates that the cancel request was processed. When or if the function is actually canceled is driver- and data source&#150;dependent. The application must continue to call the original function until the return code is not SQL_STILL_EXECUTING. If the function was successfully canceled, the return code is SQL_ERROR and SQLSTATE S1008 (Operation canceled). If the function completed its normal processing, the return code is SQL_SUCCESS or SQL_SUCCESS_WITH_INFO if the function succeeded or SQL_ERROR and a SQLSTATE other than S1008 (Operation canceled) if the function failed.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E44"></A>
<H4>
<FONT>Canceling Functions that Need Data<A NAME="I77"></A><A NAME="I78"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>After <B>SQLExecute</B> or <B>SQLExecDirect</B> returns SQL_NEED_DATA and before data has been sent for all data-at-execution parameters, an application can call <B>SQLCancel</B> to cancel the statement execution. After the statement has been canceled, the application can call <B>SQLExecute</B> or <B>SQLExecDirect</B> again. For more information, see <B>SQLBindParameter</B>.<A NAME="I79"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>After <B>SQLSetPos</B> returns SQL_NEED_DATA and before data has been sent for all data-at-execution columns, an application can call <B>SQLCancel</B> to cancel the operation. After the operation has been canceled, the application can call <B>SQLSetPos</B> again; canceling does not affect the cursor state or the current cursor position. For more information, see <B>SQLSetPos</B>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E45"></A>
<H4>
<FONT>Canceling Functions in Multithreaded Applications<A NAME="I80"></A><A NAME="I81"></A><A NAME="I82"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>In a multithreaded application, the application can cancel a function that is running synchronously on an <I>hstmt</I>. To cancel the function, the application calls <B>SQLCancel</B> with the same <I>hstmt</I> as that used by the target function, but on a different thread. As in canceling a function running asynchronously, the return code of the <B>SQLCancel</B> only indicates whether the driver processed the request successfully. The return code of the original function indicates whether it completed normally or was canceled.
</BLOCKQUOTE>
<A NAME="E11E89"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800 >
<TR>
<TD WIDTH=260 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=193 VALIGN=top >
<A NAME="E7E330"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=260 VALIGN=top >
<BLOCKQUOTE>
<P>Assigning storage for a parameter
</BLOCKQUOTE></TD>
<TD WIDTH=193 VALIGN=top >
<A NAME="E7E331"></A>
<P><B>SQLBindParameter</B></TD>
</TR>
<TR>
<TD WIDTH=260 VALIGN=top >
<BLOCKQUOTE>
<P>Executing an SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=193 VALIGN=top >
<A NAME="E7E332"></A>
<P><B>SQLExecDirect</B></TD>
</TR>
<TR>
<TD WIDTH=260 VALIGN=top >
<BLOCKQUOTE>
<P>Executing a prepared SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=193 VALIGN=top >
<A NAME="E7E333"></A>
<P><B>SQLExecute</B></TD>
</TR>
<TR>
<TD WIDTH=260 VALIGN=top >
<BLOCKQUOTE>
<P>Freeing a statement handle
</BLOCKQUOTE></TD>
<TD WIDTH=193 VALIGN=top >
<A NAME="E7E334"></A>
<P><B>SQLFreeStmt</B></TD>
</TR>
<TR>
<TD WIDTH=260 VALIGN=top >
<BLOCKQUOTE>
<P>Positioning the cursor in a rowset
</BLOCKQUOTE></TD>
<TD WIDTH=193 VALIGN=top >
<A NAME="E7E335"></A>
<P><B>SQLSetPos</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=260 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the next parameter to send data for
</BLOCKQUOTE></TD>
<TD WIDTH=193 VALIGN=top >
<A NAME="E7E336"></A>
<P><B>SQLParamData</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=260 VALIGN=top >
<BLOCKQUOTE>
<P>Sending parameter data at execution time
</BLOCKQUOTE></TD>
<TD WIDTH=193 VALIGN=top >
<A NAME="E7E337"></A>
<P><B>SQLPutData</B> (extension)</TD></TR></TABLE><A NAME="E10E69"></A>
<H2>
<FONT FACE="Arial"><B>SQLColAttributes (ODBC 1.0, Core)</B><A NAME="I83"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLColAttributes</B> returns descriptor information for a column in a result set; it cannot be used to return information about the bookmark column (column 0). Descriptor information is returned as a character string, a 32-bit descriptor-dependent value, or an integer value.
</BLOCKQUOTE>
<A NAME="E11E90"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE<A NAME="I84"></A> <B>SQLColAttributes</B>(<I>hstmt</I>, <I>icol</I>, <I>fDescType</I>, <I>rgbDesc</I>, <I>cbDescMax</I>, <I>pcbDesc</I>, <I>pfDesc</I>)<A NAME="I85"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLColAttributes</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=82 VALIGN=top >
<A NAME="E7E338"></A>
<P>Argument
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E338"></A>
<P>Use
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E338"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=82 VALIGN=top >
<A NAME="E7E339"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E339"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E339"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=82 VALIGN=top >
<A NAME="E7E340"></A>
<P><I>icol</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E340"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E340"></A>
<P>Column number of result data, ordered sequentially from left to right, starting 
<BR>at 1. Columns may be described in any order.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=82 VALIGN=top >
<A NAME="E7E341"></A>
<P><I>fDescType</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E341"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E341"></A>
<P>A valid descriptor type (see &quot;Comments&quot;).</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>PTR
</BLOCKQUOTE></TD>
<TD WIDTH=82 VALIGN=top >
<A NAME="E7E342"></A>
<P><I>rgbDesc</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E342"></A>
<P>Output
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E342"></A>
<P>Pointer to storage for the descriptor information. The format of the descriptor information returned depends on the <I>fDescType</I>.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=82 VALIGN=top >
<A NAME="E7E343"></A>
<P><I>cbDescMax</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E343"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E343"></A>
<P>Maximum length of the <I>rgbDesc</I> buffer.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=82 VALIGN=top >
<A NAME="E7E344"></A>
<P><I>pcbDesc</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E344"></A>
<P>Output
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E344"></A>
<P>Total number of bytes (excluding the null termination byte for character data) available to return in <I>rgbDesc</I>.
<BLOCKQUOTE>
<P>For character data, if the number of bytes available to return is greater than or equal to <I>cbDescMax</I>, the descriptor information in <I>rgbDesc</I> is truncated to <I>cbDescMax </I>&#150; 1 bytes and is null-terminated by the driver.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For all other types of data, the value of <I>cbValueMax</I> is ignored and the driver assumes the size of <I>rgbValue</I> is 32 bits.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SDWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=82 VALIGN=top >
<A NAME="E7E345"></A>
<P><I>pfDesc</I>
</TD><TD WIDTH=64 VALIGN=top >
<A NAME="E7E345"></A>
<P>Output
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E345"></A>
<P>Pointer to an integer value to contain descriptor information for numeric descriptor types, such as SQL_COLUMN_LENGTH.</TD></TR></TABLE>
<A NAME="E11E91"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I86"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E92"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I87"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLColAttributes</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>SQLColAttributes </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=153 VALIGN=top >
<A NAME="E7E346"></A>
<P>Error
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E346"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E347"></A>
<P>General warning
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E347"></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=153 VALIGN=top >
<A NAME="E7E348"></A>
<P>Data truncated
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E348"></A>
<P>The buffer <I>rgbDesc</I> was not large enough to return the entire string value, so the string value was truncated. The argument <I>pcbDesc</I> contains the length of the untruncated string value. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>24000
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E349"></A>
<P>Invalid cursor state
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E349"></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=153 VALIGN=top >
<A NAME="E7E350"></A>
<P>Driver does not support this function
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E350"></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=153 VALIGN=top >
<A NAME="E7E351"></A>
<P>General error
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E351"></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=153 VALIGN=top >
<A NAME="E7E352"></A>
<P>Memory allocation failure
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E352"></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=153 VALIGN=top >
<A NAME="E7E353"></A>
<P>Invalid column number
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E353"></A>
<P>(DM) The value specified for the argument <I>icol</I> was 0 and the argument <I>fDescType</I> was not SQL_COLUMN_COUNT.
<BLOCKQUOTE>
<P>The value specified for the argument <I>icol</I> was greater than the number of columns in the result set and the argument <I>fDescType</I> was not SQL_COLUMN_COUNT.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1008
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E354"></A>
<P>Operation canceled
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E354"></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=153 VALIGN=top >
<A NAME="E7E355"></A>
<P>Function sequence error
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E355"></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=153 VALIGN=top >
<A NAME="E7E356"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E356"></A>
<P>(DM) The value specified for the argument <I>cbDescMax</I> was less than 0.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1091
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E357"></A>
<P>Descriptor type out of range
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E357"></A>
<P>(DM) The value specified for the argument <I>fDescType</I> was in the block of numbers reserved for ODBC descriptor types but was not valid for the version of ODBC supported by the driver (see &quot;Comments&quot;).</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1C00
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E358"></A>
<P>Driver not capable
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E358"></A>
<P>The value specified for the argument <I>fDescType</I> was in the range of numbers reserved for driver-specific descriptor types but was not supported by the driver.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1T00
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E359"></A>
<P>Timeout expired
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E359"></A>
<P>The timeout period expired before the data source returned the requested information. The timeout period is set through <B>SQLSetStmtOption</B>, SQL_QUERY_TIMEOUT.</TD></TR></TABLE><A NAME="I88"></A>
<BLOCKQUOTE>
<P><B>SQLColAttributes</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="E11E93"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I89"></A><A NAME="I90"></A><A NAME="I91"></A><A NAME="I92"></A><A NAME="I93"></A></FONT></H3>
<BLOCKQUOTE>
<P><B>SQLColAttributes</B> returns information either in <I>pfDesc</I> or in <I>rgbDesc</I>. Integer information is returned in <I>pfDesc</I> as a 32-bit, signed value; all other formats of information are returned in <I>rgbDesc</I>. When information is returned in <I>pfDesc</I>, the driver ignores <I>rgbDesc</I>, <I>cbDescMax</I>, and <I>pcbDesc</I>. When information is returned in <I>rgbDesc</I>, the driver ignores <I>pfDesc</I>.<A NAME="I94"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The currently defined descriptor types, the version of ODBC in which they were introduced, and the arguments in which information is returned for them are shown below; it is expected that more descriptor types will be defined to take advantage of different data sources. Descriptor types from 0 to 999 are reserved by ODBC; driver developers must reserve values greater than or equal to SQL_COLUMN_DRIVER_START for driver-specific use.<A NAME="I95"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>A driver must return a value for each of the descriptor types defined in the following table. If a descriptor type does not apply to a driver or data source, then, unless otherwise stated, the driver returns 0 in <I>pcbDesc</I> or an empty string in <I>rgbDesc</I>.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P><B>fDescType</B>
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E360"></A>
<P>Information
<BR><B>returned in</B>
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E361"></A>
<P>Description<A NAME="I96"></A></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_AUTO_INCREMENT(ODBC 1.0)
<BR>
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>pfDesc
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E362"></A>
<P>TRUE if the column is autoincrement.
<BLOCKQUOTE>
<P>FALSE if the column is not autoincrement or is not numeric.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Auto increment is valid for numeric data type columns only. An application can insert values into an autoincrement column, but cannot update values in the column.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_CASE_SENSITIVE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E363"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E363"></A>
<P>TRUE if the column is treated as case sensitive for collations and comparisons.
<BLOCKQUOTE>
<P>FALSE if the column is not treated as case sensitive for collations and comparisons or is noncharacter.<A NAME="I97"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_COUNT
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E364"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E364"></A>
<P>Number of columns available in the result set. The icol argument is ignored.<A NAME="I98"></A></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_DISPLAY_SIZE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E365"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E365"></A>
<P>Maximum number of characters required to display data from the column. For more information on display size, see &quot;Precision, Scale, Length, and Display Size&quot; in Appendix D, &quot;Data Types.&quot;<A NAME="I99"></A><A NAME="I100"></A><A NAME="I101"></A><A NAME="I102"></A><A NAME="I103"></A></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_LABEL
<BR>(ODBC 2.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E366"></A>
<P>rgbDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E366"></A>
<P>The column label or title. For example, a column named EmpName might be labeled Employee Name.
<BLOCKQUOTE>
<P>If a column does not have a label, the column name is returned. If the column is unlabeled and unnamed, an empty string is returned.<A NAME="I104"></A><A NAME="I105"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_LENGTH
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E367"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E367"></A>
<P>The length in bytes of data transferred on an <B>SQLGetData</B> or <B>SQLFetch</B> operation if SQL_C_DEFAULT is specified. For numeric data, this size may be different than the size of the data stored on the data source. For more length information, see &quot;Precision, Scale, Length, and Display Size&quot; in Appendix D, &quot;Data Types.&quot;<A NAME="I106"></A></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_MONEY
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E368"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E368"></A>
<P>TRUE if the column is money data type.
<BLOCKQUOTE>
<P>FALSE if the column is not money data type.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_NAME
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E369"></A>
<P>rgbDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E369"></A>
<P>The column name.
<BLOCKQUOTE>
<P>If the column is unnamed, an empty string is returned.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_NULLABLE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E370"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E370"></A>
<P>SQL_NO_NULLS if the column does not accept NULL values.
<BLOCKQUOTE>
<P>SQL_NULLABLE if the column accepts NULL values.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NULLABLE_UNKNOWN if it is not known if the column accepts NULL values.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_OWNER_NAME
<BR>(ODBC 2.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E371"></A>
<P>rgbDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E371"></A>
<P>The owner of the table that contains the column. The returned value is implementation-defined if the column is an expression or if the column is part of a view. If the data source does not support owners or the owner name cannot be determined, an empty string is returned.<A NAME="I107"></A></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_PRECISION
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E372"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E372"></A>
<P>The precision of the column on the data source. 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=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_QUALIFIER_NAME
<BR>(ODBC 2.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E373"></A>
<P>rgbDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E373"></A>
<P>The qualifier of the table that contains the column. The returned value is implementation-defined if the column is an expression or if the column is part of a view. If the data source does not support qualifiers or the qualifier name cannot be determined, an empty string is returned.<A NAME="I108"></A></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_SCALE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E374"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E374"></A>
<P>The scale of the column on 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=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_SEARCHABLE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E375"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E375"></A>
<P>SQL_UNSEARCHABLE if the column cannot be used in a <B>WHERE</B> clause.
<BLOCKQUOTE>
<P>SQL_LIKE_ONLY if the column can be used in a <B>WHERE</B> clause only with the <B>LIKE</B> predicate.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_ALL_EXCEPT_LIKE if the column can be used in a <B>WHERE</B> clause with all comparison operators except <B>LIKE</B>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SEARCHABLE if the column can be used in a <B>WHERE</B> clause with any comparison operator.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Columns of type SQL_LONGVARCHAR and SQL_LONGVARBINARY usually return SQL_LIKE_ONLY.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_TABLE_NAME
<BR>(ODBC 2.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E376"></A>
<P>rgbDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E376"></A>
<P>The name of the table that contains the column. The returned value is implementation-defined if the column is an expression or if the column is part of a view.
<BLOCKQUOTE>
<P>If the table name cannot be determined, an empty string is returned.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_TYPE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E377"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E377"></A>
<P>SQL data type. This can be an ODBC SQL data type or a driver-specific SQL data type. For a list of valid ODBC SQL data types, 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>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_TYPE_NAME
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E378"></A>
<P>rgbDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E378"></A>
<P>Data source&#150;dependent data type name; for example, &quot;CHAR&quot;, &quot;VARCHAR&quot;, &quot;MONEY&quot;, &quot;LONG VARBINARY&quot;, or &quot;CHAR ( ) FOR BIT DATA&quot;.
<BLOCKQUOTE>
<P>If the type is unknown, an empty string is returned.<A NAME="I109"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_UNSIGNED
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E379"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E379"></A>
<P>TRUE if the column is unsigned (or not numeric).
<BLOCKQUOTE>
<P>FALSE if the column is signed.<A NAME="I110"></A><A NAME="I111"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_COLUMN_UPDATABLE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E380"></A>
<P>pfDesc
</TD><TD WIDTH=126 VALIGN=top >
<A NAME="E7E380"></A>
<P>Column is described by the values for the defined constants:
<BLOCKQUOTE>
<P>SQL_ATTR_READONLY
<BR>SQL_ATTR_WRITE
<BR>SQL_ATTR_READWRITE_UNKNOWN
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_COLUMN_UPDATABLE describes the updatability of the column in the result set. Whether a column is updatable can be based on the data type, user privileges, and the definition of the result set itself. If it is unclear whether a column is updatable, SQL_ATTR_READWRITE_UNKNOWN should be returned.</TD></TR></BLOCKQUOTE></TABLE><A NAME="I112"></A>
<BLOCKQUOTE>
<P>This function is an extensible alternative to <B>SQLDescribeCol</B>. <B>SQLDescribeCol</B> returns a fixed set of descriptor information based on ANSI-89 SQL. <B>SQLColAttributes</B> allows access to the more extensive set of descriptor information available in ANSI SQL-92 and DBMS vendor extensions.
</BLOCKQUOTE>
<A NAME="E11E94"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800 >
<TR>
<TD WIDTH=278 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=174 VALIGN=top >
<A NAME="E7E381"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=278 VALIGN=top >
<BLOCKQUOTE>
<P>Assigning storage for a column in a result set
</BLOCKQUOTE></TD>
<TD WIDTH=174 VALIGN=top >
<A NAME="E7E382"></A>
<P><B>SQLBindCol</B></TD>
</TR>
<TR>
<TD WIDTH=278 VALIGN=top >
<BLOCKQUOTE>
<P>Canceling statement processing
</BLOCKQUOTE></TD>
<TD WIDTH=174 VALIGN=top >
<A NAME="E7E383"></A>
<P><B>SQLCancel</B></TD>
</TR>
<TR>
<TD WIDTH=278 VALIGN=top >
<BLOCKQUOTE>
<P>Returning information about a column in a result set
</BLOCKQUOTE></TD>
<TD WIDTH=174 VALIGN=top >
<A NAME="E7E384"></A>
<P><B>SQLDescribeCol</B></TD>
</TR>
<TR>
<TD WIDTH=278 VALIGN=top >
<BLOCKQUOTE>
<P>Fetching a block of data or scrolling through a result set
</BLOCKQUOTE></TD>
<TD WIDTH=174 VALIGN=top >
<A NAME="E7E385"></A>
<P><B>SQLExtendedFetch</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=278 VALIGN=top >
<BLOCKQUOTE>
<P>Fetching a row of data
</BLOCKQUOTE></TD>
<TD WIDTH=174 VALIGN=top >
<A NAME="E7E386"></A>
<P><B>SQLFetch</B></TD></TR></TABLE><A NAME="E10E70"></A>
<H2>
<FONT FACE="Arial"><B>SQLColumnPrivileges (ODBC 1.0, Level 2)</B><A NAME="I113"></A><A NAME="I114"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLColumnPrivileges</B> returns a list of columns and associated privileges for the specified table. The driver returns the information as a result set on the specified <I>hstmt</I>.
</BLOCKQUOTE>
<A NAME="E11E95"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLColumnPrivileges</B>(hstmt, szTableQualifier, cbTableQualifier, szTableOwner, cbTableOwner, szTableName, cbTableName, szColumnName, cbColumnName)<A NAME="I115"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLColumnPrivileges</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="E7E387"></A>
<P>Argument
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E387"></A>
<P>Use
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E387"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E388"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E388"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E388"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E389"></A>
<P><I>szTableQualifier</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E389"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E389"></A>
<P>Table qualifier. If a driver supports qualifiers for some tables but not for others, such as when the driver retrieves data from different DBMSs, an empty string (&quot;&quot;) denotes those tables that do not have qualifiers.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E390"></A>
<P><I>cbTableQualifier</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E390"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E390"></A>
<P>Length of <I>szTableQualifier</I>.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E391"></A>
<P><I>szTableOwner</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E391"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E391"></A>
<P>Owner name. If a driver supports owners for some tables but not for others, such as when the driver retrieves data from different DBMSs, an empty string (&quot;&quot;) denotes those tables that do not have owners.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E392"></A>
<P><I>cbTableOwner</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E392"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E392"></A>
<P>Length of <I>szTableOwner</I>.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E393"></A>
<P><I>szTableName</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E393"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E393"></A>
<P>Table name.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E394"></A>
<P><I>cbTableName</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E394"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E394"></A>
<P>Length of <I>szTableName</I>.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E395"></A>
<P><I>szColumnName</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E395"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E395"></A>
<P>String search pattern for column names.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E396"></A>
<P><I>cbColumnName</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E396"></A>
<P>Input
</TD><TD WIDTH=180 VALIGN=top >
<A NAME="E7E396"></A>
<P>Length of <I>szColumnName</I>.</TD></TR></TABLE>
<A NAME="E11E96"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I116"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E97"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I117"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLColumnPrivileges</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>SQLColumnPrivileges </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="E7E397"></A>
<P>Error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E397"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E398"></A>
<P>General warning
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E398"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>08S01
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E399"></A>
<P>Communication link failure
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E399"></A>
<P>The communication link between the driver and the data source to which the driver was connected failed before the function completed processing.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>24000
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E400"></A>
<P>Invalid cursor state
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E400"></A>
<P>(DM) A cursor was open on the <I>hstmt</I> and <B>SQLFetch</B> or <B>SQLExtendedFetch</B> had been called.
<BLOCKQUOTE>
<P>A cursor was open on the <I>hstmt</I> but <B>SQLFetch</B> or <B>SQLExtendedFetch</B> had not been called.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E401"></A>
<P>Driver does not support this function
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E401"></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="E7E402"></A>
<P>General error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E402"></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="E7E403"></A>
<P>Memory allocation failure
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E403"></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>S1008
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E404"></A>
<P>Operation canceled
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E404"></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="E7E405"></A>
<P>Function sequence error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E405"></A>
<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>
<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="E7E406"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E406"></A>
<P>(DM) The value of one of the name length arguments was less than 0, but not equal to SQL_NTS.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top ><BR></TD>
<TD WIDTH=120 VALIGN=top ><BR></TD>
<TD WIDTH=240 VALIGN=top >
<BLOCKQUOTE>
<P>The value of one of the name length arguments exceeded the maximum length value for the corresponding qualifier or name (see &quot;Comments&quot;).</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1C00
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E407"></A>
<P>Driver not capable
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E407"></A>
<P>A table qualifier was specified and the driver or data source does not support qualifiers.
<BLOCKQUOTE>
<P>A table owner was specified and the driver or data source does not support owners.</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>A string search pattern was specified for the column name and the data source does not support search patterns for that argument.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options was not supported by the driver or data source.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1T00
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E408"></A>
<P>Timeout expired
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E408"></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="E11E98"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I118"></A><A NAME="I119"></A></FONT></H3>
<BLOCKQUOTE>
<P><B>SQLColumnPrivileges</B> returns the results as a standard result set, ordered by TABLE_QUALIFIER, TABLE_OWNER, TABLE_NAME, COLUMN_NAME, and PRIVILEGE. The following table lists the columns in the result set.<A NAME="I120"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note <B>SQLColumnPrivileges</B> might not return privileges for all columns. For example, a driver might not return information about privileges for pseudo-columns, such as ROWID. Applications can use any valid column, regardless of whether it is returned by <B>SQLColumnPrivileges</B>.<A NAME="I121"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The lengths of VARCHAR columns shown in the table are maximums; the actual lengths depend on the data source. To determine the actual lengths of the TABLE_QUALIFIER, TABLE_OWNER, TABLE_NAME, and COLUMN_NAME columns, an application can call <B>SQLGetInfo</B> with the SQL_MAX_QUALIFIER_NAME_LEN, SQL_MAX_OWNER_NAME_LEN, SQL_MAX_TABLE_NAME_LEN, and SQL_MAX_COLUMN_NAME_LEN options.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P><B>Column Name</B>
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E409"></A>
<P>Data Type
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E409"></A>
<P>Comments</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>TABLE_QUALIFIER
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E410"></A>
<P>Varchar(128)
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E410"></A>
<P>Table qualifier identifier; NULL if not applicable to the data source. If a driver supports qualifiers for some tables but not for others, such as when the driver retrieves data from different DBMSs, it returns an empty string (&quot;&quot;) for those tables that do not have qualifiers.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>TABLE_OWNER
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E411"></A>
<P>Varchar(128)
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E411"></A>
<P>Table owner identifier; NULL if not applicable to the data source. If a driver supports owners for some tables but not for others, such as when the driver retrieves data from different DBMSs, it returns an empty string (&quot;&quot;) for those tables that do not have owners.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>TABLE_NAME
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E412"></A>
<P>Varchar(128)
<BR>not NULL
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E413"></A>
<P>Table identifier.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>COLUMN_NAME
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E414"></A>
<P>Varchar(128)
<BR>not NULL
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E415"></A>
<P>Column identifier.<A NAME="I122"></A><A NAME="I123"></A></TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>GRANTOR
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E416"></A>
<P>Varchar(128)
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E416"></A>
<P>Identifier of the user who granted the privilege; NULL if not applicable to the data source.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>GRANTEE
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E417"></A>
<P>Varchar(128)
<BR>not NULL
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E418"></A>
<P>Identifier of the user to whom the privilege was granted.<A NAME="I124"></A></TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>PRIVILEGE
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E419"></A>
<P>Varchar(128)
<BR>not NULL
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E420"></A>
<P>Identifies the column privilege. May be one of the following or others supported by the data source when implementation-defined:
<BLOCKQUOTE>
<P>SELECT: The grantee is permitted to retrieve data for the column.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>INSERT: The grantee is permitted to provide data for the column in new rows that are inserted into the associated table.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>UPDATE: The grantee is permitted to update data in the column.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>REFERENCES: The grantee is permitted to refer to the column within a constraint (for example, a unique, referential, or table check constraint).</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>IS_GRANTABLE
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E421"></A>
<P>Varchar(3)
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E421"></A>
<P>Indicates whether the grantee is permitted to grant the privilege to other users; &quot;YES&quot;, &quot;NO&quot;, or NULL if unknown or not applicable to the data source.</TD></TR></TABLE><A NAME="I125"></A>
<BLOCKQUOTE>
<P>The <I>szColumnName</I> argument accepts a search pattern. For more information about valid search patterns, see &quot;Search Pattern Arguments&quot; earlier in this chapter.
</BLOCKQUOTE>
<A NAME="E11E99"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I126"></A></FONT></H3>
<BLOCKQUOTE>
<P>For a code example of a similar function, see <B>SQLColumns</B>.
</BLOCKQUOTE>
<A NAME="E11E100"></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="E7E422"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Assigning storage for a column in a result set
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E423"></A>
<P><B>SQLBindCol</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Canceling statement processing
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E424"></A>
<P><B>SQLCancel</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the columns in a table or tables
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E425"></A>
<P><B>SQLColumns</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Fetching a block of data or scrolling through a result set
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E426"></A>
<P><B>SQLExtendedFetch</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Fetching a row of data
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E427"></A>
<P><B>SQLFetch</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning privileges for a table or tables
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E428"></A>
<P><B>SQLTablePrivileges</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning a list of tables in a data source
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E429"></A>
<P><B>SQLTables</B> (extension)</TD></TR></TABLE><A NAME="E10E71"></A>
<H2>
<FONT FACE="Arial"><B>SQLColumns (ODBC 1.0, Level 1)</B><A NAME="I127"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLColumns</B> returns the list of column names in specified tables. The driver returns this information as a result set on the specified <I>hstmt</I>.
</BLOCKQUOTE>
<A NAME="E11E101"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLColumns</B>(<I>hstmt</I>, <I>szTableQualifier</I>, <I>cbTableQualifier</I>, <I>szTableOwner</I>, <I>cbTableOwner</I>, <I>szTableName</I>, <I>cbTableName</I>, <I>szColumnName</I>, <I>cbColumnName</I>)<A NAME="I128"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLColumns</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=93 VALIGN=top >
<A NAME="E7E430"></A>
<P>Argument
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E430"></A>
<P>Use
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E430"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E431"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E431"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E431"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E432"></A>
<P><I>szTableQualifie</I><I>r</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E432"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E432"></A>
<P>Qualifier name. If a driver supports qualifiers for some tables but not for others, such as when the driver retrieves data from different DBMSs, an empty string (&quot;&quot;) denotes those tables that do not have qualifiers.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E433"></A>
<P><I>cbTableQualifie</I><I>r</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E433"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E433"></A>
<P>Length of <I>szTableQualifier</I>.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E434"></A>
<P><I>szTableOwner</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E434"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E434"></A>
<P>String search pattern for owner names. If a driver supports owners for some tables but not for others, such as when the driver retrieves data from different DBMSs, an empty string (&quot;&quot;) denotes those tables that do not have owners.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E435"></A>
<P><I>cbTableOwner</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E435"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E435"></A>
<P>Length of <I>szTableOwner</I>.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E436"></A>
<P><I>szTableName</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E436"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E436"></A>
<P>String search pattern for table names.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E437"></A>
<P><I>cbTableName</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E437"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E437"></A>
<P>Length of <I>szTableName</I>.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E438"></A>
<P><I>szColumnName</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E438"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E438"></A>
<P>String search pattern for column names. </TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E439"></A>
<P><I>cbColumnName</I>
</TD><TD WIDTH=60 VALIGN=top >
<A NAME="E7E439"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E439"></A>
<P>Length of <I>szColumnName</I>.</TD></TR></TABLE>
<A NAME="E11E102"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I129"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E103"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I130"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLColumns</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>SQLColumns </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=133 VALIGN=top >
<A NAME="E7E440"></A>
<P>Error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E440"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E441"></A>
<P>General warning
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E441"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>08S01
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E442"></A>
<P>Communication link failure
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E442"></A>
<P>The communication link between the driver and the data source to which the driver was connected failed before the function completed processing.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>24000
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E443"></A>
<P>Invalid cursor state
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E443"></A>
<P>(DM) A cursor was open on the <I>hstmt</I> and <B>SQLFetch</B> or <B>SQLExtendedFetch</B> had been called.
<BLOCKQUOTE>
<P>A cursor was open on the <I>hstmt</I> but <B>SQLFetch</B> or <B>SQLExtendedFetch</B> had not been called.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E444"></A>
<P>Driver does not support this function
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E444"></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=133 VALIGN=top >
<A NAME="E7E445"></A>
<P>General error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E445"></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=133 VALIGN=top >
<A NAME="E7E446"></A>
<P>Memory allocation failure
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E446"></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>S1008
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E447"></A>
<P>Operation canceled
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E447"></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=133 VALIGN=top >
<A NAME="E7E448"></A>
<P>Function sequence error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E448"></A>
<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>
<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=133 VALIGN=top >
<A NAME="E7E449"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E449"></A>
<P>(DM) The value of one of the name length arguments was less than 0, but not equal to SQL_NTS.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top ><BR></TD>
<TD WIDTH=133 VALIGN=top ><BR></TD>
<TD WIDTH=226 VALIGN=top >
<BLOCKQUOTE>
<P>The value of one of the name length arguments exceeded the maximum length value for the corresponding qualifier or name. The maximum length of each qualifier or name may be obtained by calling <B>SQLGetInfo</B> with the <I>fInfoType</I> values (see &quot;Comments&quot;).</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1C00
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E450"></A>
<P>Driver not capable
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E450"></A>
<P>A table qualifier was specified and the driver or data source does not support qualifiers.
<BLOCKQUOTE>
<P>A table owner was specified and the driver or data source does not support owners.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top ><BR></TD>
<TD WIDTH=133 VALIGN=top ><BR></TD>
<TD WIDTH=226 VALIGN=top >
<BLOCKQUOTE>
<P>A string search pattern was specified for the table owner, table name, or column name and the data source does not support search patterns for one or more of those arguments.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options was not supported by the driver or data source.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1T00
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E451"></A>
<P>Timeout expired
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E451"></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="E11E104"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I131"></A><A NAME="I132"></A></FONT></H3>
<BLOCKQUOTE>
<P>This function is typically used before statement execution to retrieve information about columns for a table or tables from the data source&#146;s catalog. Note by contrast, that the functions <B>SQLColAttributes</B> and <B>SQLDescribeCol</B> describe the columns in a result set and that the function <B>SQLNumResultCols</B> returns the number of columns in a result set.<A NAME="I133"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note <B>SQLColumns</B> might not return all columns. For example, a driver might not return information about pseudo-columns, such as Oracle ROWID. Applications can use any valid column, regardless of whether it is returned by <B>SQLColumns</B>.<A NAME="I134"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>SQLColumns</B> returns the results as a standard result set, ordered by TABLE_QUALIFIER, TABLE_OWNER, and TABLE_NAME. The following table lists the columns in the result set. Additional columns beyond column 12 (REMARKS) can be defined by the driver.<A NAME="I135"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The lengths of VARCHAR columns shown in the table are maximums; the actual lengths depend on the data source. To determine the actual lengths of the TABLE_QUALIFIER, TABLE_OWNER, TABLE_NAME, and COLUMN_NAME columns, an application can call <B>SQLGetInfo</B> with the SQL_MAX_QUALIFIER_NAME_LEN, SQL_MAX_OWNER_NAME_LEN, SQL_MAX_TABLE_NAME_LEN, and SQL_MAX_COLUMN_NAME_LEN options.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P><B>Column Name</B>
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E452"></A>
<P>Data Type
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E452"></A>
<P>Comments</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>TABLE_QUALIFIER
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E453"></A>
<P>Varchar(128)
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E453"></A>
<P>Table qualifier identifier; NULL if not applicable to the data source. If a driver supports qualifiers for some tables but not for others, such as when the driver retrieves data from different DBMSs, it returns an empty string (&quot;&quot;) for those tables that do not have qualifiers.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>TABLE_OWNER
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E454"></A>
<P>Varchar(128) 
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E454"></A>
<P>Table owner identifier; NULL if not applicable to the data source. If a driver supports owners for some tables but not for others, such as when the driver retrieves data from different DBMSs, it returns an empty string (&quot;&quot;) for those tables that do not have owners.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>TABLE_NAME
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E455"></A>
<P>Varchar(128) not NULL
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E455"></A>
<P>Table identifier.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>COLUMN_NAME
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E456"></A>
<P>Varchar(128) not NULL
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E456"></A>
<P>Column identifier.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>DATA_TYPE
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E457"></A>
<P>Smallint not NULL
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E457"></A>
<P>SQL data type. This can be an ODBC SQL data type or a driver-specific SQL data type. For a list of valid ODBC SQL data types, 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>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>TYPE_NAME
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E458"></A>
<P>Varchar(128) not NULL
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E458"></A>
<P>Data source&#150;dependent data type name; for example, &quot;CHAR&quot;, &quot;VARCHAR&quot;, &quot;MONEY&quot;, &quot;LONG VARBINARY&quot;, or &quot;CHAR ( ) FOR BIT DATA&quot;.</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>PRECISION
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E459"></A>
<P>Integer
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E459"></A>
<P>The precision of the column on the data source. For precision information, see &quot;Precision, Scale, Length, and Display Size&quot; in Appendix D, &quot;Data Types.&quot;<A NAME="I136"></A></TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>LENGTH
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E460"></A>
<P>Integer
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E460"></A>
<P>The length in bytes of data transferred on an <B>SQLGetData</B> or <B>SQLFetch</B> operation if SQL_C_DEFAULT is specified. For numeric data, this size may be different than the size of the data stored on the data source. This value is the same as the PRECISION column for character or binary data. For more information about length, see &quot;Precision, Scale, Length, and Display Size&quot; in Appendix D, &quot;Data Types.&quot;</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>SCALE
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E461"></A>
<P>Smallint
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E461"></A>
<P>The scale of the column on the data source. For more scale information, see &quot;Precision, Scale, Length, and Display Size&quot; in Appendix D, &quot;Data Types.&quot; NULL is returned for data types where scale is not applicable.<A NAME="I137"></A></TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>RADIX
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E462"></A>
<P>Smallint
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E462"></A>
<P>For numeric data types, either 10 or 2. If it is 10, the values in PRECISION and SCALE give the number of decimal digits allowed for the column. For example, a DECIMAL(12,5) column would return a RADIX of 10, a PRECISION of 12, and a SCALE of 5; A FLOAT column could return a RADIX of 10, a PRECISION of 15 and a SCALE of NULL.
<BLOCKQUOTE>
<P>If it is 2, the values in PRECISION and SCALE give the number of bits allowed in the column. For example, a FLOAT column could return a RADIX of 2, a PRECISION of 53, and a SCALE of NULL.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>NULL is returned for data types where radix is not applicable.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>NULLABLE
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E463"></A>
<P>Smallint not NULL
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E463"></A>
<P>SQL_NO_NULLS if the column does not accept NULL values.
<BLOCKQUOTE>
<P>SQL_NULLABLE if the column accepts NULL values.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NULLABLE_UNKNOWN if it is not known if the column accepts NULL values.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>REMARKS
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E464"></A>
<P>Varchar(254)
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E464"></A>
<P>A description of the column.</TD></TR></TABLE><A NAME="I138"></A>
<BLOCKQUOTE>
<P>The <I>szTableOwner</I>, <I>szTableName</I>, and <I>szColumnName</I> arguments accept search patterns. For more information about valid search patterns, see &quot;Search Pattern Arguments&quot; earlier in this chapter.
</BLOCKQUOTE>
<A NAME="E11E105"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I139"></A></FONT></H3>
<BLOCKQUOTE>
<P>In the following example, an application declares storage locations for the result set returned by <B>SQLColumns</B>. It calls <B>SQLColumns</B> to return a result set that describes each column in the EMPLOYEE table. It then calls <B>SQLBindCol</B> to bind the columns in the result set to the storage locations. Finally, the application fetches each row of data with <B>SQLFetch</B> and processes it.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">#define STR_LEN 128+1
#define REM_LEN 254+1
/* Declare storage locations for result set data */
UCHAR  szQualifier[STR_LEN], szOwner[STR_LEN];
UCHAR  szTableName[STR_LEN], szColName[STR_LEN];
UCHAR  szTypeName[STR_LEN], szRemarks[REM_LEN];
SDWORD Precision, Length;
SWORD  DataType, Scale, Radix, Nullable;
/* Declare storage locations for bytes available to return */
SDWORD cbQualifier, cbOwner, cbTableName, cbColName;
SDWORD cbTypeName, cbRemarks, cbDataType, cbPrecision;
SDWORD cbLength, cbScale, cbRadix, cbNullable;
retcode = SQLColumns(hstmt,
                     NULL, 0,              /* All qualifiers */
                     NULL, 0,              /* All owners     */
                     &quot;EMPLOYEE&quot;, SQL_NTS,  /* EMPLOYEE table */
                     NULL, 0);             /* All columns    */
if (retcode == SQL_SUCCESS) {
   /* Bind columns in result set to storage locations */
   SQLBindCol(hstmt, 1, SQL_C_CHAR, szQualifier, STR_LEN,&amp;cbQualifier);
   SQLBindCol(hstmt, 2, SQL_C_CHAR, szOwner, STR_LEN, &amp;cbOwner);
   SQLBindCol(hstmt, 3, SQL_C_CHAR, szTableName, STR_LEN,&amp;cbTableName);
   SQLBindCol(hstmt, 4, SQL_C_CHAR, szColName, STR_LEN, &amp;cbColName);
   SQLBindCol(hstmt, 5, SQL_C_SSHORT, &amp;DataType, 0, &amp;cbDataType);
   SQLBindCol(hstmt, 6, SQL_C_CHAR, szTypeName, STR_LEN, &amp;cbTypeName);
   SQLBindCol(hstmt, 7, SQL_C_SLONG, &amp;Precision, 0, &amp;cbPrecision);
   SQLBindCol(hstmt, 8, SQL_C_SLONG, &amp;Length, 0, &amp;cbLength);
   SQLBindCol(hstmt, 9, SQL_C_SSHORT, &amp;Scale, 0, &amp;cbScale);
   SQLBindCol(hstmt, 10, SQL_C_SSHORT, &amp;Radix, 0, &amp;cbRadix);
   SQLBindCol(hstmt, 11, SQL_C_SSHORT, &amp;Nullable, 0, &amp;cbNullable);
   SQLBindCol(hstmt, 12, SQL_C_CHAR, szRemarks, REM_LEN, &amp;cbRemarks);
   while(TRUE) {
      retcode = SQLFetch(hstmt);
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {
         show_error( );
      }
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){
         ...;  /* Process fetched data */
      } else {
         break;
      }
   }
}</FONT></PRE></BLOCKQUOTE>
<A NAME="E11E106"></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="E7E465"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Assigning storage for a column in a result set
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E466"></A>
<P><B>SQLBindCol</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Canceling statement processing
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E467"></A>
<P><B>SQLCancel</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning privileges for a column or columns
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E468"></A>
<P><B>SQLColumnPrivileges</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Fetching a block of data or scrolling through a result set
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E469"></A>
<P><B>SQLExtendedFetch</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Fetching a row of data
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E470"></A>
<P><B>SQLFetch</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning table statistics and indexes
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E471"></A>
<P><B>SQLStatistics</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning a list of tables in a data source
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E472"></A>
<P><B>SQLTables</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning privileges for a table or tables
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E473"></A>
<P><B>SQLTablePrivileges</B> (extension)</TD></TR></TABLE><P ALIGN=CENTER>
<A HREF="prguid14.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="prguid16.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>