287 lines
17 KiB
HTML
287 lines
17 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE html
|
||
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html lang="en-us" xml:lang="en-us">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<meta name="security" content="public" />
|
||
<meta name="Robots" content="index,follow" />
|
||
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
<meta name="DC.Type" content="reference" />
|
||
<meta name="DC.Title" content="SQLSetStmtAttr - Set a statement attribute" />
|
||
<meta name="DC.Relation" scheme="URI" content="rzadphdapi.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="rzadpfnsstmo.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="rzadpfetchsc.htm" />
|
||
<meta name="copyright" content="(C) Copyright IBM Corporation 1999, 2006" />
|
||
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1999, 2006" />
|
||
<meta name="DC.Format" content="XHTML" />
|
||
<meta name="DC.Identifier" content="rzadpfnsstma" />
|
||
<meta name="DC.Language" content="en-us" />
|
||
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
<!-- US Government Users Restricted Rights -->
|
||
<!-- Use, duplication or disclosure restricted by -->
|
||
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
<title>SQLSetStmtAttr</title>
|
||
</head>
|
||
<body id="rzadpfnsstma"><a name="rzadpfnsstma"><!-- --></a>
|
||
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
<h1 class="topictitle1">SQLSetStmtAttr - Set a statement attribute</h1>
|
||
<div><div class="section"></div>
|
||
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLSetStmtAttr()</samp> sets
|
||
an attribute of a specific statement handle. To set an option for all statement
|
||
handles associated with a connection handle, the application can call <samp class="codeph">SQLSetConnectOption()</samp>.</p>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLSetStmtAttr (SQLHSTMT hstmt,
|
||
SQLINTEGER fAttr,
|
||
SQLPOINTER vParam,
|
||
SQLINTEGER sLen);</pre>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Function arguments</h4>
|
||
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="all"><caption>Table 1. SQLSetStmtAttr arguments</caption><thead align="left"><tr><th align="left" valign="top" width="20%" id="d0e57">Data type</th>
|
||
<th align="left" valign="top" width="20%" id="d0e59">Argument</th>
|
||
<th align="left" valign="top" width="20%" id="d0e61">Use</th>
|
||
<th align="left" valign="top" width="40%" id="d0e63">Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr><td align="left" valign="top" width="20%" headers="d0e57 ">SQLHSTMT</td>
|
||
<td align="left" valign="top" width="20%" headers="d0e59 "><em>hstmt</em></td>
|
||
<td align="left" valign="top" width="20%" headers="d0e61 ">Input</td>
|
||
<td align="left" valign="top" width="40%" headers="d0e63 ">Statement handle.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="20%" headers="d0e57 ">SQLINTEGER</td>
|
||
<td align="left" valign="top" width="20%" headers="d0e59 "><em>fAttr</em></td>
|
||
<td align="left" valign="top" width="20%" headers="d0e61 ">Input</td>
|
||
<td align="left" valign="top" width="40%" headers="d0e63 ">Attribute to set. Refer to <a href="#rzadpfnsstma__tbstmto">Table 2</a> for
|
||
the list of settable statement attributes.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="20%" headers="d0e57 ">SQLPOINTER</td>
|
||
<td align="left" valign="top" width="20%" headers="d0e59 "><em>vParam</em></td>
|
||
<td align="left" valign="top" width="20%" headers="d0e61 ">Input</td>
|
||
<td align="left" valign="top" width="40%" headers="d0e63 ">Value associated with <em>fAttr</em>. <em>vParam</em> can
|
||
be a 32-bit integer value or a character string.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="20%" headers="d0e57 ">SQLINTEGER</td>
|
||
<td align="left" valign="top" width="20%" headers="d0e59 "><em>sLen</em></td>
|
||
<td align="left" valign="top" width="20%" headers="d0e61 ">Input</td>
|
||
<td align="left" valign="top" width="40%" headers="d0e63 ">Length of data if data is a character string;
|
||
otherwise, unused.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Usage</h4><p>Statement options for an <em>hstmt</em> remain
|
||
in effect until they are changed by another call to <samp class="codeph">SQLSetStmtAttr()</samp> or
|
||
the <em>hstmt</em> is dropped by calling <samp class="codeph">SQLFreeStmt()</samp> with
|
||
the SQL_DROP option. Calling <samp class="codeph">SQLFreeStmt()</samp> with the SQL_CLOSE,
|
||
SQL_UNBIND, or SQL_RESET_PARAMS options does not reset the statement options.</p>
|
||
<div class="p">The
|
||
format of information set through <em>vParam</em> depends on the specified <em>fOption</em>.
|
||
The format of each is noted in <a href="#rzadpfnsstma__tbstmto">Table 2</a>.
|
||
|
||
<div class="tablenoborder"><img src="./delta.gif" alt="Start of change" /><a name="rzadpfnsstma__tbstmto"><!-- --></a><table cellpadding="4" cellspacing="0" summary="" id="rzadpfnsstma__tbstmto" width="100%" frame="hsides" border="1" rules="all"><caption>Table 2. Statement
|
||
attributes</caption><thead align="left"><tr><th align="left" valign="top" width="50%" id="d0e155"><em>fAttr</em></th>
|
||
<th align="left" valign="top" width="50%" id="d0e158">Contents</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_APP_PARAM_DESC</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 "><em>VParam</em> must be a descriptor handle.
|
||
The specified descriptor serves as the application parameter descriptor for
|
||
later calls to <samp class="codeph">SQLExecute()</samp> and <samp class="codeph">SQLExecDirect()</samp> on
|
||
the statement handle.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_APP_ROW_DESC</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 "><em>VParam</em> must be a descriptor handle.
|
||
The specified descriptor serves as the application row descriptor for later
|
||
calls to <samp class="codeph">SQLFetch()</samp> on the statement handle.</td>
|
||
</tr>
|
||
<tr><td valign="top" width="50%" headers="d0e155 ">SQL_ATTR_BIND_TYPE</td>
|
||
<td valign="top" width="50%" headers="d0e158 ">Specifies whether row-wise or column-wise binding is
|
||
used. <ul><li>SQL_BIND_BY_ROW – Binding is row-wise. This is the default. <p>When using
|
||
row-wise binding for a multiple row fetch, all of the data for a row is returned
|
||
in contiguous storage, followed by the data for the next row, and so on.</p>
|
||
</li>
|
||
<li>SQL_BIND_BY_COLUMN – Binding is column-wise. <p>When using column-wise
|
||
binding for a multiple row fetch, all of the data for each column is returned
|
||
in contiguous storage. The storage for each column need not be contiguous.
|
||
A different address is provided by the user for each column in the result
|
||
set, and it is the responsibility of the user to ensure that each address
|
||
has space for all the data to be retrieved.</p>
|
||
</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_CURSOR_HOLD</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 ">A 32-bit integer value that specifies if
|
||
cursors opened for this statement handle should be held. <ul><li>SQL_FALSE – An open cursor for this statement handle is closed on a commit
|
||
or rollback operation. This is the default.</li>
|
||
<li>SQL_TRUE – An open cursor for this statement handle is not closed on a
|
||
commit or rollback operation.</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_CURSOR_SCROLLABLE</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 ">A 32-bit integer value that specifies if
|
||
cursors opened for this statement handle should be scrollable. <ul><li>SQL_FALSE – Cursors are not scrollable, and <samp class="codeph">SQLFetchScroll()</samp> cannot
|
||
be used against them. This is the default.</li>
|
||
<li>SQL_TRUE – Cursors are scrollable. <samp class="codeph">SQLFetchScroll()</samp> can
|
||
be used to retrieve data from these cursors.</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr><td valign="top" width="50%" headers="d0e155 ">SQL_ATTR_CURSOR_SENSITIVITY </td>
|
||
<td valign="top" width="50%" headers="d0e158 ">A 32-bit integer value that specifies whether cursors
|
||
opened for this statement handle make visible the changes made to the result
|
||
set by another cursor. See <a href="../db2/rbafzmsth2clcu.htm" target="_blank">DECLARE CURSOR</a> for a more precise definition of the
|
||
following options:<ul><li>SQL_UNSPECIFIED – Cursors on the statement handle might make visible none,
|
||
some, or all such changes depending on the cursor type. This is the default.</li>
|
||
<li>SQL_INSENSITIVE – All valid cursors on the statement handle show the result
|
||
set without reflecting any changes made to it by any other cursor.</li>
|
||
<li>SQL_SENSITIVE – All valid cursors on the statement handle make visible
|
||
all changes made to a result by another cursor.</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_CURSOR_TYPE</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 ">A 32-bit integer value that specifies the
|
||
behavior of cursors opened for this statement handle. <ul><li>SQL_CURSOR_FORWARD_ONLY – Cursors are not scrollable, and the <samp class="codeph">SQLFetchScroll()</samp> function
|
||
cannot be used against them. This is the default.</li>
|
||
<li><img src="./delta.gif" alt="Start of change" />SQL_CURSOR_DYNAMIC – Cursors are scrollable except for
|
||
insensitive cursor sensitivity. The <samp class="codeph">SQLFetchScroll()</samp> function
|
||
can be used to retrieve data from these cursors.<img src="./deltaend.gif" alt="End of change" /></li>
|
||
<li><img src="./delta.gif" alt="Start of change" />SQL_CURSOR_STATIC – Cursors are scrollable except for
|
||
sensitive cursor sensitivity. The <samp class="codeph">SQLFetchScroll()</samp> function
|
||
can be used to retrieve data from these cursors. <img src="./deltaend.gif" alt="End of change" /></li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_EXTENDED_COL_INFO</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 ">A 32-bit integer value that specifies if
|
||
cursors opened for this statement handle should provide extended column information.
|
||
<ul><li>SQL_FALSE – This statement handle cannot be used on the <samp class="codeph">SQLColAttributes()</samp> function
|
||
to retrieve extended column information. This is the default. Setting this
|
||
attribute at the statement level overrides the connection level setting of
|
||
the attribute.</li>
|
||
<li>SQL_TRUE – This statement handle can be used on the <samp class="codeph">SQLColAttributes()</samp> function
|
||
to retrieve extended column information, such as base table, base schema,
|
||
base column, and label.</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_FOR_FETCH_ONLY</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 ">A 32-bit integer value that specifies whether
|
||
cursors opened for this statement handle should be read only: <ul><li>SQL_TRUE – Cursors are read-only and cannot be used for positioned update
|
||
or delete operations. This is the default unless SQL_ATTR_FOR_FETCH_ONLY environment
|
||
has been set to SQL_FALSE.</li>
|
||
<li>SQL_FALSE – Cursors can be used for positioned update or delete operations.</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_FULL_OPEN</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 ">A 32-bit integer value that specifies if
|
||
cursors opened for this statement handle should be full open operations. <ul><li>SQL_FALSE – Opening a cursor for this statement handle might use a cached
|
||
cursor for performance reasons. This is the default.</li>
|
||
<li>SQL_TRUE – Opening a cursor for this statement handle always forces a
|
||
full open operation of a new cursor.</li>
|
||
</ul>
|
||
</td>
|
||
</tr>
|
||
<tr><td valign="top" width="50%" headers="d0e155 ">SQL_ATTR_ROW_STATUS_PTR</td>
|
||
<td valign="top" width="50%" headers="d0e158 ">An output smallint pointer to specify an array of status
|
||
values at SQLFetchScroll(). The number of elements must equal the number of
|
||
rows in the row set (as defined by the SQL_ROWSET_SIZE attribute). A status
|
||
value SQL_ROW_SUCCESS for each row fetched is returned.<p>If the number of
|
||
rows fetched is less than the number of elements in the status array (that
|
||
is, less than the row set size), the remaining status elements are set to
|
||
SQL_ROW_NOROW. The number of rows fetched is returned in the output pointer.
|
||
This can be set by the SQLSetStmtAttr attribute SQL_ATTR_ROWS_FETCHED_PTR.</p>
|
||
<div class="p">DB2
|
||
UDB CLI cannot detect whether a row has been updated or deleted since the
|
||
start of the fetch. Therefore, the following ODBC defined status values are
|
||
not reported:<ul><li>SQL_ROW_DELETED.</li>
|
||
<li>SQL_ROW_UPDATED. </li>
|
||
</ul>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
<tr><td valign="top" width="50%" headers="d0e155 ">SQL_ATTR_ROWS_FETCHED_PTR</td>
|
||
<td valign="top" width="50%" headers="d0e158 ">An output integer pointer that contains the number of
|
||
rows actually fetched by <samp class="codeph">SQLFetchScroll()</samp>. If an error occurs
|
||
during processing, the pointer points to the ordinal position of the row (in
|
||
the row set) that precedes the row where the error occurred. If an error occurs
|
||
retrieving the first row, the pointer points to the value 0.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="50%" headers="d0e155 ">SQL_ATTR_ROWSET_SIZE</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e158 ">A 32-bit integer value that specifies the
|
||
number of rows in the row set. This is the number of rows returned by each
|
||
call to <samp class="codeph">SQLExtendedFetch()</samp>. The default value is 1.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<img src="./deltaend.gif" alt="End of change" /></div>
|
||
</div>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Return codes</h4><ul><li>SQL_SUCCESS</li>
|
||
<li>SQL_ERROR</li>
|
||
<li>SQL_INVALID_HANDLE</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Diagnostics</h4>
|
||
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 3. SQLStmtAttr SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="top" width="25%" id="d0e350">SQLSTATE</th>
|
||
<th align="left" valign="top" width="25%" id="d0e352">Description</th>
|
||
<th align="left" valign="top" width="50%" id="d0e354">Explanation</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr><td align="left" valign="top" width="25%" headers="d0e350 "><strong>40</strong>003 <strong>*</strong></td>
|
||
<td align="left" valign="top" width="25%" headers="d0e352 ">Statement completion unknown</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e354 ">The communication link between the CLI and
|
||
the data source fails before the function completes processing.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="25%" headers="d0e350 "><strong>HY</strong>000</td>
|
||
<td align="left" valign="top" width="25%" headers="d0e352 ">General error</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e354 ">An error occurred for which there is no specific
|
||
SQLSTATE and for which no implementation defined SQLSTATE is defined. The
|
||
error message returned by SQLError in the argument <em>szErrorMsg</em> describes
|
||
the error and its cause.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="25%" headers="d0e350 "><strong>HY</strong>001</td>
|
||
<td align="left" valign="top" width="25%" headers="d0e352 ">Memory allocation failure</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e354 ">The driver is unable to allocate memory required
|
||
to support the processing or completion of the function.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="25%" headers="d0e350 "><strong>HY</strong>009</td>
|
||
<td align="left" valign="top" width="25%" headers="d0e352 ">Argument value that is not valid</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e354 ">Given the specified <em>fAttr</em> value, a
|
||
value that is not valid is specified for the argument <em>vParam</em>. <p>An <em>fAttr</em> value
|
||
that is not valid is specified.</p>
|
||
<p>The argument <em>vParam</em> is a null
|
||
pointer.</p>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="25%" headers="d0e350 "><strong>HY</strong>010</td>
|
||
<td align="left" valign="top" width="25%" headers="d0e352 ">Function sequence error</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e354 ">The function is called out of sequence.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="25%" headers="d0e350 "><strong>HY</strong>C00</td>
|
||
<td align="left" valign="top" width="25%" headers="d0e352 ">Driver not capable</td>
|
||
<td align="left" valign="top" width="50%" headers="d0e354 ">The driver or the data sources does not support
|
||
the specified option.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div>
|
||
<div class="familylinks">
|
||
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzadphdapi.htm" title="This topic provides a description of each CLI function.">DB2 UDB CLI functions</a></div>
|
||
</div>
|
||
<div class="relref"><strong>Related reference</strong><br />
|
||
<div><a href="rzadpfnsstmo.htm">SQLSetStmtOption - Set statement option</a></div>
|
||
<div><a href="rzadpfetchsc.htm">SQLFetchScroll - Fetch from a scrollable cursor</a></div>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html> |