File: prguid14.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 (2128 lines) | stat: -rw-r--r-- 87,873 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="prguid15.htm">
<LINK REL="Previous" HREF="prguid13.htm"></HEAD>
<BODY BGCOLOR="#FFFFFF">
<P ALIGN=CENTER>
<A HREF="prguid13.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="prguid15.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="#E74E1" >SQLAllocConnect (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E49" >Syntax</A>
<LI>
<A HREF="#E11E50" >Returns</A>
<LI>
<A HREF="#E11E51" >Diagnostics</A>
<LI>
<A HREF="#E11E52" >Comments</A>
<LI>
<A HREF="#E11E53" >Code Example</A>
<LI>
<A HREF="#E11E54" >Related Functions</A></UL>
<LI>
<A HREF="#E10E64" >SQLAllocEnv (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E55" >Syntax</A>
<LI>
<A HREF="#E11E56" >Returns</A>
<LI>
<A HREF="#E11E57" >Diagnostics</A>
<LI>
<A HREF="#E11E58" >Comments</A>
<LI>
<A HREF="#E11E59" >Code Example</A>
<LI>
<A HREF="#E11E60" >Related Functions</A></UL>
<LI>
<A HREF="#E10E65" >SQLAllocStmt (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E61" >Syntax</A>
<LI>
<A HREF="#E11E62" >Returns</A>
<LI>
<A HREF="#E11E63" >Diagnostics</A>
<LI>
<A HREF="#E11E64" >Comments</A>
<LI>
<A HREF="#E11E65" >Code Example</A>
<LI>
<A HREF="#E11E66" >Related Functions</A></UL>
<LI>
<A HREF="#E10E66" >SQLBindCol (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E67" >Syntax</A>
<LI>
<A HREF="#E11E68" >Returns</A>
<LI>
<A HREF="#E11E69" >Diagnostics</A>
<LI>
<A HREF="#E11E70" >Comments</A>
<LI>
<A HREF="#E11E71" >Code Example</A>
<LI>
<A HREF="#E11E72" >Related Functions</A></UL>
<LI>
<A HREF="#E10E67" >SQLBindParameter (ODBC 2.0, Level 1)</A>
<UL>
<LI>
<A HREF="#E11E73" >Syntax</A>
<LI>
<A HREF="#E11E74" >Returns</A>
<LI>
<A HREF="#E11E75" >Diagnostics</A>
<LI>
<A HREF="#E11E76" >Comments</A>
<UL>
<LI>
<A HREF="#E12E31" >fParamType Argument</A>
<LI>
<A HREF="#E12E32" >fCType Argument</A>
<LI>
<A HREF="#E12E33" >fSqlType Argument</A>
<LI>
<A HREF="#E12E34" >cbColDef Argument</A>
<LI>
<A HREF="#E12E35" >rgbValue Argument</A>
<LI>
<A HREF="#E12E36" >cbValueMax Argument</A>
<LI>
<A HREF="#E12E37" >pcbValue Argument</A>
<LI>
<A HREF="#E12E38" >Passing Parameter Values</A>
<LI>
<A HREF="#E12E39" >Conversion of Calls to and from SQLSetParam</A></UL>
<LI>
<A HREF="#E11E77" >Code Example</A>
<LI>
<A HREF="#E11E78" >Related Functions</A></UL></UL></UL>
<HR ALIGN=CENTER>
<A NAME="E74E1"></A>
<H2>
<FONT FACE="Arial"><B>SQLAllocConnect (ODBC 1.0, Core)</B></FONT></H2>
<A NAME="I2"></A><A NAME="I3"></A>
<BLOCKQUOTE>
<P><B>SQLAllocConnect</B> allocates memory for a connection handle within the environment identified by <I>henv</I>.
</BLOCKQUOTE>
<A NAME="E11E49"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<A NAME="E7E186"></A>
<P>RETCODE <B>SQLAllocConnect</B>(<I>henv</I>,<I> phdbc</I>)<A NAME="I4"></A>
<BLOCKQUOTE>
<P>The <B>SQLAllocConnect</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="E7E187"></A>
<P>Argument
</TD><TD WIDTH=86 VALIGN=top >
<A NAME="E7E187"></A>
<P>Use
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E187"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HENV
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E188"></A>
<P><I>henv</I>
</TD><TD WIDTH=86 VALIGN=top >
<A NAME="E7E188"></A>
<P>Input
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E188"></A>
<P>Environment handle.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HDBC FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E189"></A>
<P><I>phdbc</I>
</TD><TD WIDTH=86 VALIGN=top >
<A NAME="E7E189"></A>
<P>Output
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E189"></A>
<P>Pointer to storage for the connection handle.</TD></TR></TABLE>
<A NAME="E11E50"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I5"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.<A NAME="I6"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If <B>SQLAllocConnect</B> returns SQL_ERROR, it will set the <I>hdbc</I> referenced by <I>phdbc</I> to SQL_NULL_HDBC. To obtain additional information, the application can call <B>SQLError</B> with the specified <I>henv</I> and with <I>hdbc</I> and <I>hstmt</I> set to SQL_NULL_HDBC and SQL_NULL_HSTMT, respectively.
</BLOCKQUOTE>
<A NAME="E11E51"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I7"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLAllocConnect</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>SQLAllocConnect </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=106 VALIGN=top >
<A NAME="E7E190"></A>
<P>Error
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E190"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E191"></A>
<P>General warning
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E191"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E192"></A>
<P>General error
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E192"></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=106 VALIGN=top >
<A NAME="E7E193"></A>
<P>Memory allocation failure
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E193"></A>
<P>(DM) The Driver Manager was unable to allocate memory for the connection handle.
<BLOCKQUOTE>
<P>The driver was unable to allocate memory for the connection handle.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1009
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E194"></A>
<P>Invalid argument value
</TD><TD WIDTH=246 VALIGN=top >
<A NAME="E7E194"></A>
<P>(DM) The argument <I>phdbc</I> was a null pointer.</TD></TR></TABLE>
<A NAME="E11E52"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I8"></A><A NAME="I9"></A><A NAME="I10"></A><A NAME="I11"></A><A NAME="I12"></A><A NAME="I13"></A></FONT></H3>
<BLOCKQUOTE>
<P>A connection handle references information such as the valid statement handles on the connection and whether a transaction is currently open. To request a connection handle, an application passes the address of an <I>hdbc</I> to <B>SQLAllocConnect</B>. The driver allocates memory for the connection information and stores the value of the associated handle in the <I>hdbc</I>. On operating systems that support multiple threads, applications can use the same <I>hdbc</I> on different threads and drivers must therefore support safe, multithreaded access to this information. The application passes the <I>hdbc</I> value in all subsequent calls that require an <I>hdbc</I>.<A NAME="I14"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The Driver Manager processes the <B>SQLAllocConnect</B> function and calls the driver&#146;s <B>SQLAllocConnect</B> function when the application calls <B>SQLConnect</B>,<B> </B><B>SQLBrowseConnect</B>, or <B>SQLDriverConnect</B>. (For more information, see the description of the <B>SQLConnect</B> function.)<A NAME="I15"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application calls <B>SQLAllocConnect</B> with a pointer to a valid <I>hdbc</I>, the driver overwrites the <I>hdbc</I> without regard to its previous contents.
</BLOCKQUOTE>
<A NAME="E11E53"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I16"></A></FONT></H3>
<BLOCKQUOTE>
<P>See <B>SQLBrowseConnect</B> and <B>SQLConnect</B>.
</BLOCKQUOTE>
<A NAME="E11E54"></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="E7E195"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Connecting to a data source
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E196"></A>
<P><B>SQLConnect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Freeing a connection handle
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E197"></A>
<P><B>SQLFreeConnect</B></TD></TR></TABLE><A NAME="E10E64"></A>
<H2>
<FONT FACE="Arial"><B>SQLAllocEnv (ODBC 1.0, Core)</B><A NAME="I17"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLAllocEnv</B> allocates memory for an environment handle and initializes the ODBC call level interface for use by an application. An application must call <B>SQLAllocEnv</B> prior to calling any other ODBC function.
</BLOCKQUOTE>
<A NAME="E11E55"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLAllocEnv</B>(<I>phenv</I>)<A NAME="I18"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLAllocEnv</B> function accepts the following argument.
</BLOCKQUOTE>
<TABLE WIDTH=800>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E198"></A>
<P>Argument
</TD><TD WIDTH=86 VALIGN=top >
<A NAME="E7E198"></A>
<P>Use
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E198"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HENV FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=106 VALIGN=top >
<A NAME="E7E199"></A>
<P><I>phenv</I>
</TD><TD WIDTH=86 VALIGN=top >
<A NAME="E7E199"></A>
<P>Output
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E199"></A>
<P>Pointer to storage for the environment handle.</TD></TR></TABLE>
<A NAME="E11E56"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I19"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS or SQL_ERROR. <A NAME="I20"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If <B>SQLAllocEnv</B> returns SQL_ERROR, it will set the <I>henv</I> referenced by <I>phenv</I> to SQL_NULL_HENV. In this case, the application can assume that the error was a memory allocation error.
</BLOCKQUOTE>
<A NAME="E11E57"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I21"></A></FONT></H3>
<BLOCKQUOTE>
<P>A driver cannot return SQLSTATE values directly after the call to <B>SQLAllocEnv</B>, since no valid handle will exist with which to call <B>SQLError</B>.<A NAME="I22"></A><A NAME="I23"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>There are two levels of <B>SQLAllocEnv</B> functions, one within the Driver Manager and one within each driver. The Driver Manager does not call the driver-level function until the application calls <B>SQLConnect</B>,<B> </B><B>SQLBrowseConnect</B>, or <B>SQLDriverConnect</B>. If an error occurs in the driver-level <B>SQLAllocEnv</B> function, then the Driver Manager &#150; level <B>SQLConnect</B>, <B>SQLBrowseConnect</B>,<B> </B>or <B>SQLDriverConnect</B> function returns SQL_ERROR. A subsequent call to <B>SQLError</B> with <I>henv</I>, SQL_NULL_HDBC, and SQL_NULL_HSTMT returns SQLSTATE IM004 (Driver&#146;s <B>SQLAllocEnv</B> failed), followed by one of the following errors from the driver:<A NAME="I24"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>SQLSTATE S1000 (General error).<A NAME="I25"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>A driver-specific SQLSTATE value, ranging from S1000 to S19ZZ. For example, SQLSTATE S1001 (Memory allocation failure) indicates that the Driver Manager&#146;s call to the driver-level <B>SQLAllocEnv </B>returned SQL_ERROR, and the Driver Manager&#146;s <I>henv</I> was set to SQL_NULL_HENV.<A NAME="I26"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>For additional information about the flow of function calls between the Driver Manager and a driver, see the <B>SQLConnect</B> function description.
</BLOCKQUOTE>
<A NAME="E11E58"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I27"></A><A NAME="I28"></A><A NAME="I29"></A><A NAME="I30"></A><A NAME="I31"></A><A NAME="I32"></A></FONT></H3>
<BLOCKQUOTE>
<P>An environment handle references global information such as valid connection handles and active connection handles. To request an environment handle, an application passes the address of an <I>henv</I> to <B>SQLAllocEnv</B>. The driver allocates memory for the environment information and stores the value of the associated handle in the <I>henv</I>. On operating systems that support multiple threads, applications can use the same <I>henv</I> on different threads and drivers must therefore support safe, multithreaded access to this information. The application passes the <I>henv</I> value in all subsequent calls that require an <I>henv</I>.<A NAME="I33"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>There should never be more than one <I>henv</I> allocated at one time and the application should not call <B>SQLAllocEnv</B> when there is a current valid <I>henv</I>. If the application calls <B>SQLAllocEnv</B> with a pointer to a valid <I>henv</I>, the driver overwrites the <I>henv</I> without regard to its previous contents.<A NAME="I34"></A><A NAME="I35"></A><A NAME="I36"></A><A NAME="I37"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>When the Driver Manager processes the <B>SQLAllocEnv</B> function, it checks the <B>Trace</B> keyword in the [ODBC] section of the ODBC.INI file or the ODBC subkey in the registry. If it is set to 1, the Driver Manager enables tracing for all applications on Windows 3.1 or for the current application on Windows NT and Windows 95.
</BLOCKQUOTE>
<A NAME="E11E59"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I38"></A></FONT></H3>
<BLOCKQUOTE>
<P>See <B>SQLBrowseConnect </B>and<B> SQLConnect</B>.
</BLOCKQUOTE>
<A NAME="E11E60"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E200"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Allocating a connection handle
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E201"></A>
<P><B>SQLAllocConnect</B></TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Connecting to a data source
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E202"></A>
<P><B>SQLConnect</B></TD>
</TR>
<TR>
<TD WIDTH=254 VALIGN=top >
<BLOCKQUOTE>
<P>Freeing an environment handle
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E203"></A>
<P><B>SQLFreeEnv</B></TD></TR></TABLE><A NAME="E10E65"></A>
<H2>
<FONT FACE="Arial"><B>SQLAllocStmt (ODBC 1.0, Core)</B><A NAME="I39"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLAllocStmt</B> allocates memory for a statement handle and associates the statement handle with the connection specified by <I>hdbc</I>.<!-- --><A NAME="I40"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application must call <B>SQLAllocStmt</B> prior to submitting SQL statements.
</BLOCKQUOTE>
<A NAME="E11E61"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLAllocStmt</B>(<I>hdbc</I>,<I> phstmt</I>)<A NAME="I41"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLAllocStmt</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="E7E204"></A>
<P>Argument
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E204"></A>
<P>Use
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E204"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HDBC
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E205"></A>
<P><I>hdbc</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E205"></A>
<P>Input
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E205"></A>
<P>Connection handle.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E206"></A>
<P><I>phstmt</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E206"></A>
<P>Output
</TD><TD WIDTH=186 VALIGN=top >
<A NAME="E7E206"></A>
<P>Pointer to storage for the statement handle.</TD></TR></TABLE>
<A NAME="E11E62"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I42"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE, or SQL_ERROR.<A NAME="I43"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If <B>SQLAllocStmt </B>returns SQL_ERROR, it will set the <I>hstmt</I> referenced by <I>phstmt</I> to SQL_NULL_HSTMT. The application can then obtain additional information by calling <B>SQLError</B> with the <I>hdbc</I> and SQL_NULL_HSTMT.
</BLOCKQUOTE>
<A NAME="E11E63"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I44"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLAllocStmt</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>SQLAllocStmt </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=80 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E207"></A>
<P>Error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E207"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E208"></A>
<P>General warning
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E208"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>08003
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E209"></A>
<P>Connection not open
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E209"></A>
<P>(DM) The connection specified by the <I>hdbc</I> argument was not open. The connection process must be completed successfully (and the connection must be open) for the driver to allocate an <I>hstmt</I>. </TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E210"></A>
<P>Driver does not support this function
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E210"></A>
<P>(DM) The driver associated with the <I>hdbc</I> does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E211"></A>
<P>General error
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E211"></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=80 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E212"></A>
<P>Memory allocation failure
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E212"></A>
<P>(DM) The Driver Manager was unable to allocate memory for the statement handle.
<BLOCKQUOTE>
<P>The driver was unable to allocate memory for the statement handle.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>S1009
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E213"></A>
<P>Invalid argument value
</TD><TD WIDTH=240 VALIGN=top >
<A NAME="E7E213"></A>
<P>(DM) The argument <I>phstmt</I> was a null pointer.</TD></TR></TABLE>
<A NAME="E11E64"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I45"></A><A NAME="I46"></A><A NAME="I47"></A></FONT></H3>
<BLOCKQUOTE>
<P>A statement handle references statement information, such as network information, SQLSTATE values and error messages, cursor name, number of result set columns, and status information for SQL statement processing.<A NAME="I48"></A><A NAME="I49"></A><A NAME="I50"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>To request a statement handle, an application connects to a data source and then passes the address of an <I>hstmt</I> to <B>SQLAllocStmt</B>. The driver allocates memory for the statement information and stores the value of the associated handle in the <I>hstmt</I>. On operating systems that support multiple threads, applications can use the same <I>hstmt</I> on different threads and drivers must therefore support safe, multithreaded access to this information. The application passes the <I>hstmt</I> value in all subsequent calls that require an <I><U>hstmt</U></I><U>.</U><A NAME="I51"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application calls <B>SQLAllocStmt</B> with a pointer to a valid <I>hstmt</I>, the driver overwrites the <I>hstmt</I> without regard to its previous contents.
</BLOCKQUOTE>
<A NAME="E11E65"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I52"></A></FONT></H3>
<BLOCKQUOTE>
<P>See <B>SQLBrowseConnect</B>,<B> SQLConnect</B>, and <B>SQLSetCursorName</B>.
</BLOCKQUOTE>
<A NAME="E11E66"></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="E7E214"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Executing an SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E215"></A>
<P><B>SQLExecDirect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Executing a prepared SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E216"></A>
<P><B>SQLExecute</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Freeing a statement handle
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E217"></A>
<P><B>SQLFreeStmt</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Preparing a statement for execution
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E218"></A>
<P><B>SQLPrepare</B></TD></TR></TABLE><A NAME="E10E66"></A>
<H2>
<FONT FACE="Arial"><B>SQLBindCol (ODBC 1.0, Core)</B><A NAME="I53"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLBindCol</B> assigns the storage and data type for a column in a result set, including:<A NAME="I54"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>A storage buffer that will receive the contents of a column of data<A NAME="I55"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The length of the storage buffer<A NAME="I56"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>A storage location that will receive the actual length of the column of data returned by the fetch operation<A NAME="I57"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Data type conversion
</BLOCKQUOTE></UL>
<A NAME="E11E67"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLBindCol</B>(<I>hstmt</I>, <I>icol</I>, <I>fCType</I>, <I>rgbValue</I>, <I>cbValueMax</I>, <I>pcbValue</I>)
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLBindCol</B> function accepts the following arguments.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E219"></A>
<P>Argument
</TD><TD WIDTH=61 VALIGN=top >
<A NAME="E7E219"></A>
<P>Use
</TD><TD WIDTH=225 VALIGN=top >
<A NAME="E7E219"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E220"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=61 VALIGN=top >
<A NAME="E7E220"></A>
<P>Input
</TD><TD WIDTH=225 VALIGN=top >
<A NAME="E7E220"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E221"></A>
<P><I>icol</I>
</TD><TD WIDTH=61 VALIGN=top >
<A NAME="E7E221"></A>
<P>Input
</TD><TD WIDTH=225 VALIGN=top >
<A NAME="E7E221"></A>
<P>Column number of result data, ordered sequentially left to right, starting at 1. A column number of 0 is used to retrieve a bookmark for the row.</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD<A NAME="I58"></A><A NAME="I59"></A><A NAME="I60"></A><A NAME="I61"></A><A NAME="I62"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P><I>fCType</I>
</BLOCKQUOTE></TD>
<TD WIDTH=61 VALIGN=top >
<A NAME="E7E222"></A>
<P>Input
</TD><TD WIDTH=225 VALIGN=top >
<A NAME="E7E222"></A>
<P>The C data type of the result data. This must be one of the following values:
<BLOCKQUOTE>
<P>SQL_C_BINARY
<BR>SQL_C_BIT
<BR>SQL_C_BOOKMARK
<BR>SQL_C_CHAR
<BR>SQL_C_DATE
<BR>SQL_C_DEFAULT
<BR>SQL_C_DOUBLE
<BR>SQL_C_FLOAT
<BR>SQL_C_SLONG
<BR>SQL_C_SSHORT
<BR>SQL_C_STINYINT
<BR>SQL_C_TIME
<BR>SQL_C_TIMESTAMP
<BR>SQL_C_ULONG
<BR>SQL_C_USHORT
<BR>SQL_C_UTINYINT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_DEFAULT specifies that data be transferred to its default C data type.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD COLSPAN=4 WIDTH=453 VALIGN=top >
<BLOCKQUOTE>
<P><B>Note</B>   Drivers must also support the following values of <I>fCType</I> from ODBC 1.0. Applications must use these values, rather than the ODBC 2.0 values, when calling an ODBC 1.0 driver:
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_LONG
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_SHORT, 
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_TINYINT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information, see &quot;ODBC 1.0 C Data Types&quot; in Appendix D, &quot;Data Types.&quot;
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For information about how data is converted, see &quot;Converting Data from SQL to C Data Types&quot; in Appendix D, &quot;Data Types.&quot;
</BLOCKQUOTE></TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>PTR
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P><I>rgbValue</I>
</BLOCKQUOTE></TD>
<TD WIDTH=61 VALIGN=top >
<A NAME="E7E223"></A>
<P>Input
</TD><TD WIDTH=225 VALIGN=top >
<A NAME="E7E223"></A>
<P>Pointer to storage for the data. If <I>rgbValue</I> is a null pointer, the driver unbinds the column. (To unbind all columns, an application calls <B>SQLFreeStmt</B> with the SQL_UNBIND option.)</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>SDWORD
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P><I>cbValueMax </I>
</BLOCKQUOTE></TD>
<TD WIDTH=61 VALIGN=top >
<A NAME="E7E224"></A>
<P>Input
</TD><TD WIDTH=225 VALIGN=top >
<A NAME="E7E224"></A>
<P>Maximum length of the <I>rgbValue</I> buffer. For character data, <I>rgbValue</I> must also include space for the null-termination byte. 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=80 VALIGN=top >
<BLOCKQUOTE>
<P>SDWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<BLOCKQUOTE>
<P><I>pcbValue</I>
</BLOCKQUOTE></TD>
<TD WIDTH=61 VALIGN=top >
<A NAME="E7E225"></A>
<P>Input
</TD><TD WIDTH=225 VALIGN=top >
<A NAME="E7E225"></A>
<P>SQL_NULL_DATA or the number of bytes (excluding the null termination byte for character data) available to return in <I>rgbValue</I> prior to calling <B>SQLExtendedFetch</B> or <B>SQLFetch</B>, or SQL_NO_TOTAL if the number of available bytes cannot be determined.
<BLOCKQUOTE>
<P>For character data, if the number of bytes available to return is SQL_NO_TOTAL or is greater than or equal to <I>cbValueMax</I>, the data in <I>rgbValue</I> is truncated to <I>cbValueMax</I> &#150; 1 bytes and is null-terminated by the driver.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For binary data, if the number of bytes available to return is SQL_NO_TOTAL or is greater than <I>cbValueMax</I>, the data in <I>rgbValue</I> is truncated to <I>cbValueMax</I> bytes.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For all other data types, the value of <I>cbValueMax</I> is ignored and the driver assumes the size of <I>rgbValue</I> is the size of the C data type specified with <I>fCType</I>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information about the value returned in <I>pcbValue</I> for each <I>fCType</I>, see &quot;Converting Data from SQL to C Data Types&quot; in Appendix D, &quot;Data Types.&quot;</TD></TR></BLOCKQUOTE></TABLE>
<A NAME="E11E68"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I63"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E69"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I64"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLBindCol</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>SQLBindCol </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=167 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E226"></A>
<P>Error
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E226"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=167 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E227"></A>
<P>General warning
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E227"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=167 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E228"></A>
<P>Driver does not support this function
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E228"></A>
<P>(DM) The driver associated with the <I>hstmt</I> does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=167 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E229"></A>
<P>General error
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E229"></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=167 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E230"></A>
<P>Memory allocation failure
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E230"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=167 VALIGN=top >
<BLOCKQUOTE>
<P>S1002
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E231"></A>
<P>Invalid column number
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E231"></A>
<P>The value specified for the argument <I>icol</I> exceeded the maximum number of columns supported by the data source.</TD>
</TR>
<TR>
<TD WIDTH=167 VALIGN=top >
<BLOCKQUOTE>
<P>S1003
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E232"></A>
<P>Program type out of range
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E232"></A>
<P>(DM) The argument <I>fCType</I> was not a valid data type or SQL_C_DEFAULT.
<BLOCKQUOTE>
<P>The argument <I>icol</I> was 0 and the argument <I>fCType</I> was not SQL_C_BOOKMARK.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=167 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E233"></A>
<P>Function sequence error
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E233"></A>
<P>(DM) An asynchronously executing function 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=167 VALIGN=top >
<BLOCKQUOTE>
<P>S1090
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E234"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E234"></A>
<P>(DM) The value specified for the argument <I>cbValueMax</I> was less than 0.</TD>
</TR>
<TR>
<TD WIDTH=167 VALIGN=top >
<BLOCKQUOTE>
<P>S1C00
</BLOCKQUOTE></TD>
<TD WIDTH=167 VALIGN=top >
<A NAME="E7E235"></A>
<P>Driver not capable
</TD><TD WIDTH=119 VALIGN=top >
<A NAME="E7E235"></A>
<P>The driver does not support the data type specified in the argument <I>fCType</I>.
<BLOCKQUOTE>
<P>The argument <I>icol</I> was 0 and the driver does not support bookmarks.</TD></TR></BLOCKQUOTE></TABLE>
<A NAME="E11E70"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I65"></A><A NAME="I66"></A></FONT></H3>
<BLOCKQUOTE>
<P>The ODBC interface provides two ways to retrieve a column of data:<A NAME="I67"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI><B>SQLBindCol</B> assigns the storage location for a column of data before the data is retrieved. When <B>SQLFetch</B> or <B>SQLExtendedFetch</B> is called, the driver places the data for all bound columns in the assigned locations.<A NAME="I68"></A><A NAME="I69"></A><A NAME="I70"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLGetData</B> (an extended function) assigns a storage location for a column of data after <B>SQLFetch</B> or <B>SQLExtendedFetch</B> has been called. It also places the data for the requested column in the assigned location. Because it can retrieve data from a column in parts, <B>SQLGetData</B> can be used to retrieve long data values.<A NAME="I71"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>An application may choose to bind every column with <B>SQLBindCol</B>, to do no binding and retrieve data only with <B>SQLGetData</B>, or to use a combination of the two. However, unless the driver provides extended functionality, <B>SQLGetData</B> can only be used to retrieve data from columns that occur after the last bound column.<A NAME="I72"></A><A NAME="I73"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application calls <B>SQLBindCol</B> to pass the pointer to the storage buffer for a column of data to the driver and to specify how or if the data will be converted. It is the application&#146;s responsibility to allocate enough storage for the data. If the buffer will contain variable length data, the application must allocate as much storage as the maximum length of the bound column or the data may be truncated. For a list of valid data conversion types, see &quot;Converting Data from SQL to C Data Types&quot; in Appendix D, &quot;Data Types.&quot;<A NAME="I74"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>At fetch time, the driver processes the data for each bound column according to the arguments specified in <B>SQLBindCol</B>. First, it converts the data according to the argument <I>fCType</I>. Next, it fills the buffer pointed to by <I>rgbValue</I>. Finally, it stores the available number of bytes in <I>pcbValue</I>; this is the number of bytes available prior to calling <B>SQLFetch</B> or <B>SQLExtendedFetch</B>.<A NAME="I75"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>If SQL_MAX_LENGTH has been specified with <B>SQLSetStmtOption</B> and the available number of bytes is greater than SQL_MAX_LENGTH, the driver stores SQL_MAX_LENGTH in <I>pcbValue</I>.<A NAME="I76"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the data is truncated because of SQL_MAX_LENGTH, but the user&#146;s buffer was large enough for SQL_MAX_LENGTH bytes of data, SQL_SUCCESS is returned.
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note The SQL_MAX_LENGTH statement option is intended to reduce network traffic and may not be supported by all drivers. To guarantee that data is truncated, an application should allocate a buffer of the desired size and specify this size in the <I>cbValueMax</I> argument.<A NAME="I77"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>If the user&#146;s buffer causes the truncation, the driver returns SQL_SUCCESS_WITH_INFO and SQLSTATE 01004 (Data truncated) for the fetch function.<A NAME="I78"></A><A NAME="I79"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the data value for a column is NULL, the driver sets <I>pcbValue</I> to SQL_NULL_DATA.<A NAME="I80"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the number of bytes available to return cannot be determined in advance, the driver sets <I>pcbValue</I> to SQL_NO_TOTAL.<A NAME="I81"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>When an application uses <B>SQLExtendedFetch</B> to retrieve more than one row of  data, it only needs to call <B>SQLBindCol</B> once for each column of the result set (just as when it binds a column in order to retrieve a single row of data with <B>SQLFetch</B>). The <B>SQLExtendedFetch</B> function coordinates the placement of each row of data into subsequent locations in the rowset buffers. For additional information about binding rowset buffers, see the &quot;Comments&quot; topic for <B>SQLExtendedFetch</B>.<A NAME="I82"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application can call <B>SQLBindCol</B> to bind a column to a new storage location, regardless of whether data has already been fetched. The new binding replaces the old binding. Note that the new binding does not apply to data already fetched; the next time data is fetched, the data will be placed in the new storage location.<A NAME="I83"></A><A NAME="I84"></A><A NAME="I85"></A><A NAME="I86"></A><A NAME="I87"></A><A NAME="I88"></A><A NAME="I89"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>To unbind a single bound column, an application calls <B>SQLBindCol</B> and specifies a null pointer for <I>rgbValue</I>; if <I>rgbValue</I> is a null pointer and the column is not bound, <B>SQLBindCol</B> returns SQL_SUCCESS. To unbind all bound columns, an application calls <B>SQLFreeStmt</B> with the SQL_UNBIND option.
</BLOCKQUOTE>
<A NAME="E11E71"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I90"></A></FONT></H3>
<BLOCKQUOTE>
<P>In the following example, an application executes a <B>SELECT</B> statement to return a result set of the employee names, ages, and birthdays, which is sorted by birthday. It then calls <B>SQLBindCol</B> to bind the columns of data to local storage locations. Finally, the application fetches each row of data with <B>SQLFetch</B> and prints each employee&#146;s name, age, and birthday.<A NAME="I91"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more code examples, see <B>SQLColumns</B>, <B>SQLExtendedFetch</B>, and <B>SQLSetPos</B>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">#define NAME_LEN 30
#define BDAY_LEN 11
UCHAR  szName[NAME_LEN], szBirthday[BDAY_LEN];
SWORD  sAge;
SDWORD cbName, cbAge, cbBirthday;
retcode = SQLExecDirect(hstmt,
<BR>   &quot;SELECT NAME, AGE, BIRTHDAY FROM EMPLOYEE ORDER BY 3, 2, 1&quot;,    SQL_NTS);
if (retcode == SQL_SUCCESS) {
   /* Bind columns 1, 2, and 3 */
   SQLBindCol(hstmt, 1, SQL_C_CHAR, szName, NAME_LEN, &amp;cbName);
   SQLBindCol(hstmt, 2, SQL_C_SSHORT, &amp;sAge, 0, &amp;cbAge);
   SQLBindCol(hstmt, 3, SQL_C_CHAR, szBirthday, BDAY_LEN, &amp;cbBirthday);
   /* Fetch and print each row of data.  On */
   /* an error, display a message and exit. */
   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){
         fprintf(out, &quot;%-*s %-2d %*s&quot;, NAME_LEN-1, szName,
<BR>                 sAge, BDAY_LEN-1, szBirthday);
      } else {
         break;
      }
   }
}</FONT></PRE></BLOCKQUOTE>
<A NAME="E11E72"></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="E7E236"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning information about a column in a result set
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E237"></A>
<P><B>SQLDescribeCol</B></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="E7E238"></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="E7E239"></A>
<P><B>SQLFetch</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Freeing a statement handle
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E240"></A>
<P><B>SQLFreeStmt</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Fetching part or all of a column of data
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E241"></A>
<P><B>SQLGetData</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the number of result set columns
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E242"></A>
<P><B>SQLNumResultCols</B></TD></TR></TABLE><A NAME="E7E242"></A>
<A NAME="E10E67"></A>
<H2>
<FONT FACE="Arial"><B>SQLBindParameter (ODBC 2.0, Level 1)</B><A NAME="I92"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLBindParameter</B> binds a buffer to a parameter marker in an SQL statement.<A NAME="I93"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note This function replaces the ODBC 1.0 function <B>SQLSetParam</B>. For more information, see &quot;Comments.&quot;</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<A NAME="E11E73"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLBindParameter</B>(<I>hstmt</I>, <I>ipar</I>, <I>fParamType</I>, <I>fCType</I>, <I>fSqlType</I>, <I>cbColDef</I>, <I>ibScale</I>, <I>rgbValue</I>, <I>cbValueMax</I>, <I>pcbValue</I>)<A NAME="I94"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLBindParameter</B> function accepts the following arguments.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E243"></A>
<P>Argument
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E243"></A>
<P>Use
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E243"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E244"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E244"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E244"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E245"></A>
<P><I>ipar</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E245"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E245"></A>
<P>Parameter number, ordered sequentially left to right, starting at 1.</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E246"></A>
<P><I>fParamType</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E246"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E246"></A>
<P>The type of the parameter. For more information, see &quot;fParamType Argument&quot; in &quot;Comments.&quot;</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E247"></A>
<P><I>fCType</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E247"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E247"></A>
<P>The C data type of the parameter. For more information, see &quot;fCType Argument&quot; in &quot;Comments.&quot;</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E248"></A>
<P><I>fSqlType</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E248"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E248"></A>
<P>The SQL data type of the parameter. For more information, see &quot;fSqlType Argument&quot; in &quot;Comments.&quot;</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>UDWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E249"></A>
<P><I>cbColDef</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E249"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E249"></A>
<P>The precision of the column or expression of the corresponding parameter marker. For more information, see &quot;cbColDef Argument&quot; in &quot;Comments.&quot;</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E250"></A>
<P><I>ibScale</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E250"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E250"></A>
<P>The scale of the column or expression of the corresponding parameter marker. For further information concerning scale, see &quot;Precision, Scale, Length, and Display Size,&quot; in Appendix D, &quot;Data Types.&quot;</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>PTR
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E251"></A>
<P><I>rgbValue</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E251"></A>
<P>Input/
<BR>Output
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E252"></A>
<P>A pointer to a buffer for the parameter&#146;s data. For more information, see &quot;rgbValue Argument&quot; in &quot;Comments.&quot;</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>SDWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E253"></A>
<P><I>cbValueMax</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E253"></A>
<P>Input
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E253"></A>
<P>Maximum length of the <I>rgbValue</I> buffer. For more information, see &quot;cbValueMax Argument&quot; in &quot;Comments.&quot;</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>SDWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E254"></A>
<P><I>pcbValue</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E254"></A>
<P>Input/
<BR>Output
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E255"></A>
<P>A pointer to a buffer for the parameter&#146;s length. For more information, see &quot;pcbValue Argument&quot; in &quot;Comments.&quot;</TD></TR></TABLE>
<A NAME="E11E74"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I95"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E75"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I96"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLBindParameter</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>SQLBindParameter </B>and explains each one in the context of this function; the notation &quot;(DM)&quot; precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E256"></A>
<P>Error
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E256"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E257"></A>
<P>General warning
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E257"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>07006
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E258"></A>
<P>Restricted data type attribute violation
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E258"></A>
<P>The data value identified by the <I>fCType</I> argument cannot be converted to the data type identified by the <I>fSqlType</I> argument.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E259"></A>
<P>Driver does not support this function
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E259"></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=140 VALIGN=top >
<A NAME="E7E260"></A>
<P>General error
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E260"></A>
<P>An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by <B>SQLError</B> in the argument <I>szErrorMsg</I> describes the error and its cause.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E261"></A>
<P>Memory allocation failure
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E261"></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>S1003
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E262"></A>
<P>Program type out of range
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E262"></A>
<P>(DM) The value specified by the argument <I>fCType</I> was not a valid data type or SQL_C_DEFAULT.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1004
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E263"></A>
<P>SQL data type out of range
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E263"></A>
<P>(DM) The value specified for the argument <I>fSqlType</I> was in the block of numbers reserved for ODBC SQL data type indicators but was not a valid ODBC SQL data type indicator.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1009
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E264"></A>
<P>Invalid argument value
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E264"></A>
<P>(DM) The argument <I>rgbValue</I> was a null pointer, the argument <I>pcbValue</I> was a null pointer, and the argument <I>fParamType</I> was not SQL_PARAM_OUTPUT.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E265"></A>
<P>Function sequence error
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E265"></A>
<P>(DM) An asynchronously executing function 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=140 VALIGN=top >
<A NAME="E7E266"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E266"></A>
<P>(DM) The value specified for the argument <I>cbValueMax</I> was less than 0.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1093
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E267"></A>
<P>Invalid parameter number
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E267"></A>
<P>(DM) The value specified for the argument <I>ipar</I> was less than 1.
<BLOCKQUOTE>
<P>The value specified for the argument <I>ipar</I> was greater than the maximum number of parameters supported by the data source.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1094
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E268"></A>
<P>Invalid scale value
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E268"></A>
<P>The value specified for the argument <I>ibScale</I> was outside the range of values supported by the data source for a column of the SQL data type specified by the <I>fSqlType</I> argument.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1104
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E269"></A>
<P>Invalid precision value
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E269"></A>
<P>The value specified for the argument <I>cbColDef</I> was outside the range of values supported by the data source for a column of the SQL data type specified by the <I>fSqlType</I> argument.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1105
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E270"></A>
<P>Invalid parameter type
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E270"></A>
<P>(DM) The value specified for the argument <I>fParamType</I> was invalid (see &quot;Comments&quot;).
<BLOCKQUOTE>
<P>The value specified for the argument <I>fParamType</I> was SQL_PARAM_OUTPUT and the parameter did not mark a return value from a procedure or a procedure parameter.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The value specified for the argument <I>fParamType</I> was SQL_PARAM_INPUT and the parameter marked the return value from a procedure.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1C00
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E271"></A>
<P>Driver not capable
</TD><TD WIDTH=220 VALIGN=top >
<A NAME="E7E271"></A>
<P>The driver or data source does not support the conversion specified by the combination of the value specified for the argument <I>fCType</I> and the driver-specific value specified for the argument <I>fSqlType</I>.
<BLOCKQUOTE>
<P>The value specified for the argument <I>fSqlType</I> was a valid ODBC SQL data type indicator for the version of ODBC supported by the driver, but was not supported by the driver or data source.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The value specified for the argument <I>fSqlType</I> was in the range of numbers reserved for driver-specific SQL data type indicators, but was not supported by the driver or data source.</TD></TR></BLOCKQUOTE></TABLE>
<A NAME="E11E76"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I97"></A><A NAME="I98"></A></FONT></H3>
<BLOCKQUOTE>
<P>An application calls <B>SQLBindParameter</B> to bind each parameter marker in an SQL statement. Bindings remain in effect until the application calls <B>SQLBindParameter</B> again or until the application calls <B>SQLFreeStmt</B> with the SQL_DROP or SQL_RESET_PARAMS option.<A NAME="I99"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information concerning parameter data types and parameter markers, see &quot;Parameter Data Types&quot; and &quot;Parameter Markers&quot; in Appendix C, &quot;SQL Grammar.&quot;
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E31"></A>
<H4>
<FONT>fParamType Argument<A NAME="I100"></A><A NAME="I101"></A><A NAME="I102"></A><A NAME="I103"></A><A NAME="I104"></A><A NAME="I105"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>fParamType</I> argument specifies the type of the parameter. All parameters in SQL statements that do not call procedures, such as <B>INSERT</B> statements, are input parameters. Parameters in procedure calls can be input, input/output, or output parameters. (An application calls <B>SQLProcedureColumns</B> to determine the type of a parameter in a procedure call; parameters in procedure calls whose type cannot be determined are assumed to be input parameters.)<A NAME="I106"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>fParamType</I> argument is one of the following values:<A NAME="I107"></A><A NAME="I108"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>SQL_PARAM_INPUT. The parameter marks a parameter in an SQL statement that does not call a procedure, such as an <B>INSERT</B> statement, or it marks an input parameter in a procedure; these are collectively known as <I>input parameters</I>. For example, the parameters in <B>INSERT </B><B>INTO Employee VALUES (?, ?, ?)</B> and <B>{call AddEmp(?, ?, ?)}</B> are input parameters.<A NAME="I109"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI> When the statement is executed, the driver sends data for the parameter to the data source; the <I>rgbValue</I> buffer must contain a valid input value or the <I>pcbValue</I> buffer must contain SQL_NULL_DATA, SQL_DATA_AT_EXEC, or the result of the SQL_LEN_DATA_AT_EXEC macro.<A NAME="I110"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI> If an application cannot determine the type of a parameter in a procedure call, it sets <I>fParamType</I> to SQL_PARAM_INPUT; if the data source returns a value for the parameter, the driver discards it.<A NAME="I111"></A><A NAME="I112"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>SQL_PARAM_INPUT_OUTPUT. The parameter marks an input/output parameter in a procedure. For example, the parameter in <B>{call </B><B>GetEmpDept(?)}</B> is an input/output parameter that accepts an employee&#146;s name and returns the name of the employee&#146;s department.<A NAME="I113"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI> When the statement is executed, the driver sends data for the parameter to the data source; the <I>rgbValue</I> buffer must contain a valid input value or the <I>pcbValue</I> buffer must contain SQL_NULL_DATA, SQL_DATA_AT_EXEC, or the result of the SQL_LEN_DATA_AT_EXEC macro. After the statement is executed, the driver returns data for the parameter to the application; if the data source does not return a value for an input/output parameter, the driver sets the <I>pcbValue</I> buffer to SQL_NULL_DATA.
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note When an ODBC 1.0 application calls <B>SQLSetParam</B> in an ODBC 2.0 driver, the Driver Manager converts this to a call to <B>SQLBindParameter</B> in which the <I>fParamType</I> argument is set to SQL_PARAM_INPUT_OUTPUT.<A NAME="I114"></A><A NAME="I115"></A><A NAME="I116"></A><A NAME="I117"></A><A NAME="I118"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>SQL_PARAM_OUTPUT. The parameter marks the return value of a procedure or an output parameter in a procedure; these are collectively known as <I>output parameters</I>. For example, the parameter in <B>{?=call </B><B>GetNextEmpID}</B> is an output parameter that returns the next employee ID.<A NAME="I119"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI> After the statement is executed, the driver returns data for the parameter to the application, unless the <I>rgbValue</I> and <I>pcbValue</I> arguments are both null pointers, in which case the driver discards the output value. If the data source does not return a value for an output parameter, the driver sets the <I>pcbValue</I> buffer to SQL_NULL_DATA.
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<A NAME="E12E32"></A>
<H4>
<FONT>fCType Argument<A NAME="I120"></A><A NAME="I121"></A><A NAME="I122"></A><A NAME="I123"></A><A NAME="I124"></A><A NAME="I125"></A><A NAME="I126"></A><A NAME="I127"></A><A NAME="I128"></A><A NAME="I129"></A><A NAME="I130"></A><A NAME="I131"></A><A NAME="I132"></A><A NAME="I133"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The C data type of the parameter. This must be one of the following values:
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_BINARY
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_BIT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_CHAR
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_DATE
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_DEFAULT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_DOUBLE
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_FLOAT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_SLONG
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_SSHORT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_STINYINT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_TIME
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_TIMESTAMP
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_ULONG
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_USHORT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_UTINYINT<A NAME="I134"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_C_DEFAULT specifies that the parameter value be transferred from the default C data type for the SQL data type specified with <I>fSqlType</I>.<A NAME="I135"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information, see &quot;Default C Data Types&quot; and &quot;Converting Data from C to SQL Data Types&quot; and &quot;Converting Data from SQL to C Data Types&quot; in Appendix D, &quot;Data Types.&quot;<A NAME="I136"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note Drivers must also support the following values of <I>fCType</I> from ODBC 1.0. Applications must use these values, instead of the ODBC 2.0 values, when calling an ODBC 1.0 driver:
<BR>
<BR> SQL_C_LONG
<BR> SQL_C_SHORT
<BR> SQL_C_TINYINT
<BR>
<BR>For more information, see &quot;ODBC 1.0 C Data Types&quot; in Appendix D, &quot;Data Types.&quot;</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E33"></A>
<H4>
<FONT>fSqlType Argument<A NAME="I137"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>This must be one of the following values:
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_BIGINT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_BINARY
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_BIT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_CHAR
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_DATE
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_DECIMAL
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_DOUBLE
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_FLOAT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_INTEGER
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_LONGVARBINARY
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_LONGVARCHAR
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_NUMERIC
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_REAL
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SMALLINT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_TIME
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_TIMESTAMP
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_TINYINT
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_VARBINARY
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_VARCHAR<A NAME="I138"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>or a driver-specific value. Values greater than SQL_TYPE_DRIVER_START are reserved by ODBC; values less than or equal to SQL_TYPE_DRIVER_START are driver-specific.<A NAME="I139"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For information about how data is converted, see &quot;Converting Data from C to SQL Data Types&quot; and &quot;Converting Data from SQL to C Data Types&quot; in Appendix D, &quot;Data Types.&quot;
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E34"></A>
<H4>
<FONT>cbColDef Argument<A NAME="I140"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>cbColDef</I> argument specifies the precision of the column or expression corresponding to the parameter marker, unless all of the following are true:<A NAME="I141"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>An ODBC 2.0 application calls <B>SQLBindParameter</B> in an ODBC 1.0 driver or an ODBC 1.0 application calls <B>SQLSetParam</B> in an ODBC 2.0 driver. (Note that the Driver Manager converts these calls.)<A NAME="I142"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The <I>fSqlType</I> argument is SQL_LONGVARBINARY or SQL_LONGVARCHAR.<A NAME="I143"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The data for the parameter will be sent with <B>SQLPutData</B>.<A NAME="I144"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>In this case, the <I>cbColDef</I> argument contains the total number of bytes that will be sent for the parameter. For more information, see &quot;Passing Parameter Values&quot; and SQL_DATA_AT_EXEC in &quot;pcbValue Argument.&quot;
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E35"></A>
<H4>
<FONT>rgbValue Argument<A NAME="I145"></A><A NAME="I146"></A><A NAME="I147"></A><A NAME="I148"></A><A NAME="I149"></A><A NAME="I150"></A><A NAME="I151"></A><A NAME="I152"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>rgbValue</I> argument points to a buffer that, when <B>SQLExecute</B> or <B>SQLExecDirect</B> is called, contains the actual data for the parameter. The data must be in the form specified by the <I>fCType</I> argument.<A NAME="I153"></A><A NAME="I154"></A><A NAME="I155"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If <I>rgbValue</I> points to a character string that contains a literal quote character ( ' ), the driver ensures that each literal quote is translated into the form required by the data source. For example, if the data source required that embedded literal quotes be doubled, the driver would replace each quote character ( ' ) with two quote characters ( ' ' ).<A NAME="I156"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If <I>pcbValue</I> is the result of the SQL_LEN_DATA_AT_EXEC(<I>length</I>) macro or SQL_DATA_AT_EXEC, then <I>rgbValue</I> is an application-defined 32-bit value that is associated with the parameter. It is returned to the application through <B>SQLParamData</B>. For example, <I>rgbValue</I> might be a token such as a parameter number, a pointer to data, or a pointer to a structure that the application used to bind input parameters. Note, however, that if the parameter is an input/output parameter, <I>rgbValue</I> must be a pointer to a buffer where the output value will be stored. If <B>SQLParamOptions</B> was called to specify multiple values for the parameter, the application can use the value of the <I>pirow</I> argument in <B>SQLParamOptions</B> in conjunction with the <I>rgbValue</I>. For example, <I>rgbValue</I> might point to an array of values  and the application might use <I>pirow</I> to retrieve the correct value from the array. For more information, see &quot;Passing Parameter Values.&quot;<A NAME="I157"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the <I>fParamType</I> argument is SQL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT, <I>rgbValue</I> points to a buffer in which the driver returns the output value. If the procedure returns one or more result sets, the <I>rgbValue</I> buffer is not guaranteed to be set until all results have been fetched. (If <I>fParamType</I> is SQL_PARAM_OUTPUT and <I>rgbValue</I> and <I>pcbValue</I> are both null pointers, the driver discards the output value.)<A NAME="I158"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application calls <B>SQLParamOptions</B> to specify multiple values for each parameter, <I>rgbValue</I> points to an array. A single SQL statement processes the entire array of input values for an input or input/output parameter and returns an array of output values for an input/output or output parameter.<A NAME="I159"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E36"></A>
<H4>
<FONT>cbValueMax Argument<A NAME="I160"></A><A NAME="I161"></A><A NAME="I162"></A><A NAME="I163"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For character and binary C data, the <I>cbValueMax</I> argument specifies the length of the <I>rgbValue</I> buffer (if it is a single element) or the length of an element in the <I>rgbValue</I> array (if the application calls <B>SQLParamOptions</B> to specify multiple values for each parameter). If the application specifies multiple values, <I>cbValueMax</I> is used to determine the location of values in the <I>rgbValue</I> array, both on input and on output. For input/output and output parameters, it is used to determine whether to truncate character and binary C data on output:<A NAME="I164"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>For character C data, if the number of bytes available to return is greater than or equal to <I>cbValueMax</I>, the data in <I>rgbValue</I> is truncated to <I>cbValueMax</I> &#150; 1 bytes and is null-terminated by the driver.<A NAME="I165"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For binary C data, if the number of bytes available to return is greater than <I>cbValueMax</I>, the data in <I>rgbValue</I> is truncated to <I>cbValueMax</I> bytes.<A NAME="I166"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>For all other types of C data, the <I>cbValueMax</I> argument is ignored. The length of the <I>rgbValue</I> buffer (if it is a single element) or the length of an element in the <I>rgbValue</I> array (if the application calls <B>SQLParamOptions</B> to specify multiple values for each parameter) is assumed to be the length of the C data type.<A NAME="I167"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note When an ODBC 1.0 application calls <B>SQLSetParam</B> in an ODBC 2.0 driver, the Driver Manager converts this to a call to <B>SQLBindParameter</B> in which the <I>cbValueMax</I> argument is always SQL_SETPARAM_VALUE_MAX. Because the Driver Manager returns an error if an ODBC 2.0 application sets <I>cbValueMax</I> to SQL_SETPARAM_VALUE_MAX, an ODBC 2.0 driver can use this to determine when it is called by an ODBC 1.0 application.
<BR>
<BR>In <B>SQLSetParam</B>, the way in which an application specifies the length of the <I>rgbValue</I> buffer so that the driver can return character or binary data and the way in which an application sends an array of character or binary parameter values to the driver are driver-defined.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E37"></A>
<H4>
<FONT>pcbValue Argument<A NAME="I168"></A><A NAME="I169"></A><A NAME="I170"></A><A NAME="I171"></A><A NAME="I172"></A><A NAME="I173"></A><A NAME="I174"></A><A NAME="I175"></A><A NAME="I176"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>pcbValue</I> argument points to a buffer that, when <B>SQLExecute</B> or <B>SQLExecDirect</B> is called, contains one of the following:<A NAME="I177"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>The length of the parameter value stored in <I>rgbValue</I>. This is ignored except for character or binary C data.<A NAME="I178"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>SQL_NTS. The parameter value is a null-terminated string.<A NAME="I179"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>SQL_NULL_DATA. The parameter value is NULL.<A NAME="I180"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>SQL_DEFAULT_PARAM. A procedure is to use the default value of a parameter, rather than a value retrieved from the application. This value is valid only in a procedure call, and then only if the <I>fParamType</I> argument is SQL_PARAM_INPUT or SQL_PARAM_INPUT_OUTPUT. When <I>pcbValue</I> is SQL_DEFAULT_PARAM, the <I>fCType</I>, <I>fSqlType</I>, <I>cbColDef</I>, <I>ibScale</I>, <I>cbValueMax</I> and <I>rgbValue</I> arguments are ignored for input parameters and are used only to define the output parameter value for input/output parameters.
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note This value was introduced in ODBC 2.0.<A NAME="I181"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>The result of the SQL_LEN_DATA_AT_EXEC(<I>length</I>) macro. The data for the parameter will be sent with <B>SQLPutData</B>. If the <I>fSqlType</I> argument is SQL_LONGVARBINARY, SQL_LONGVARCHAR, or a long, data source&#150;specific data type and the driver returns &quot;Y&quot; for the SQL_NEED_LONG_DATA_LEN information type in <B>SQLGetInfo</B>, <I>length</I> is the number of bytes of data to be sent for the parameter; otherwise, <I>length</I> must be a nonnegative value and is ignored. For more information, see &quot;Passing Parameter Values.&quot;<A NAME="I182"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI> For example, to specify that 10,000 bytes of data will be sent with <B>SQLPutData</B> for an SQL_LONGVARCHAR parameter, an application sets <I>pcbValue</I> to SQL_LEN_DATA_AT_EXEC(10000).
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note This macro was introduced in ODBC 2.0.<A NAME="I183"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>SQL_DATA_AT_EXEC. The data for the parameter will be sent with <B>SQLPutData</B>. This value is used by ODBC 2.0 applications when calling ODBC 1.0 drivers and by ODBC 1.0 applications when calling ODBC 2.0 drivers. For more information, see &quot;Passing Parameter Values.&quot;<A NAME="I184"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>If <I>pcbValue</I> is a null pointer, the driver assumes that all input parameter values are non-NULL and that character and binary data are null-terminated. If <I>fParamType</I> is SQL_PARAM_OUTPUT and <I>rgbValue</I> and <I>pcbValue</I> are both null pointers, the driver discards the output value.<A NAME="I185"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note Application developers are strongly discouraged from specifying a null pointer for <I>pcbValue</I> when the data type of the parameter is SQL_C_BINARY. For SQL_C_BINARY data, a driver sends only the data preceding an occurrence of the null-termination character, 0x00. To ensure that a driver does not unexpectedly truncate SQL_C_BINARY data, <I>pcbValue</I> should contain a pointer to a valid length value.<A NAME="I186"></A><A NAME="I187"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the <I>fParamType</I> argument is SQL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT, <I>pcbValue</I> points to a buffer in which the driver returns SQL_NULL_DATA, the number of bytes available to return in <I>rgbValue</I> (excluding the null termination byte of character data), or SQL_NO_TOTAL if the number of bytes available to return cannot be determined. If the procedure returns one or more result sets, the <I>pcbValue</I> buffer is not guaranteed to be set until all results have been fetched.<A NAME="I188"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application calls <B>SQLParamOptions</B> to specify multiple values for each parameter, <I>pcbValue</I> points to an array of SDWORD values. These can be any of the values listed earlier in this section and are processed with a single SQL statement.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E38"></A>
<H4>
<FONT>Passing Parameter Values<A NAME="I189"></A><A NAME="I190"></A><A NAME="I191"></A><A NAME="I192"></A><A NAME="I193"></A><A NAME="I194"></A><A NAME="I195"></A><A NAME="I196"></A><A NAME="I197"></A><A NAME="I198"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application can pass the value for a parameter either in the <I>rgbValue</I> buffer or with one or more calls to <B>SQLPutData</B>. Parameters whose data is passed with <B>SQLPutData</B> are known as <I>data-at-execution</I> parameters. These are commonly used to send data for SQL_LONGVARBINARY and SQL_LONGVARCHAR parameters and can be mixed with other parameters.<A NAME="I199"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>To pass parameter values, an application:<A NAME="I200"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Calls <B>SQLBindParameter</B> for each parameter to bind buffers for the parameter&#146;s value (<I>rgbValue</I> argument) and length (<I>pcbValue</I> argument). For data-at-execution parameters, <I>rgbValue</I> is an application-defined 32-bit value such as a parameter number or a pointer to data. The value will be returned later and can be used to identify the parameter.<A NAME="I201"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>2. Places values for input and input/output parameters in the <I>rgbValue</I> and <I>pcbValue</I> buffers:
</BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For normal parameters, the application places the parameter value in the <I>rgbValue</I> buffer and the length of that value in the <I>pcbValue</I> buffer.
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For data-at-execution parameters, the application places the result of the SQL_LEN_DATA_AT_EXEC(<I>length</I>) macro (when calling an ODBC 2.0 driver) or SQL_DATA_AT_EXEC (when calling an ODBC 1.0 driver) in the <I>pcbValue</I> buffer.<A NAME="I202"></A>
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<LI>3. Calls <B>SQLExecute</B> or <B>SQLExecDirect</B> to execute the SQL statement.
</BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If there are no data-at-execution parameters, the process is complete.
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If there are any data-at-execution parameters, the function returns SQL_NEED_DATA.<A NAME="I203"></A>
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<LI>4. Calls <B>SQLParamData</B> to retrieve the application-defined value specified in the <I>rgbValue</I> argument for the first data-at-execution parameter to be processed.
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note Although data-at-execution parameters are similar to data-at-execution columns, the value returned by <B>SQLParamData</B> is different for each.
<BR>
<BR>Data-at-execution parameters are parameters in an SQL statement for which data will be sent with <B>SQLPutData</B> when the statement is executed with <B>SQLExecDirect</B> or <B>SQLExecute</B>. They are bound with <B>SQLBindParameter</B>. The value returned by <B>SQLParamData</B> is a 32-bit value passed to <B>SQLBindParameter</B> in the <I>rgbValue</I> argument.
<BR>
<BR>Data-at-execution columns are columns in a rowset for which data will be sent with <B>SQLPutData</B> when a row is updated or added with <B>SQLSetPos</B>. They are bound with <B>SQLBindCol</B>. The value returned by <B>SQLParamData</B> is the address of the row in the <I>rgbValue</I> buffer that is being processed.<A NAME="I204"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>5. Calls <B>SQLPutData</B> one or more times to send data for the parameter. More than one call is needed if the data value is larger than the <I>rgbValue</I> buffer specified in <B>SQLPutData</B>; note that multiple calls to <B>SQLPutData</B> for the same parameter are allowed only when sending character C data to a column with a character, binary, or data source&#150;specific data type or when sending binary C data to a column with a character, binary, or data source&#150;specific data type.<A NAME="I205"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>6. Calls <B>SQLParamData</B> again to signal that all data has been sent for the parameter.
</BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If there are more data-at-execution parameters, <B>SQLParamData</B> returns SQL_NEED_DATA and the application-defined value for the next data-at-execution parameter to be processed. The application repeats steps 5 and 6.
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If there are no more data-at-execution parameters, the process is complete. If the statement was successfully executed, <B>SQLParamData</B> returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO; if the execution failed, it returns SQL_ERROR. At this point, <B>SQLParamData</B> can return any SQLSTATE that can be returned by the function used to execute the statement (<B>SQLExecDirect</B> or <B>SQLExecute</B>).
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI> Output values for any input/output or output parameters will be available in the <I>rgbValue</I> and <I>pcbValue</I> buffers after the application retrieves any result sets generated by the statement.<A NAME="I206"></A>
</BLOCKQUOTE></BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>After <B>SQLExecute</B> or <B>SQLExecDirect</B> returns SQL_NEED_DATA, and before data is sent for all data-at-execution parameters, the statement is canceled, or an error occurs in <B>SQLParamData</B> or <B>SQLPutData</B>, the application can only call <B>SQLCancel</B>, <B>SQLGetFunctions</B>, <B>SQLParamData</B>, or <B>SQLPutData</B> with the <I>hstmt</I> or the <I>hdbc</I> associated with the <I>hstmt</I>. If it calls any other function with the <I>hstmt</I> or the <I>hdbc</I> associated with the <I>hstmt</I>, the function returns SQL_ERROR and SQLSTATE S1010 (Function sequence error).<A NAME="I207"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application calls <B>SQLCancel</B> while the driver still needs data for data-at-execution parameters, the driver cancels statement execution; the application can then call <B>SQLExecute</B> or <B>SQLExecDirect</B> again. If the application calls <B>SQLParamData</B> or <B>SQLPutData</B> after canceling the statement, the function returns SQL_ERROR and SQLSTATE S1008 (Operation canceled).
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E39"></A>
<H4>
<FONT>Conversion of Calls to and from SQLSetParam<A NAME="I208"></A><A NAME="I209"></A><A NAME="I210"></A><A NAME="I211"></A><A NAME="I212"></A><A NAME="I213"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>When an ODBC 1.0 application calls <B>SQLSetParam</B> in an ODBC 2.0 driver, the ODBC 2.0 Driver Manager maps the call as follows:
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=213 VALIGN=top >
<BLOCKQUOTE>
<P><B>Call by ODBC 1.0 Application</B>
</BLOCKQUOTE></TD>
<TD WIDTH=240 VALIGN=top >
<A NAME="E7E272"></A>
<P>Call to ODBC 2.0 Driver</TD>
</TR>
<TR>
<TD WIDTH=213 VALIGN=top >
<BLOCKQUOTE>
<P>SQLSetParam(
<BR>  hstmt, ipar,
<BR>  fCType, fSqlType, cbColDef, ibScale,
<BR>  rgbValue,
<BR>  pcbValue);
</BLOCKQUOTE></TD>
<TD WIDTH=240 VALIGN=top >
<A NAME="E7E273"></A>
<P>SQLBindParameter(
<BR>  hstmt, ipar, SQL_PARAM_INPUT_OUTPUT,
<BR>  fCType, fSqlType, cbColDef, ibScale,
<BR>  rgbValue, SQL_SETPARAM_VALUE_MAX,
<BR>  pcbValue);</TD></TR></TABLE>
<BLOCKQUOTE>
<P>When an ODBC 2.0 application calls <B>SQLBindParameter</B> in an ODBC 1.0 driver, the ODBC 2.0 Driver Manager maps the calls as follows:
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=213 VALIGN=top >
<BLOCKQUOTE>
<P><B>Call by ODBC 2.0 Application</B>
</BLOCKQUOTE></TD>
<TD WIDTH=240 VALIGN=top >
<A NAME="E7E274"></A>
<P>Call to ODBC 1.0 Driver</TD>
</TR>
<TR>
<TD WIDTH=213 VALIGN=top >
<BLOCKQUOTE>
<P>SQLBindParameter(
<BR>  hstmt, ipar, fParamType,
<BR>  fCType, fSqlType, cbColDef, ibScale,
<BR>  rgbValue, cbValueMax, pcbValue);
</BLOCKQUOTE></TD>
<TD WIDTH=240 VALIGN=top >
<A NAME="E7E275"></A>
<P>SQLSetParam(
<BR>  hstmt, ipar,
<BR>  fCType, fSqlType, cbColDef, ibScale,
<BR>  rgbValue, pcbValue);</TD></TR></TABLE>
<A NAME="E11E77"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I214"></A></FONT></H3>
<BLOCKQUOTE>
<P>In the following example, an application prepares an SQL statement to insert data into the EMPLOYEE table. The SQL statement contains parameters for the NAME, AGE, and BIRTHDAY columns. For each parameter in the statement, the application calls <B>SQLBindParameter</B> to specify the ODBC C data type and the SQL data type of the parameter and to bind a buffer to each parameter. For each row of data, the application assigns data values to each parameter and calls <B>SQLExecute</B> to execute the statement.
</BLOCKQUOTE><A NAME="I215"></A><A NAME="I216"></A>
<BLOCKQUOTE>
<P>For more code examples, see <B>SQLParamOptions</B>, <B>SQLProcedures</B>, <B>SQLPutData</B>, and <B>SQLSetPos</B>.
</BLOCKQUOTE>
<A NAME="E7E276"></A>
<P>#define NAME_LEN 30
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">UCHAR       szName[NAME_LEN];
SWORD       sAge;
SDWORD      cbName = SQL_NTS, cbAge = 0, cbBirthday = 0;
DATE_STRUCT dsBirthday;
retcode = SQLPrepare(hstmt,
<BR>   &quot;INSERT INTO EMPLOYEE (NAME, AGE, BIRTHDAY) VALUES (?, ?, ?)&quot;,
<BR>          SQL_NTS);
if (retcode == SQL_SUCCESS) {
   /* Specify data types and buffers.          */
   /* for Name, Age, Birthday parameter data.  */
   SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR,
<BR>                    SQL_CHAR, NAME_LEN, 0, szName, 0, &amp;cbName);
   SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT,
<BR>                    SQL_SMALLINT, 0, 0, &amp;sAge, 0, &amp;cbAge);
   SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_DATE,
<BR>                    SQL_DATE, 0, 0, &amp;dsBirthday, 0, &amp;cbBirthday);
   strcpy(szName, &quot;Smith, John D.&quot;);    /* Specify first row of   */
   sAge = 40;                           /* parameter data         */
   dsBirthday.year = 1952;
   dsBirthday.month = 2;
   dsBirthday.day = 29;
   retcode = SQLExecute(hstmt);         /* Execute statement with */
                                        /* first row              */
   strcpy(szName, &quot;Jones, Bob K.&quot;);     /* Specify second row of  */
   sAge = 52;                           /* parameter data         */
   dsBirthday.year = 1940;
   dsBirthday.month = 3;
   dsBirthday.day = 31;
   SQLExecute(hstmt);                   /* Execute statement with  */
                                        /* second row              */
}</FONT></PRE></BLOCKQUOTE>
<A NAME="E11E78"></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="E7E277"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning information about a parameter in a statement
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E278"></A>
<P><B>SQLDescribeParam</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Executing an SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E279"></A>
<P><B>SQLExecDirect</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Executing a prepared SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E280"></A>
<P><B>SQLExecute</B></TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the number of statement parameters
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E281"></A>
<P><B>SQLNumParams</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the next parameter to send data for
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E282"></A>
<P><B>SQLParamData</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Specifying multiple parameter values
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E283"></A>
<P><B>SQLParamOptions</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Sending parameter data at execution time
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E284"></A>
<P><B>SQLPutData</B> (extension)</TD></TR></TABLE><P ALIGN=CENTER>
<A HREF="prguid13.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="prguid15.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>