File: prguid23.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 (2196 lines) | stat: -rw-r--r-- 92,554 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="prguid24.htm">
<LINK REL="Previous" HREF="prguid22.htm"></HEAD>
<BODY BGCOLOR="#FFFFFF">
<P ALIGN=CENTER>
<A HREF="prguid22.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="prguid24.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="#E74E10" >SQLRowCount (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E303" >Syntax</A>
<LI>
<A HREF="#E11E304" >Returns</A>
<LI>
<A HREF="#E11E305" >Diagnostics</A>
<LI>
<A HREF="#E11E306" >Comments</A>
<LI>
<A HREF="#E11E307" >Related Functions</A></UL>
<LI>
<A HREF="#E10E100" >SQLSetConnectOption (ODBC 1.0, Level 1)</A>
<UL>
<LI>
<A HREF="#E11E308" >Syntax</A>
<LI>
<A HREF="#E11E309" >Returns</A>
<LI>
<A HREF="#E11E310" >Diagnostics</A>
<LI>
<A HREF="#E11E311" >Comments</A>
<UL>
<LI>
<A HREF="#E12E58" >Data Translation</A></UL>
<LI>
<A HREF="#E11E312" >Code Example</A>
<LI>
<A HREF="#E11E313" >Related Functions</A></UL>
<LI>
<A HREF="#E10E101" >SQLSetCursorName (ODBC 1.0, Core)</A>
<UL>
<LI>
<A HREF="#E11E314" >Syntax</A>
<LI>
<A HREF="#E11E315" >Returns</A>
<LI>
<A HREF="#E11E316" >Diagnostics</A>
<LI>
<A HREF="#E11E317" >Comments</A>
<LI>
<A HREF="#E11E318" >Code Example</A>
<LI>
<A HREF="#E11E319" >Related Functions</A></UL>
<LI>
<A HREF="#E10E102" >SQLSetParam (ODBC 1.0, Deprecated)</A>
<LI>
<A HREF="#E10E103" >SQLSetPos (ODBC 1.0, Level 2)</A>
<UL>
<LI>
<A HREF="#E11E320" >Syntax</A>
<LI>
<A HREF="#E11E321" >Returns</A>
<LI>
<A HREF="#E11E322" >Diagnostics</A>
<LI>
<A HREF="#E11E323" >Comments</A>
<UL>
<LI>
<A HREF="#E12E59" >irow Argument</A>
<LI>
<A HREF="#E12E60" >fOption Argument</A>
<LI>
<A HREF="#E12E61" >fLock Argument</A>
<LI>
<A HREF="#E12E62" >Using SQLSetPos</A>
<LI>
<A HREF="#E12E63" >Performing Bulk Operations</A>
<LI>
<A HREF="#E12E64" >SQLSetPos Macros</A></UL>
<LI>
<A HREF="#E11E324" >Code Example</A>
<LI>
<A HREF="#E11E325" >Related Functions</A></UL></UL></UL>
<HR ALIGN=CENTER>
<A NAME="E74E10"></A>
<H2>
<FONT FACE="Arial"><B>SQLRowCount (ODBC 1.0, Core)</B><A NAME="I2"></A><A NAME="I3"></A><A NAME="I4"></A><A NAME="I5"></A><A NAME="I6"></A><A NAME="I7"></A><A NAME="I8"></A><A NAME="I9"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLRowCount</B> returns the number of rows affected by an <B>UPDATE</B>, <B>INSERT</B>, or <B>DELETE</B> statement or by a SQL_UPDATE, SQL_ADD, or SQL_DELETE operation in <B>SQLSetPos</B>.
</BLOCKQUOTE>
<A NAME="E11E303"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLRowCount</B>(<I>hstmt</I>, <I>pcrow</I>)<A NAME="I10"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLRowCount</B> function accepts the following arguments.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P><B>Type</B>
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E1594"></A>
<P>Argument
</TD><TD WIDTH=86 VALIGN=top >
<A NAME="E7E1594"></A>
<P>Use
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E1594"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E1595"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=86 VALIGN=top >
<A NAME="E7E1595"></A>
<P>Input
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E1595"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=73 VALIGN=top >
<BLOCKQUOTE>
<P>SDWORD FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E1596"></A>
<P><I>pcrow</I>
</TD><TD WIDTH=86 VALIGN=top >
<A NAME="E7E1596"></A>
<P>Output
</TD><TD WIDTH=200 VALIGN=top >
<A NAME="E7E1596"></A>
<P>For <B>UPDATE</B>, <B>INSERT</B>, and <B>DELETE</B> statements and for the SQL_UPDATE, SQL_ADD, and SQL_DELETE operations in <B>SQLSetPos</B>, <I>pcrow</I> is the number of rows affected by the request or &#150;1 if the number of affected rows is not available.
<BLOCKQUOTE>
<P>For other statements and functions, the driver may define the value of <I>pcrow</I>. For example, some data sources may be able to return the number of rows returned by a <B>SELECT</B> statement or a catalog function before fetching the rows.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>Note</B>   Many data sources cannot return the number of rows in a result set before fetching them; for maximum interoperability, applications should not rely on this behavior.</TD></TR></BLOCKQUOTE></TABLE>
<A NAME="E11E304"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I11"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E305"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I12"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLRowCount </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 
<BR><B>SQLRowCount </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="E7E1597"></A>
<P>Error
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E1597"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E1598"></A>
<P>General warning
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E1598"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E1599"></A>
<P>Driver does not support this function
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E1599"></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="E7E1600"></A>
<P>General error
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E1600"></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="E7E1601"></A>
<P>Memory allocation failure
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E1601"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=93 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E1602"></A>
<P>Function sequence error
</TD><TD WIDTH=206 VALIGN=top >
<A NAME="E7E1602"></A>
<P>(DM) The function was called prior to calling <B>SQLExecute</B>, <B>SQLExecDirect</B>, <B>SQLSetPos</B> for the <I>hstmt</I>.
<BLOCKQUOTE>
<P>(DM) An asynchronously executing function 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></TABLE>
<A NAME="E11E306"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I13"></A></FONT></H3>
<BLOCKQUOTE>
<P>If the last executed statement associated with <I>hstmt</I> was not an <B>UPDATE</B>, <B>INSERT</B>, or <B>DELETE</B> statement, or if the <I>fOption</I> argument in the previous call to <B>SQLSetPos</B> was not SQL_UPDATE, SQL_ADD, or SQL_DELETE, the value of <I>pcrow</I> is driver-defined.
</BLOCKQUOTE>
<A NAME="E11E307"></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="E7E1603"></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="E7E1604"></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="E7E1605"></A>
<P><B>SQLExecute</B></TD></TR></TABLE><A NAME="E10E100"></A>
<H2>
<FONT FACE="Arial"><B>SQLSetConnectOption (ODBC 1.0, Level 1)</B><A NAME="I14"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLSetConnectOption</B> sets options that govern aspects of connections.
</BLOCKQUOTE>
<A NAME="E11E308"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLSetConnectOption</B>(<I>hdbc</I>, <I>fOption</I>, <I>vParam</I>)<A NAME="I15"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLSetConnectOption</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="E7E1606"></A>
<P>Argument
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E1606"></A>
<P>Use
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1606"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>HDBC
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E1607"></A>
<P><I>hdbc</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E1607"></A>
<P>Input
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1607"></A>
<P>Connection handle.</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E1608"></A>
<P><I>fOption</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E1608"></A>
<P>Input
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1608"></A>
<P>Option to set, listed in &quot;Comments.&quot;</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>UDWORD
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E1609"></A>
<P><I>vParam</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E1609"></A>
<P>Input
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1609"></A>
<P>Value associated with <I>fOption</I>. Depending on the value of <I>fOption</I>, <I>vParam</I> will be a 32-bit integer value or point to a null-terminated character string.</TD></TR></TABLE>
<A NAME="E11E309"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I16"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E310"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I17"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLSetConnectOption</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>SQLSetConnectOption </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.<A NAME="I18"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The driver can return SQL_SUCCESS_WITH_INFO to provide information about the result of setting an option. For example, setting SQL_ACCESS_MODE to read-only during a transaction might cause the transaction to be committed. The driver could use SQL_SUCCESS_WITH_INFO &#151; and information returned with <B>SQLError</B> &#151; to inform the application of the commit action.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSTATE</B>
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1610"></A>
<P>Error
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1610"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1611"></A>
<P>General warning
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1611"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>01S02
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1612"></A>
<P>Option value changed
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1612"></A>
<P>The driver did not support the specified value of the <I>vParam</I> argument and substituted a similar value. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>08002
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1613"></A>
<P>Connection in use
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1613"></A>
<P>The argument <I>fOption</I> was SQL_ODBC_CURSORS and the driver was already connected to the data source.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>08003
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1614"></A>
<P>Connection not open
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1614"></A>
<P>An <I>fOption</I> value was specified that required an open connection, but the <I>hdbc</I> was not in a connected state.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>08S01
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1615"></A>
<P>Communication link failure
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1615"></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=106 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1616"></A>
<P>Driver does not support this function
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1616"></A>
<P>(DM) The driver associated with the <I>hdbc</I> does not support the function.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>IM009
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1617"></A>
<P>Unable to load translation DLL
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1617"></A>
<P>The driver was unable to load the translation DLL that was specified for the connection. This error can only be returned when <I>fOption</I> is SQL_TRANSLATE_DLL.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1618"></A>
<P>General error
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1618"></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=106 VALIGN=top >
<BLOCKQUOTE>
<P>S1001
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1619"></A>
<P>Memory allocation failure
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1619"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>S1009
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1620"></A>
<P>Invalid argument value
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1620"></A>
<P>Given the specified <I>fOption</I> value, an invalid value was specified for the argument <I>vParam</I>. (The Driver Manager returns this SQLSTATE only for connection and statement options that accept a discrete set of values, such as SQL_ACCESS_MODE or SQL_ASYNC_ENABLE. For all other connection and statement options, the driver must verify the value of the argument <I>vParam</I>.)</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1621"></A>
<P>Function sequence error
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1621"></A>
<P>(DM) An asynchronously executing function was called for an <I>hstmt</I> associated with the <I>hdbc</I> and was still executing when <B>SQLSetConnectOption</B> was called.
<BLOCKQUOTE>
<P>(DM) <B>SQLExecute</B>, <B>SQLExecDirect</B>, or <B>SQLSetPos</B> was called for an <I>hstmt</I> associated with the <I>hdbc</I> and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>(DM) <B>SQLBrowseConnect</B> was called for the <I>hdbc</I> and returned SQL_NEED_DATA. This function was called before <B>SQLBrowseConnect</B> returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>S1011
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1622"></A>
<P>Operation invalid at this time
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1622"></A>
<P>The argument <I>fOption</I> was SQL_TXN_ISOLATION and a transaction was open.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>S1092
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1623"></A>
<P>Option type out of range
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1623"></A>
<P>(DM) The value specified for the argument <I>fOption</I> was in the block of numbers reserved for ODBC connection and statement options, but was not valid for the version of ODBC supported by the driver.</TD>
</TR>
<TR>
<TD WIDTH=106 VALIGN=top >
<BLOCKQUOTE>
<P>S1C00
</BLOCKQUOTE></TD>
<TD WIDTH=133 VALIGN=top >
<A NAME="E7E1624"></A>
<P>Driver not capable
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1624"></A>
<P>The value specified for the argument <I>fOption</I> was a valid ODBC connection or statement option for the version of ODBC supported by the driver, but was not supported by the driver.
<BLOCKQUOTE>
<P>The value specified for the argument <I>fOption</I> was in the block of numbers reserved for driver-specific connection and statement options, but was not supported by the driver.</TD></TR></BLOCKQUOTE></TABLE><A NAME="I19"></A>
<BLOCKQUOTE>
<P>When <I>fOption</I> is a statement option, <B>SQLSetConnectOption</B> can return any SQLSTATEs returned by <B>SQLSetStmtOption</B>.
</BLOCKQUOTE>
<A NAME="E11E311"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I20"></A></FONT></H3>
<BLOCKQUOTE>
<P>The currently defined options and the version of ODBC in which they were introduced are shown below; it is expected that more will be defined to take advantage of different data sources. Options from 0 to 999 are reserved by ODBC; driver developers must reserve values greater than or equal to SQL_CONNECT_OPT_DRVR_START for driver-specific use.<A NAME="I21"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application can call <B>SQLSetConnectOption</B> and include a statement option. The driver sets the statement option for any <I>hstmts</I> associated with the specified <I>hdbc</I> and establishes the statement option as a default for any <I>hstmts</I> later allocated for that <I>hdbc</I>. For a list of statement options, see <B>SQLSetStmtOption</B>.<A NAME="I22"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>All connection and statement options successfully set by the application for the <I>hdbc</I> persist until <B>SQLFreeConnect</B> is called on the <I>hdbc</I>. For example, if an application calls <B>SQLSetConnectOption</B> before connecting to a data source, the option persists even if <B>SQLSetConnectOption</B> fails in the driver when the application connects to the data source; if an application sets a driver-specific option, the option persists even if the application connects to a different driver on the <I>hdbc</I>.<A NAME="I23"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Some connection and statement options support substitution of a similar value if the data source does not support the specified value of <I>vParam</I>. In such cases, the driver returns SQL_SUCCESS_WITH_INFO and SQLSTATE 01S02 (Option value changed). For example, if <I>fOption</I> is SQL_PACKET_SIZE and <I>vParam</I> exceeds the maximum packet size, the driver substitutes the maximum size. To determine the substituted value, an application calls <B>SQLGetConnectOption</B> (for connection options) or <B>SQLGetStmtOption</B> (for statement options).<A NAME="I24"></A><A NAME="I25"></A><A NAME="I26"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The format of information set through <I>vParam</I> depends on the specified <I>fOption</I>. <B>SQLSetConnectOption</B> will accept option information in one of two different formats: a null-terminated character string or a 32-bit integer value. The format of each is noted in the option&#146;s description. Character strings pointed to by the <I>vParam</I> argument of <B>SQLSetConnectOption</B> have a maximum length of SQL_MAX_OPTION_STRING_LENGTH bytes (excluding the null termination byte).
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P><B>fOption</B>
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1625"></A>
<P>vParam Contents</TD>
</TR>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_ACCESS_MODE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1626"></A>
<P>A 32-bit integer value. SQL_MODE_READ_ONLY is used by the driver or data source as an indicator that the connection is not required to support SQL statements that cause updates to occur. This mode can be used to optimize locking strategies, transaction management, or other areas as appropriate to the driver or data source. The driver is not required to prevent such statements from being submitted to the data source. The behavior of the driver and data source when asked to process SQL statements that are not read-only during a read-only connection is implementation defined. SQL_MODE_READ_WRITE is the default.<A NAME="I27"></A><A NAME="I28"></A><A NAME="I29"></A><A NAME="I30"></A><A NAME="I31"></A><A NAME="I32"></A></TD>
</TR>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_AUTOCOMMIT
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1627"></A>
<P>A 32-bit integer value that specifies whether to use auto-commit or manual-commit mode:
<BLOCKQUOTE>
<P>SQL_AUTOCOMMIT_OFF = The driver uses manual-commit mode, and the application must explicitly commit or roll back transactions with <B>SQLTransact</B>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_AUTOCOMMIT_ON = The driver uses auto-commit mode. Each statement is committed immediately after it is executed. This is the default. Note that changing from manual-commit mode to auto-commit mode commits any open transactions on the connection.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P> <B>Important</B>   Some data sources delete the access plans and close the cursors for all hstmts on an hdbc each time a statement is committed; autocommit mode can cause this to happen after each statement is executed. For more information, see the SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR information types in <B>SQLGetInfo</B>.<A NAME="I33"></A><A NAME="I34"></A><A NAME="I35"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_CURRENT_QUALIFIER
<BR>(ODBC 2.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1628"></A>
<P>A null-terminated character string containing the name of the qualifier to be used by the data source. For example, in SQL Server, the qualifier is a database, so the driver sends a <B>USE</B> database statement to the data source, where database is the database specified in vParam. For a single-tier driver, the qualifier might be a directory, so the driver changes its current directory to the directory specified in vParam.<A NAME="I36"></A><A NAME="I37"></A><A NAME="I38"></A></TD>
</TR>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_LOGIN_TIMEOUT
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1629"></A>
<P>A 32-bit integer value corresponding to the number of seconds to wait for a login request to complete before returning to the application. The default is driver-dependent and must be nonzero. If vParam is 0, the timeout is disabled and a connection attempt will wait indefinitely.
<BLOCKQUOTE>
<P>If the specified timeout exceeds the maximum login timeout in the data source, the driver substitutes that value and returns SQLSTATE 01S02 (Option value changed).<A NAME="I39"></A><A NAME="I40"></A><A NAME="I41"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_ODBC_CURSORS
<BR>(ODBC 2.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1630"></A>
<P>A 32-bit option specifying how the Driver Manager uses the ODBC cursor library:
<BLOCKQUOTE>
<P>SQL_CUR_USE_IF_NEEDED = The Driver Manager uses the ODBC cursor library only if it is needed. If the driver supports the SQL_FETCH_PRIOR option in <B>SQLExtendedFetch</B>, the Driver Manager uses the scrolling capabilities of the driver. Otherwise, it uses the ODBC cursor library.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_CUR_USE_ODBC = The Driver Manager uses the ODBC cursor library.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_CUR_USE_DRIVER = The Driver Manager uses the scrolling capabilities of the driver. This is the default setting.<A NAME="I42"></A><A NAME="I43"></A><A NAME="I44"></A><A NAME="I45"></A><A NAME="I46"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_OPT_TRACE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1631"></A>
<P>A 32-bit integer value telling the Driver Manager whether to perform tracing:
<BLOCKQUOTE>
<P>SQL_OPT_TRACE_OFF = Tracing off (the default)
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_OPT_TRACE_ON = Tracing on
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>When tracing is on, the Driver Manager writes each ODBC function call to the trace file. On Windows and WOW, the Driver Manager writes to the trace file each time any application calls a function. On Windows NT, the Driver Manager writes to the trace file only for the application that turned tracing on.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>Note</B>   When tracing is on, the Driver Manager can return SQLSTATE IM013 (Trace file error) from any function.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application specifies a trace file with the SQL_OPT_TRACEFILE option. If the file already exists, the Driver Manager appends to the file. Otherwise, it creates the file. If tracing is on and no trace file has been specified, the Driver Manager writes to the file \SQL.LOG. On Windows NT, tracing should only be used for a single application or each application should specify a different trace file. Otherwise, two or more applications will attempt to open the same trace file at the same time, causing an error.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the <B>Trace</B> keyword in the [ODBC] section of the ODBC.INI file (or registry) is set to 1 when an application calls <B>SQLAllocEnv</B>, tracing is enabled. On Windows and WOW, it is enabled for all applications; on Windows NT it is enabled only for the application that called <B>SQLAllocEnv</B>.<A NAME="I47"></A><A NAME="I48"></A><A NAME="I49"></A><A NAME="I50"></A><A NAME="I51"></A><A NAME="I52"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_OPT_TRACEFILE
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1632"></A>
<P>A null-terminated character string containing the name of the trace file.
<BLOCKQUOTE>
<P>The default value of the SQL_OPT_TRACEFILE option is specified with the TraceFile keyname in the [ODBC] section of the ODBC.INI file (or registry).<A NAME="I53"></A><A NAME="I54"></A><A NAME="I55"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_PACKET_SIZE
<BR>(ODBC 2.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1633"></A>
<P>A 32-bit integer value specifying the network packet size in bytes.
<BLOCKQUOTE>
<P><B>Note   </B>Many data sources either do not support this option or can only return the network packet size.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the specified size exceeds the maximum packet size or is smaller than the minimum packet size, the driver substitutes that value and returns SQLSTATE 01S02 (Option value changed).<A NAME="I56"></A><A NAME="I57"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_QUIET_MODE
<BR>(ODBC 2.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1634"></A>
<P>A 32-bit window handle (hwnd).
<BLOCKQUOTE>
<P>If the window handle is a null pointer, the driver does not display any dialog boxes.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the window handle is not a null pointer, it should be the parent window handle of the application. The driver uses this handle to display dialog boxes. This is the default.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application has not specified a parent window handle for this option, the driver uses a null parent window handle to display dialog boxes or return in <B>SQLGetConnectOption</B>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>Note   </B>The SQL_QUIET_MODE connection option does not apply to dialog boxes displayed by <B>SQLDriverConnect</B>.<A NAME="I58"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P><!--SQL_TRANSLATE_DLL-->
<BR><!--(ODBC 1.0)-->
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1635"></A>
<P><!--A null-terminated character string containing the --><!--name of a DLL containing the functions --><!--<B>SQLDriverToDataSource</B>--><!-- and --><!--<B>SQLDataSourceToDriver</B>--><!-- that the driver loads --><!--and uses to perform tasks such as character set --><!--translation. This option may only be specified if --><!--the driver has connected to the data source.--></TD>
</TR>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_TRANSLATE_OPTION
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1636"></A>
<P>A 32-bit flag value that is passed to the translatation DLL. This option may only be specified if the driver has connected to the data source.
<BLOCKQUOTE>
<P>The valid values are:
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SOLID_XLATOPT_DEFAULT = The application uses the default character set conversion for the operating system used.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SOLID_XLATOPT_NOCNV = No conversion is done. The characters are stored as they are given.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SOLID_XLATOPT_ANSI = The charaters are considered to belong to ANSI (ISO Latin 1) character set. This character set is used i.e. in MS Windows.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SOLID_XLATOPT_PCOEM = This character set is used i.e. in MS DOS and OS/2.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_SOLID_XLATOPT_7BITSCAND = This character set is used i.e. in VAX/VMS.<A NAME="I59"></A><A NAME="I60"></A><A NAME="I61"></A><A NAME="I62"></A><A NAME="I63"></A></TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_TXN_ISOLATION
<BR>(ODBC 1.0)
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1637"></A>
<P>A 32-bit bitmask that sets the transaction isolation level for the current hdbc. An application must call <B>SQLTransact</B> to commit or roll back all open transactions on an hdbc, before calling <B>SQLSetConnectOption</B> with this option.
<BLOCKQUOTE>
<P>The valid values for vParam can be determined by calling <B>SQLGetInfo</B> with fInfoType equal to SQL_TXN_ISOLATION_OPTIONS. The following terms are used to define transaction isolation levels:
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>Dirty Read    </B>Transaction 1 changes a row. Transaction 2 reads the changed row before transaction 1 commits the change. If transaction 1 rolls back the change, transaction 2 will have read a row that is considered to have never existed.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>Nonrepeatable Read    </B>Transaction 1 reads a row. Transaction 2 updates or deletes that row and commits this change. If transaction 1 attempts to reread the row, it will receive different row values or discover that the row has been deleted.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>Phantom    </B>Transaction 1 reads a set of rows that satisfy some search criteria. Transaction 2 inserts a row that matches the search criteria. If transaction 1 reexecutes the statement that read the rows, it receives a different set of rows.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>vParam must be one of the following values:
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_TXN_READ_UNCOMMITTED = Dirty reads, nonrepeatable reads, and phantoms are possible.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_TXN_READ_COMMITTED = Dirty reads are not possible. Nonrepeatable reads and phantoms are possible.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_TXN_REPEATABLE_READ = Dirty reads and nonrepeatable reads are not possible. Phantoms are possible.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_TXN_SERIALIZABLE = Transactions are serializable. Dirty reads, nonrepeatable reads, and phantoms are not possible.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>SQL_TXN_VERSIONING = Transactions are serializable, but higher concurrency is possible than with SQL_TXN_SERIALIZABLE. Dirty reads are not possible. Typically, SQL_TXN_SERIALIZABLE is implemented by using locking protocols that reduce concurrency and SQL_TXN_VERSIONING is implemented by using a non-locking protocol such as record versioning. Oracle&#146;s Read Consistency isolation level is an example of SQL_TXN_VERSIONING.</TD></TR></BLOCKQUOTE></TABLE>
<BLOCKQUOTE>
<A NAME="E12E58"></A>
<H4>
<FONT>Data Translation<A NAME="I64"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Data translation will be performed for all data flowing between the driver and the data source.<A NAME="I65"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The translation option (set with the SQL_TRANSLATE_OPTION option) can be any 32-bit value. Its meaning depends on the translation DLL being used. A new option can be set at any time. The new option will be applied to the next exchange of data following the call to <B>SQLSetConnectOption</B>. A default translation DLL may be specified for the data source in its data source specification in the ODBC.INI file or registry. The default translation DLL is loaded by the driver at connection time. A translation option (SQL_TRANSLATE_OPTION) may be specified in the data source specification as well.<A NAME="I66"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>To change the translation DLL for a connection, an application calls <B>SQLSetConnectOption</B> with the SQL_TRANSLATE_DLL option after it has connected to the data source. The driver will attempt to load the specified DLL and, if the attempt fails, return SQL_ERROR with the SQLSTATE IM009 (Unable to load translation DLL).<A NAME="I67"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If no translation DLL has been specified in the ODBC initialization file or by calling <B>SQLSetConnectOption</B>, the driver will not attempt to translate data. Any value set for the translation option will be ignored.
</BLOCKQUOTE>
<A NAME="E11E312"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I68"></A></FONT></H3>
<BLOCKQUOTE>
<P>See <B>SQLConnect</B> and <B>SQLParamOptions</B>.
</BLOCKQUOTE>
<A NAME="E11E313"></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="E7E1638"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the setting of a connection option
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E1639"></A>
<P><B>SQLGetConnectOption</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Returning the setting of a statement option
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E1640"></A>
<P><B>SQLGetStmtOption</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Setting a statement option
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E1641"></A>
<P><B>SQLSetStmtOption</B> (extension)</TD></TR></TABLE><A NAME="E10E101"></A>
<H2>
<FONT FACE="Arial"><B>SQLSetCursorName (ODBC 1.0, Core)</B><A NAME="I69"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLSetCursorName</B> associates a cursor name with an active <I>hstmt</I>. If an application does not call <B>SQLSetCursorName</B>, the driver generates cursor names as needed for SQL statement processing.
</BLOCKQUOTE>
<A NAME="E11E314"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLSetCursorName</B>(<I>hstmt</I>, <I>szCursor</I>, <I>cbCursor</I>)<A NAME="I70"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLSetCursorName</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=86 VALIGN=top >
<A NAME="E7E1642"></A>
<P>Argument
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E1642"></A>
<P>Use
</TD><TD WIDTH=193 VALIGN=top >
<A NAME="E7E1642"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E1643"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E1643"></A>
<P>Input
</TD><TD WIDTH=193 VALIGN=top >
<A NAME="E7E1643"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>UCHAR FAR *
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E1644"></A>
<P><I>szCursor</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E1644"></A>
<P>Input
</TD><TD WIDTH=193 VALIGN=top >
<A NAME="E7E1644"></A>
<P>Cursor name.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>SWORD
</BLOCKQUOTE></TD>
<TD WIDTH=86 VALIGN=top >
<A NAME="E7E1645"></A>
<P><I>cbCursor</I>
</TD><TD WIDTH=73 VALIGN=top >
<A NAME="E7E1645"></A>
<P>Input
</TD><TD WIDTH=193 VALIGN=top >
<A NAME="E7E1645"></A>
<P>Length of <I>szCursor</I>.</TD></TR></TABLE>
<A NAME="E11E315"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I71"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E316"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I72"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLSetCursorName</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>SQLSetCursorName </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=140 VALIGN=top >
<A NAME="E7E1646"></A>
<P>Error
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1646"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E1647"></A>
<P>General warning
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1647"></A>
<P>Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>24000
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E1648"></A>
<P>Invalid cursor state
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1648"></A>
<P>The statement corresponding to <I>hstmt</I> was already in an executed or cursor-positioned state.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>34000
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E1649"></A>
<P>Invalid cursor name
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1649"></A>
<P>The cursor name specified by the argument <I>szCursor</I> was invalid. For example, the cursor name exceeded the maximum length as defined by the driver.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>3C000
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E1650"></A>
<P>Duplicate cursor name
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1650"></A>
<P>The cursor name specified by the argument <I>szCursor</I> already exists.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E1651"></A>
<P>Driver does not support this function
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1651"></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=140 VALIGN=top >
<A NAME="E7E1652"></A>
<P>General error
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1652"></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=140 VALIGN=top >
<A NAME="E7E1653"></A>
<P>Memory allocation failure
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1653"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1009
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E1654"></A>
<P>Invalid argument value
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1654"></A>
<P>(DM) The argument <I>szCursor</I> was a null pointer.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E1655"></A>
<P>Function sequence error
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1655"></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=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1090
</BLOCKQUOTE></TD>
<TD WIDTH=140 VALIGN=top >
<A NAME="E7E1656"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1656"></A>
<P>(DM) The argument <I>cbCursor</I> was less than 0, but not equal to SQL_NTS.</TD></TR></TABLE>
<A NAME="E11E317"></A>
<H3>
<FONT FACE="Arial">Comments<A NAME="I73"></A><A NAME="I74"></A><A NAME="I75"></A><A NAME="I76"></A></FONT></H3>
<BLOCKQUOTE>
<P>The only ODBC SQL statements that use a cursor name are a positioned update and delete (for example, <B>UPDATE</B> <I>table-name</I> ...<B>WHERE CURRENT </B><B>OF</B> <I>cursor-name</I>). If the application does not call <B>SQLSetCursorName</B> to define a cursor name, on execution of a <B>SELECT</B> statement the driver generates a name that begins with the letters SQL_CUR and does not exceed 18 characters in length.<A NAME="I77"></A><A NAME="I78"></A><A NAME="I79"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>All cursor names within the <I>hdbc</I> must be unique. The maximum length of a cursor name is defined by the driver. For maximum interoperability, it is recommended that applications limit cursor names to no more than 18 characters.<A NAME="I80"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>A cursor name that is set either explicitly or implicitly remains set until the <I>hstmt</I> with which it is associated is dropped, using <B>SQLFreeStmt</B> with the SQL_DROP option.
</BLOCKQUOTE>
<A NAME="E11E318"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I81"></A></FONT></H3>
<BLOCKQUOTE>
<P>In the following example, an application uses <B>SQLSetCursorName</B> to set a cursor name for an <I>hstmt</I>. It then uses that <I>hstmt</I> to retrieve results from the EMPLOYEE table. Finally, it performs a positioned update to change the name of 25-year-old John Smith to John D. Smith. Note that the application uses different <I>hstmts</I> for the <B>SELECT</B> and <B>UPDATE</B> statements.<A NAME="I82"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more code examples, see <B>SQLSetPos</B>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">#define NAME_LEN 30
HSTMT     hstmtSelect,
HSTMT     hstmtUpdate;
UCHAR     szName[NAME_LEN];
SWORD     sAge;
SDWORD    cbName;
SDWORD    cbAge;
/* Allocate the statements and set the cursor name */
SQLAllocStmt(hdbc, &amp;hstmtSelect);
SQLAllocStmt(hdbc, &amp;hstmtUpdate);
SQLSetCursorName(hstmtSelect, &quot;C1&quot;, SQL_NTS);
/* SELECT the result set and bind its columns to local storage */
SQLExecDirect(hstmtSelect,
<BR>              &quot;SELECT NAME, AGE FROM EMPLOYEE FOR UPDATE&quot;,
<BR>              SQL_NTS);
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &amp;cbName);
SQLBindCol(hstmtSelect, 2, SQL_C_SSHORT, &amp;sAge, 0, &amp;cbAge);
/* Read through the result set until the cursor is      */
/* positioned on the row for the 25-year-old John Smith */
do
   retcode = SQLFetch(hstmtSelect);
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &amp;&amp;
<BR>       (strcmp(szName, &quot;Smith, John&quot;) != 0 || sAge != 25));
/* Perform a positioned update of John Smith's name */
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
   SQLExecDirect(hstmtUpdate,
<BR>    &quot;UPDATE EMPLOYEE SET NAME=\&quot;Smith, John D.\&quot; WHERE CURRENT OF C1&quot;,
<BR>      SQL_NTS);
}</FONT></PRE></BLOCKQUOTE>
<A NAME="E11E319"></A>
<H3>
<FONT FACE="Arial">Related Functions</FONT></H3>

<TABLE WIDTH=800 >
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P><B>For information about</B>
</BLOCKQUOTE></TD>
<TD WIDTH=233 VALIGN=top >
<A NAME="E7E1657"></A>
<P>See</TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>Executing an SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=233 VALIGN=top >
<A NAME="E7E1658"></A>
<P><B>SQLExecDirect</B></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>Executing a prepared SQL statement
</BLOCKQUOTE></TD>
<TD WIDTH=233 VALIGN=top >
<A NAME="E7E1659"></A>
<P><B>SQLExecute</B></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>Returning a cursor name
</BLOCKQUOTE></TD>
<TD WIDTH=233 VALIGN=top >
<A NAME="E7E1660"></A>
<P><B>SQLGetCursorName</B></TD>
</TR>
<TR>
<TD WIDTH=220 VALIGN=top >
<BLOCKQUOTE>
<P>Setting cursor scrolling options
</BLOCKQUOTE></TD>
<TD WIDTH=233 VALIGN=top >
<A NAME="E7E1661"></A>
<P><B>SQLSetScrollOptions</B> (extension)</TD></TR></TABLE><A NAME="E10E102"></A>
<H2>
<FONT FACE="Arial"><B>SQLSetParam (ODBC 1.0, Deprecated)</B><A NAME="I83"></A><A NAME="I84"></A><A NAME="I85"></A><A NAME="I86"></A></FONT></H2>
<A NAME="I87"></A><A NAME="I88"></A><A NAME="I89"></A><A NAME="I90"></A><A NAME="I91"></A><A NAME="I92"></A>
<BLOCKQUOTE>
<P>In ODBC 2.0, the ODBC 1.0 function <B>SQLSetParam</B> has been replaced by <B>SQLBindParameter</B>. For more information, see <B>SQLBindParameter</B>.
</BLOCKQUOTE>
<A NAME="E10E103"></A>
<H2>
<FONT FACE="Arial"><B>SQLSetPos (ODBC 1.0, Level 2)</B><A NAME="I93"></A><A NAME="I94"></A><A NAME="I95"></A><A NAME="I96"></A></FONT></H2>
<BLOCKQUOTE>
<P><B>SQLSetPos</B> sets the cursor position in a rowset and allows an application to refresh, update, delete, or add data to the rowset.
</BLOCKQUOTE>
<A NAME="E11E320"></A>
<H3>
<FONT FACE="Arial">Syntax</FONT></H3>
<BLOCKQUOTE>
<P>RETCODE <B>SQLSetPos</B>(<I>hstmt</I>, <I>irow</I>, <I>fOption</I>, <I>fLock</I>)<A NAME="I97"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <B>SQLSetPos</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="E7E1662"></A>
<P>Argument
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E1662"></A>
<P>Use
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1662"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>HSTMT
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E1663"></A>
<P><I>hstmt</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E1663"></A>
<P>Input
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1663"></A>
<P>Statement handle.</TD>
</TR>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E1664"></A>
<P><I>irow</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E1664"></A>
<P>Input
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1664"></A>
<P>Position of the row in the rowset on which to perform the operation specified with the <I>fOption</I> argument. If <I>irow</I> is 0, the operation applies to every row in the rowset.
<BLOCKQUOTE>
<P>For additional information, see &quot;Comments.&quot;</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E1665"></A>
<P><I>fOption</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E1665"></A>
<P>Input
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1665"></A>
<P>Operation to perform:
<BLOCKQUOTE>
<P>SQL_POSITION
<BR>SQL_REFRESH
<BR>SQL_UPDATE
<BR>SQL_DELETE
<BR>SQL_ADD
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information, see &quot;Comments.&quot;</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=80 VALIGN=top >
<BLOCKQUOTE>
<P>UWORD
</BLOCKQUOTE></TD>
<TD WIDTH=93 VALIGN=top >
<A NAME="E7E1666"></A>
<P><I>fLock</I>
</TD><TD WIDTH=66 VALIGN=top >
<A NAME="E7E1666"></A>
<P>Input
</TD><TD WIDTH=213 VALIGN=top >
<A NAME="E7E1666"></A>
<P>Specifies how to lock the row after performing the operation specified in the <I>fOption</I> argument.
<BLOCKQUOTE>
<P>SQL_LOCK_NO_CHANGE
<BR>SQL_LOCK_EXCLUSIVE
<BR>SQL_LOCK_UNLOCK
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For more information, see &quot;Comments.&quot;</TD></TR></BLOCKQUOTE></TABLE>
<A NAME="E11E321"></A>
<H3>
<FONT FACE="Arial">Returns<A NAME="I98"></A></FONT></H3>
<BLOCKQUOTE>
<P>SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
</BLOCKQUOTE>
<A NAME="E11E322"></A>
<H3>
<FONT FACE="Arial">Diagnostics<A NAME="I99"></A></FONT></H3>
<BLOCKQUOTE>
<P>When <B>SQLSetPos</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>SQLSetPos</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="E7E1667"></A>
<P>Error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1667"></A>
<P>Description</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01000
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1668"></A>
<P>General warning
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1668"></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="E7E1669"></A>
<P>Data truncated
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1669"></A>
<P>The argument <I>fOption</I> was SQL_ADD or SQL_UPDATE and the value specified for a character or binary column exceeded the maximum length of the associated table column. (Function returns SQL_SUCCESS_WITH_INFO.)
<BLOCKQUOTE>
<P>The argument <I>fOption</I> was SQL_ADD or SQL_UPDATE and the fractional part of the value specified for a numeric column was truncated. (Function returns SQL_SUCCESS_WITH_INFO.)
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The argument <I>fOption</I> was SQL_ADD or SQL_UPDATE and a timestamp value specified for a date or time column was truncated. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01S01
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1670"></A>
<P>Error in row
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1670"></A>
<P>The <I>irow</I> argument was 0 and an error occurred in one or more rows while performing the operation specified with the <I>fOption</I> argument. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01S03
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1671"></A>
<P>No rows updated or deleted
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1671"></A>
<P>The argument <I>fOption</I> was SQL_UPDATE or SQL_DELETE and no rows were updated or deleted. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>01S04
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1672"></A>
<P>More than one row updated or deleted
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1672"></A>
<P>The argument <I>fOption</I> was SQL_UPDATE or SQL_DELETE and more than one row was updated or deleted. (Function returns SQL_SUCCESS_WITH_INFO.)</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>21S02
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1673"></A>
<P>Degree of derived table does not match column list
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1673"></A>
<P>The argument <I>fOption</I> was SQL_ADD or SQL_UPDATE and no columns were bound with <B>SQLBindCol</B>.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>22003
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1674"></A>
<P>Numeric value out of range
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1674"></A>
<P>The argument <I>fOption</I> was SQL_ADD or SQL_UPDATE and the whole part of a numeric value was truncated.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>22005
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1675"></A>
<P>Error in assignment
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1675"></A>
<P>The argument <I>fOption</I> was SQL_ADD or SQL_UPDATE and a value was incompatible with the data type of the associated column.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>22008
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1676"></A>
<P>Datetime field overflow
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1676"></A>
<P>The argument <I>fOption</I> was SQL_ADD or SQL_UPDATE and a date, time, or timestamp value was, respectively, an invalid date, time, or timestamp.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>23000
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1677"></A>
<P>Integrity constraint violation
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1677"></A>
<P>The argument <I>fOption</I> was SQL_ADD or SQL_UPDATE and a value was NULL for a column defined as NOT NULL in the associated column or some other integrity constraint was violated.
<BLOCKQUOTE>
<P>The argument <I>fOption</I> was SQL_ADD and a column that was not bound with <B>SQLBindCol</B> is defined as NOT NULL or has no default.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>24000
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1678"></A>
<P>Invalid cursor state
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1678"></A>
<P>(DM) The <I>hstmt</I> was in an executed state but no result set was associated with the <I>hstmt</I>.
<BLOCKQUOTE>
<P>(DM) A cursor was open on the <I>hstmt</I> but <B>SQLFetch</B> or <B>SQLExtendedFetch</B> had not been called.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>A cursor was open on the <I>hstmt</I> and <B>SQLExtendedFetch</B> had been called, but the cursor was positioned before the start of the result set or after the end of the result set.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The argument <I>fOption</I> was SQL_DELETE, SQL_REFRESH, or SQL_UPDATE and the cursor was positioned before the start of the result set or after the end of the result set.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>42000
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1679"></A>
<P>Syntax error or access violation
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1679"></A>
<P>The driver was unable to lock the row as needed to perform the operation requested in the argument <I>fOption</I>.
<BLOCKQUOTE>
<P>The driver was unable to lock the row as requested in the argument <I>fLock</I>.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>IM001
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1680"></A>
<P>Driver does not support this function
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1680"></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>S0023
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1681"></A>
<P>No default for column
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1681"></A>
<P>The <I>fOption</I> argument was SQL_ADD and a column that was not bound did not have a default value and could not be set to NULL.
<BLOCKQUOTE>
<P>The <I>fOption</I> argument was SQL_ADD, the length specified in the <I>pcbValue</I> buffer bound by <B>SQLBindCol</B> was SQL_IGNORE, and the column did not have a default value.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1000
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1682"></A>
<P>General error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1682"></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="E7E1683"></A>
<P>Memory allocation failure
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1683"></A>
<P>The driver was unable to allocate memory required to support execution or completion of the function.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1008
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1684"></A>
<P>Operation canceled
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1684"></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=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1009
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1685"></A>
<P>Invalid argument value
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1685"></A>
<P>(DM) The value specified for the argument <I>fOption</I> was invalid.
<BLOCKQUOTE>
<P>(DM) The value specified for the argument <I>fLock</I> was invalid.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The argument <I>irow</I> was greater than the number of rows in the rowset and the <I>fOption</I> argument was not SQL_ADD.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The value specified for the argument <I>fOption</I> was SQL_ADD, SQL_UPDATE, or SQL_DELETE, the value specified for the argument <I>fLock</I> was SQL_LOCK_NO_CHANGE, and the SQL_CONCURRENCY statement option was SQL_CONCUR_READ_ONLY.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1010
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1686"></A>
<P>Function sequence error
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1686"></A>
<P>(DM) The specified <I>hstmt</I> was not in an executed state. The function was called without first calling <B>SQLExecDirect</B>, <B>SQLExecute</B>, or a catalog function.
<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=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1090
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1687"></A>
<P>Invalid string or buffer length
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1687"></A>
<P>The <I>fOption</I> argument was SQL_ADD or SQL_UPDATE, a data value was a null pointer, and the column length value was not 0, SQL_DATA_AT_EXEC, SQL_IGNORE, SQL_NULL_DATA, or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET.
<BLOCKQUOTE>
<P>The <I>fOption</I> argument was SQL_ADD or SQL_UPDATE, a data value was not a null pointer, and the column length value was less than 0, but not equal to SQL_DATA_AT_EXEC, SQL_IGNORE, SQL_NTS, or SQL_NULL_DATA, or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1107
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1688"></A>
<P>Row value out of range
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1688"></A>
<P>The value specified for the argument <I>irow</I> was greater than the number of rows in the rowset and the <I>fOption</I> argument was not SQL_ADD.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1109
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1689"></A>
<P>Invalid cursor position
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1689"></A>
<P>The cursor associated with the <I>hstmt</I> was defined as forward only, so the cursor could not be positioned within the rowset. See the description for the SQL_CURSOR_TYPE option in <B>SQLSetStmtOption</B>.
<BLOCKQUOTE>
<P>The <I>fOption</I> argument was SQL_REFRESH, SQL_UPDATE, or SQL_DELETE and the value in the <I>rgfRowStatus</I> array for the row specified by the <I>irow</I> argument was SQL_ROW_DELETED or SQL_ROW_ERROR.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1C00
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1690"></A>
<P>Driver not capable
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1690"></A>
<P>The driver or data source does not support the operation requested in the <I>fOption</I> argument or the <I>fLock</I> argument.</TD>
</TR>
<TR>
<TD WIDTH=100 VALIGN=top >
<BLOCKQUOTE>
<P>S1T00
</BLOCKQUOTE></TD>
<TD WIDTH=126 VALIGN=top >
<A NAME="E7E1691"></A>
<P>Timeout expired
</TD><TD WIDTH=226 VALIGN=top >
<A NAME="E7E1691"></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="E11E323"></A>
<H3>
<FONT FACE="Arial">Comments</FONT></H3>
<BLOCKQUOTE>
<A NAME="E12E59"></A>
<H4>
<FONT><I>irow</I> Argument<A NAME="I100"></A><A NAME="I101"></A><A NAME="I102"></A><A NAME="I103"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>irow</I> argument specifies the number of the row in the rowset on which to perform the operation specified by the <I>fOption</I> argument. If <I>irow</I> is 0, the operation applies to every row in the rowset. Except for the SQL_ADD operation, <I>irow</I> must be a value from 0 to the number of rows in the rowset. For the SQL_ADD operation, <I>irow</I> can be any value; generally it is either 0 (to add as many rows as there are in the rowset) or the number of rows in the rowset plus 1 (to add the data from an extra row of buffers allocated for this purpose).<A NAME="I104"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note In the C language, arrays are 0-based, while the <I>irow</I> argument is 1-based. For example, to update the fifth row of the rowset, an application modifies the rowset buffers at array index 4, but specifies an <I>irow</I> of 5.<A NAME="I105"></A><A NAME="I106"></A><A NAME="I107"></A><A NAME="I108"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>All operations except for SQL_ADD position the cursor on the row specified by <I>irow</I>; the SQL_ADD operation does not change the cursor position. The following operations require a cursor position:<A NAME="I109"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Positioned update and delete statements.<A NAME="I110"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Calls to <B>SQLGetData</B>.<A NAME="I111"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Calls to <B>SQLSetPos</B> with the SQL_DELETE, SQL_REFRESH, and SQL_UPDATE options.<A NAME="I112"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>For example, if the cursor is positioned on the second row of the rowset, a positioned delete statement deletes that row; if it is positioned on the entire rowset (<I>irow</I> is 0), a positioned delete statement deletes every row in the rowset.<A NAME="I113"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application can specify a cursor position when it calls <B>SQLSetPos</B>. Generally, it calls <B>SQLSetPos</B> with the SQL_POSITION or SQL_REFRESH operation to position the cursor before executing a positioned update or delete statement or calling <B>SQLGetData</B>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E60"></A>
<H4>
<FONT><I>fOption</I> Argument<A NAME="I114"></A><A NAME="I115"></A><A NAME="I116"></A><A NAME="I117"></A><A NAME="I118"></A><A NAME="I119"></A><A NAME="I120"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>fOption</I> argument supports the following operations. To determine which options are supported by a data source, an application calls <B>SQLGetInfo</B> with the SQL_POS_OPERATIONS information type.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=146 VALIGN=top >
<BLOCKQUOTE>
<P><B><I>fOption</I></B><B> Argument</B>
</BLOCKQUOTE></TD>
<TD WIDTH=306 VALIGN=top >
<A NAME="E7E1692"></A>
<P>Operation</TD>
</TR>
<TR>
<TD WIDTH=146 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_POSITION
</BLOCKQUOTE></TD>
<TD WIDTH=306 VALIGN=top >
<A NAME="E7E1693"></A>
<P>The driver positions the cursor on the row specified by <I>irow</I>.
<BLOCKQUOTE>
<P>This is the same as the FALSE value of this argument in ODBC 1.0.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=146 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_REFRESH
</BLOCKQUOTE></TD>
<TD WIDTH=306 VALIGN=top >
<A NAME="E7E1694"></A>
<P>The driver positions the cursor on the row specified by <I>irow</I> and refreshes data in the rowset buffers for that row. For more information about how the driver returns data in the rowset buffers, see the descriptions of row-wise and column-wise binding in <B>SQLExtendedFetch</B>.
<BLOCKQUOTE>
<P>This is the same as the TRUE value of this argument in ODBC 1.0.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=146 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_UPDATE
</BLOCKQUOTE></TD>
<TD WIDTH=306 VALIGN=top >
<A NAME="E7E1695"></A>
<P>The driver positions the cursor on the row specified by <I>irow</I> and updates the underlying row of data with the values in the rowset buffers (the <I>rgbValue</I> argument in <B>SQLBindCol</B>). It retrieves the lengths of the data from the number-of-bytes buffers (the <I>pcbValue</I> argument in <B>SQLBindCol</B>). If the length of any column is SQL_IGNORE, the column is not updated. After updating the row, the driver changes the <I>rgfRowStatus</I> array specified in <B>SQLExtendedFetch</B> to SQL_ROW_UPDATED.</TD>
</TR>
<TR>
<TD WIDTH=146 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_DELETE
</BLOCKQUOTE></TD>
<TD WIDTH=306 VALIGN=top >
<A NAME="E7E1696"></A>
<P>The driver positions the cursor on the row specified by <I>irow</I> and deletes the underlying row of data. It changes the <I>rgfRowStatus</I> array specified in <B>SQLExtendedFetch</B> to SQL_ROW_DELETED. After the row has been deleted, positioned update and delete statements, calls to <B>SQLGetData</B> and calls to <B>SQLSetPos</B> with <I>fOption</I> set to anything except SQL_POSITION are not valid for the row.
<BLOCKQUOTE>
<P>Whether the row remains visible depends on the cursor type. For example, deleted rows are visible to static and keyset-driven cursors but invisible to dynamic cursors.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=146 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_ADD<A NAME="I121"></A>
</BLOCKQUOTE></TD>
<TD WIDTH=306 VALIGN=top >
<BLOCKQUOTE>
<P>The driver adds a new row of data to the data source. Where the row is added to the data source and whether it is visible in the result set is driver-defined.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The driver retrieves the data from the rowset buffers (the <I>rgbValue</I> argument in <B>SQLBindCol</B>) according to the value of the <I>irow</I> argument. It retrieves the lengths of the data from the number-of-bytes buffers (the <I>pcbValue</I> argument in <B>SQLBindCol</B>). Generally, the application allocates an extra row of buffers for this purpose.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>For columns not bound to the rowset buffers, the driver uses default values (if they are available) or NULL values (if default values are not available). For columns with a length of SQL_IGNORE, the driver uses default values.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If <I>irow</I> is less than or equal to the rowset size, the driver changes the <I>rgfRowStatus</I> array specified in <B>SQLExtendedFetch</B> to SQL_ROW_ADDED after adding the row. At this point, the rowset buffers do not match the cursors for the row. To restore the rowset buffers to match the data in the cursor, an application calls <B>SQLSetPos</B> with the SQL_REFRESH option.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>This operation does not affect the cursor position.</TD></TR></BLOCKQUOTE></TABLE>
<BLOCKQUOTE>
<A NAME="E12E61"></A>
<H4>
<FONT><I>fLock</I> Argument<A NAME="I122"></A><A NAME="I123"></A><A NAME="I124"></A><A NAME="I125"></A><A NAME="I126"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>fLock</I> argument provides a way for applications to control concurrency and simulate transactions on data sources that do not support them. Generally, data sources that support concurrency levels and transactions will only support the SQL_LOCK_NO_CHANGE value of the <I>fLock</I> argument.<A NAME="I127"></A><A NAME="I128"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>fLock</I> argument specifies the lock state of the row after <B>SQLSetPos</B> has been executed. To simulate a transaction, an application uses the SQL_LOCK_RECORD macro to lock each of the rows in the transaction. It then uses the SQL_UPDATE_RECORD or SQL_DELETE_RECORD macro to update or delete each row; the driver may temporarily change the lock state of the row while performing the operation specified by the <I>fOption</I> argument. Finally, it uses the SQL_LOCK_RECORD macro to unlock each row. For an example of how an application might do this, see the second code example. Note that if the driver is unable to lock the row either to perform the requested operation or to satisfy the <I>fLock</I> argument, it returns SQL_ERROR and SQLSTATE 42000 (Syntax error or access violation).<A NAME="I129"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Although the <I>fLock</I> argument is specified for an <I>hstmt</I>, the lock accords the same privileges to all <I>hstmts</I> on the connection. In particular, a lock that is acquired by one <I>hstmt</I> on a connection can be unlocked by a different <I>hstmt</I> on the same connection.<A NAME="I130"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>A row locked through <B>SQLSetPos</B> remains locked until the application calls <B>SQLSetPos</B> for the row with <I>fLock</I> set to SQL_LOCK_UNLOCK or the application calls <B>SQLFreeStmt</B> with the SQL_CLOSE or SQL_DROP option.<A NAME="I131"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The <I>fLock</I> argument supports the following types of locks. To determine which locks are supported by a data source, an application calls <B>SQLGetInfo</B> with the SQL_LOCK_TYPES information type.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P><B><I>fLock</I></B><B> Argument</B>
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1697"></A>
<P>Lock Type</TD>
</TR>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_LOCK_NO_CHANGE
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1698"></A>
<P>The driver or data source ensures that the row is in the same locked or unlocked state as it was before <B>SQLSetPos</B> was called. This value of <I>fLock</I> allows data sources that do not support explicit row-level locking to use whatever locking is required by the current concurrency and transaction isolation levels.
<BLOCKQUOTE>
<P>This is the same as the FALSE value of the <I>fLock</I> argument in ODBC 1.0.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_LOCK_EXCLUSIVE
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1699"></A>
<P>The driver or data source locks the row exclusively. An <I>hstmt</I> on a different <I>hdbc</I> or in a different application cannot be used to acquire any locks on the row.
<BLOCKQUOTE>
<P>This is the same as the TRUE value of the <I>fLock</I> argument in ODBC 1.0.</TD>
</TR>
</BLOCKQUOTE>
<TR>
<TD WIDTH=173 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_LOCK_UNLOCK
</BLOCKQUOTE></TD>
<TD WIDTH=280 VALIGN=top >
<A NAME="E7E1700"></A>
<P>The driver or data source unlocks the row.</TD></TR></TABLE>
<BLOCKQUOTE>
<P>For the add, update, and delete operations in <B>SQLSetPos</B>, the application uses the <I>fLock</I> argument as follows:<A NAME="I132"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>To guarantee that a row does not change after it is retrieved, an application calls <B>SQLSetPos</B> with <I>fOption</I> set to SQL_REFRESH and <I>fLock</I> set to SQL_LOCK_EXCLUSIVE.<A NAME="I133"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the application sets <I>fLock</I> to SQL_LOCK_NO_CHANGE, the driver guarantees an update, or delete operation will succeed only if the application specified SQL_CONCUR_LOCK for the SQL_CONCURRENCY statement option.<A NAME="I134"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the application specifies SQL_CONCUR_ROWVER or SQL_CONCUR_VALUES for the SQL_CONCURRENCY statement option, the driver compares row versions or values and rejects the operation if the row has changed since the application fetched the row.<A NAME="I135"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If the application specifies SQL_CONCUR_READ_ONLY for the SQL_CONCURRENCY statement option, the driver rejects any update or delete operation.<A NAME="I136"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>For more information about the SQL_CONCURRENCY statement option, see <B>SQLSetStmtOption</B>.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E62"></A>
<H4>
<FONT>Using SQLSetPos<A NAME="I137"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Before an application calls <B>SQLSetPos</B>, it must:<A NAME="I138"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. If the application will call <B>SQLSetPos</B> with <I>fOption</I> set to SQL_ADD or SQL_UPDATE, call <B>SQLBindCol</B> for each column to specify its data type and associate storage for the column&#146;s data and length.<A NAME="I139"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>2. Call <B>SQLExecDirect</B>, <B>SQLExecute</B>, or a catalog function to create a result set.<A NAME="I140"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>3. Call <B>SQLExtendedFetch</B> to retrieve the data.<A NAME="I141"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>To delete data with <B>SQLSetPos</B>, an application:<A NAME="I142"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Calls <B>SQLSetPos</B> with <I>irow</I> set to the number of the row to delete.<A NAME="I143"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>An application can pass the value for a column either in the <I>rgbValue</I> buffer or with one or more calls to <B>SQLPutData</B>. Columns whose data is passed with <B>SQLPutData</B> are known as <I>data-at-execution</I> columns. These are commonly used to send data for SQL_LONGVARBINARY and SQL_LONGVARCHAR columns and can be mixed with other columns.<A NAME="I144"></A><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>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>To update or add data with <B>SQLSetPos</B>, an application:<A NAME="I153"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Places values in the <I>rgbValue</I> and <I>pcbValue</I> buffers bound with <B>SQLBindCol</B>:
</BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For normal columns, the application places the new column value in the <I>rgbValue</I> buffer and the length of that value in the <I>pcbValue</I> buffer. If the row is being updated and the column is not to be changed, the application places SQL_IGNORE in the <I>pcbValue</I> buffer.
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>For data-at-execution columns, the application places an application-defined value, such as the column number, in the <I>rgbValue</I> buffer. The value can be used later to identify the column. It places the result of the SQL_LEN_DATA_AT_EXEC(<I>length</I>) macro in the <I>pcbValue</I> buffer. If the SQL data type of the column 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, it must be a nonnegative value and is ignored.<A NAME="I154"></A>
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<LI>2. Calls <B>SQLSetPos</B> or uses an <B>SQLSetPos</B> macro to update or add the row of data.
</BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If there are no data-at-execution columns, the process is complete.
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If there are any data-at-execution columns, the function returns SQL_NEED_DATA.<A NAME="I155"></A>
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<LI>3. Calls <B>SQLParamData</B> to retrieve the address of the <I>rgbValue</I> buffer for the first data-at-execution column to be processed. The application retrieves the application-defined value from the <I>rgbValue</I> buffer.
</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.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>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="I156"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>4. Calls <B>SQLPutData</B> one or more times to send data for the column. 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 column 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="I157"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>5. Calls <B>SQLParamData</B> again to signal that all data has been sent for the column.
</BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If there are more data-at-execution columns, <B>SQLParamData</B> returns SQL_NEED_DATA and the address of the <I>rgbValue</I> buffer for the next data-at-execution column to be processed. The application repeats steps 4 and 5.
</BLOCKQUOTE></BLOCKQUOTE>
<BLOCKQUOTE>
<BLOCKQUOTE>
<LI>If there are no more data-at-execution columns, the process is complete. If the statement was executed successfully, <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 <B>SQLSetPos</B>.<A NAME="I158"></A>
</BLOCKQUOTE></BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>After <B>SQLSetPos</B> returns SQL_NEED_DATA, and before data is sent for all data-at-execution columns, the operation 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="I159"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the application calls <B>SQLCancel</B> while the driver still needs data for data-at-execution columns, the driver cancels the operation; the application can then call <B>SQLSetPos</B> again; canceling does not affect the cursor state or the current cursor position. If the application calls <B>SQLParamData</B> or <B>SQLPutData</B> after canceling the operation, the function returns SQL_ERROR and SQLSTATE S1008 (Operation canceled).
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E63"></A>
<H4>
<FONT>Performing Bulk Operations<A NAME="I160"></A><A NAME="I161"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the <I>irow</I> argument is 0, the driver performs the operation specified in the <I>fOption</I> argument for every row in the rowset. If an error occurs that pertains to the entire rowset, such as SQLSTATE S1T00 (Timeout expired), the driver returns SQL_ERROR and the appropriate SQLSTATE. The contents of the rowset buffers are undefined and the cursor position is unchanged.<A NAME="I162"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If an error occurs that pertains to a single row, the driver:<A NAME="I163"></A><A NAME="I164"></A><A NAME="I165"></A><A NAME="I166"></A><A NAME="I167"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Sets the element in the <I>rgfRowStatus</I> array for the row to SQL_ROW_ERROR.<A NAME="I168"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Posts SQLSTATE 01S01 (Error in row) in the error queue.<A NAME="I169"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Posts one or more additional SQLSTATEs for the error after SQLSTATE 01S01 (Error in row) in the error queue.<A NAME="I170"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>After it has processed the error or warning, the driver continues the operation for the remaining rows in the rowset and returns SQL_SUCCESS_WITH_INFO. Thus, for each row that returned an error, the error queue contains SQLSTATE 01S01 (Error in row) followed by zero or more additional SQLSTATEs.<A NAME="I171"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If the driver returns any warnings, such as SQLSTATE 01004 (Data truncated), it returns warnings that apply to the entire rowset or to unknown rows in the rowset before it returns the error information that applies to specific rows. It returns warnings for specific rows along with any other error information about those rows.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E64"></A>
<H4>
<FONT>SQLSetPos Macros<A NAME="I172"></A><A NAME="I173"></A><A NAME="I174"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>As an aid to programming, the following macros for calling <B>SQLSetPos</B> are defined in the SQLEXT.H file.
</BLOCKQUOTE>
<TABLE WIDTH=800 >
<TR>
<TD WIDTH=246 VALIGN=top >
<BLOCKQUOTE>
<P><B>Macro name</B>
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E1701"></A>
<P>Function call</TD>
</TR>
<TR>
<TD WIDTH=246 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_POSITION_TO(<I>hstmt</I>, <I>irow</I>)
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E1702"></A>
<P><B>SQLSetPos</B>(<I>hstmt</I>, <I>irow</I>, SQL_POSITION, 
<BR>SQL_LOCK_NO_CHANGE)</TD>
</TR>
<TR>
<TD WIDTH=246 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_LOCK_RECORD(<I>hstmt</I>, <I>irow</I>, <I>fLock</I>)
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E1703"></A>
<P><B>SQLSetPos</B>(<I>hstmt</I>, <I>irow</I>, SQL_POSITION, <I>fLock</I>)</TD>
</TR>
<TR>
<TD WIDTH=246 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_REFRESH_RECORD(<I>hstmt</I>, <I>irow</I>, <I>fLock</I>)
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E1704"></A>
<P><B>SQLSetPos</B>(<I>hstmt</I>, <I>irow</I>, SQL_REFRESH, <I>fLock</I>)</TD>
</TR>
<TR>
<TD WIDTH=246 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_UPDATE_RECORD(<I>hstmt</I>, <I>irow</I>)
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E1705"></A>
<P><B>SQLSetPos</B>(<I>hstmt</I>, <I>irow</I>, SQL_UPDATE, 
<BR>SQL_LOCK_NO_CHANGE)</TD>
</TR>
<TR>
<TD WIDTH=246 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_DELETE_RECORD(<I>hstmt</I>, <I>irow</I>)
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E1706"></A>
<P><B>SQLSetPos</B>(<I>hstmt</I>, <I>irow</I>, SQL_DELETE, 
<BR>SQL_LOCK_NO_CHANGE)</TD>
</TR>
<TR>
<TD WIDTH=246 VALIGN=top >
<BLOCKQUOTE>
<P>SQL_ADD_RECORD(<I>hstmt</I>, <I>irow</I>)
</BLOCKQUOTE></TD>
<TD WIDTH=206 VALIGN=top >
<A NAME="E7E1707"></A>
<P><B>SQLSetPos</B>(<I>hstmt</I>, <I>irow</I>, SQL_ADD, 
<BR>SQL_LOCK_NO_CHANGE)</TD></TR></TABLE>
<A NAME="E11E324"></A>
<H3>
<FONT FACE="Arial">Code Example<A NAME="I175"></A></FONT></H3>
<BLOCKQUOTE>
<P>In the following example, an application allows a user to browse the EMPLOYEE table and update employee birthdays. The cursor is keyset-driven with a rowset size of 20 and uses optimistic concurrency control comparing row versions. After each rowset is fetched, the application prints them and allows the user to select and update an employee&#146;s birthday. The application uses <B>SQLSetPos</B> to position the cursor on the selected row and performs a positioned update of the row. (Error handling is omitted for clarity.)
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">#define ROWS 20
#define NAME_LEN 30
#define BDAY_LEN 11
UCHAR  szName[ROWS][NAME_LEN], szBirthday[ROWS][BDAY_LEN], szReply[3];
SDWORD cbName[ROWS], cbBirthday[ROWS];
UWORD  rgfRowStatus[ROWS];
UDWORD crow, irow;
HSTMT  hstmtS, hstmtU;
SQLSetStmtOption(hstmtS, SQL_CONCURRENCY, SQL_CONCUR_ROWVER);
<BR>SQLSetStmtOption(hstmtS, SQL_CURSOR_TYPE, SQL_CURSOR_KEYSET_DRIVEN);
SQLSetStmtOption(hstmtS, SQL_ROWSET_SIZE, ROWS);
SQLSetCursorName(hstmtS, &quot;C1&quot;, SQL_NTS);
SQLExecDirect(hstmtS,
<BR>           &quot;SELECT NAME, BIRTHDAY FROM EMPLOYEE FOR UPDATE OF BIRTHDAY&quot;,
<BR>           SQL_NTS);
SQLBindCol(hstmtS, 1, SQL_C_CHAR, szName, NAME_LEN, cbName);
SQLBindCol(hstmtS, 1, SQL_C_CHAR, szBirthday, BDAY_LEN,
<BR>           cbBirthday);
while (SQLExtendedFetch(hstmtS, FETCH_NEXT, 0, &amp;crow, rgfRowStatus) !=
<BR>       SQL_ERROR) {
   for (irow = 0; irow &lt; crow; irow++) {
      if (rgfRowStatus[irow] != SQL_ROW_DELETED)
         printf(&quot;%d %-*s %*s\n&quot;, irow, NAME_LEN-1, szName[irow],
<BR>                BDAY_LEN-1, szBirthday[irow]);
   }
   while (TRUE) {
      printf(&quot;\nRow number to update?&quot;);
      gets(szReply);
      irow = atoi(szReply);
      if (irow &gt; 0 &amp;&amp; irow &lt;= crow) {
         printf(&quot;\nNew birthday?&quot;);
         gets(szBirthday[irow-1]);
         SQLSetPos(hstmtS, irow, SQL_POSITION, SQL_LOCK_NO_CHANGE);
         SQLPrepare(hstmtU,
<BR>            &quot;UPDATE EMPLOYEE SET BIRTHDAY=? WHERE CURRENT OF C1&quot;,
<BR>            SQL_NTS);
         SQLBindParameter(hstmtU, 1, SQL_PARAM_INPUT,
<BR>                          SQL_C_CHAR, SQL_DATE,
<BR>                          BDAY_LEN, 0, szBirthday, 0, NULL);
         SQLExecute(hstmtU);
      } else if (irow == 0) {
         break;
      }
   }
}<A NAME="I176"></A></FONT></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>In the following code fragment, an application simulates a transaction for rows 1 and 2. It locks the rows, updates them, then unlocks them. The code uses the <B>SQLSetPos</B> macros.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>
<FONT FACE="Courier New">/* Lock rows 1 and 2                                      */
SQL_LOCK_RECORD(hstmt, 1, SQL_LOCK_EXCLUSIVE);
SQL_LOCK_RECORD(hstmt, 2, SQL_LOCK_EXCLUSIVE);
/* Modify the rowset buffers for rows 1 and 2 (not shown).*/
/* Update rows 1 and 2.                                   */
SQL_UPDATE_RECORD(hstmt, 1);
SQL_UPDATE_RECORD(hstmt, 2);
/* Unlock rows 1 and 2                                    */
SQL_LOCK_RECORD(hstmt, 1, SQL_LOCK_UNLOCK);
SQL_LOCK_RECORD(hstmt, 2, SQL_LOCK_UNLOCK);</FONT></PRE></BLOCKQUOTE>
<A NAME="E11E325"></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="E7E1708"></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="E7E1709"></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="E7E1710"></A>
<P><B>SQLCancel</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="E7E1711"></A>
<P><B>SQLExtendedFetch</B> (extension)</TD>
</TR>
<TR>
<TD WIDTH=250 VALIGN=top >
<BLOCKQUOTE>
<P>Setting a statement option
</BLOCKQUOTE></TD>
<TD WIDTH=202 VALIGN=top >
<A NAME="E7E1712"></A>
<P><B>SQLSetStmtOption</B> (extension)</TD></TR></TABLE><P ALIGN=CENTER>
<A HREF="prguid22.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="prguid24.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>