460 lines
20 KiB
HTML
460 lines
20 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<link rel="STYLESHEET" href="cx_Oracle.css" type='text/css' />
|
|
<link rel="first" href="cx_Oracle.html" title='cx_Oracle' />
|
|
<link rel='contents' href='contents.html' title="Contents" />
|
|
<link rel='last' href='about.html' title='About this document...' />
|
|
<link rel='help' href='about.html' title='About this document...' />
|
|
<link rel="next" href="varobj.html" />
|
|
<link rel="prev" href="connobj.html" />
|
|
<link rel="parent" href="cx_Oracle.html" />
|
|
<link rel="next" href="varobj.html" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name='aesop' content='information' />
|
|
<title>3. Cursor Objects</title>
|
|
</head>
|
|
<body>
|
|
<div class="navigation">
|
|
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
|
|
<table align="center" width="100%" cellpadding="0" cellspacing="2">
|
|
<tr>
|
|
<td class='online-navigation'><a rel="prev" title="2. connection Objects"
|
|
href="connobj.html"><img src='previous.png'
|
|
border='0' height='32' alt='Previous Page' width='32' /></a></td>
|
|
<td class='online-navigation'><a rel="parent" title="cx_Oracle"
|
|
href="cx_Oracle.html"><img src='up.png'
|
|
border='0' height='32' alt='Up one Level' width='32' /></a></td>
|
|
<td class='online-navigation'><a rel="next" title="4. variable Objects"
|
|
href="varobj.html"><img src='next.png'
|
|
border='0' height='32' alt='Next Page' width='32' /></a></td>
|
|
<td align="center" width="100%">cx_Oracle</td>
|
|
<td class='online-navigation'><a rel="contents" title="Table of Contents"
|
|
href="contents.html"><img src='contents.png'
|
|
border='0' height='32' alt='Contents' width='32' /></a></td>
|
|
<td class='online-navigation'><img src='blank.png'
|
|
border='0' height='32' alt='' width='32' /></td>
|
|
<td class='online-navigation'><img src='blank.png'
|
|
border='0' height='32' alt='' width='32' /></td>
|
|
</tr></table>
|
|
<div class='online-navigation'>
|
|
<b class="navlabel">Previous:</b>
|
|
<a class="sectref" rel="prev" href="connobj.html">2. Connection Objects</a>
|
|
<b class="navlabel">Up:</b>
|
|
<a class="sectref" rel="parent" href="cx_Oracle.html">cx_Oracle</a>
|
|
<b class="navlabel">Next:</b>
|
|
<a class="sectref" rel="next" href="varobj.html">4. Variable Objects</a>
|
|
</div>
|
|
<hr /></div>
|
|
</div>
|
|
<!--End of Navigation Panel-->
|
|
|
|
<h1><a name="SECTION005000000000000000000"></a><a name="cursorobj"></a>
|
|
<br>
|
|
3. Cursor Objects
|
|
</h1>
|
|
|
|
<p>
|
|
<dl><dt><b><tt id='l2h-79' xml:id='l2h-79'>arraysize</tt></b></dt>
|
|
<dd>
|
|
This read-write attribute specifies the number of rows to fetch at a time
|
|
internally and is the default number of rows to fetch with the fetchmany()
|
|
call. It defaults to 1 meaning to fetch a single row at a time. Note that
|
|
this attribute can drastically affect the performance of a query since it
|
|
directly affects the number of network round trips that need to be performed.
|
|
</dd></dl>
|
|
|
|
<p>
|
|
<dl><dt><b><tt id='l2h-80' xml:id='l2h-80'>bindarraysize</tt></b></dt>
|
|
<dd>
|
|
This read-write attribute specifies the number of rows to bind at a time and
|
|
is used when creating variables via setinputsizes() or var(). It defaults to
|
|
1 meaning to bind a single row at a time.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this attribute.
|
|
</dd></dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-81' xml:id='l2h-81' class="function">arrayvar</tt></b>(</nobr></td>
|
|
<td><var><var>dataType</var>, <var>value</var>, </var><big>[</big><var><var>size</var></var><big>]</big><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Create an array variable associated with the cursor of the given type and
|
|
size and return a variable object (<a href="varobj.html#varobj">4</a>). The value is either an
|
|
integer specifying the number of elements to allocate or it is a list and
|
|
the number of elements allocated is drawn from the size of the list. If the
|
|
value is a list, the variable is also set with the contents of the list. If
|
|
the size is not specified and the type is a string or binary, 4000 bytes
|
|
(maximum allowable by Oracle) is allocated. This is needed for passing arrays
|
|
to PL/SQL (in cases where the list might be empty and the type cannot be
|
|
determined automatically) or returning arrays from PL/SQL.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this method.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-82' xml:id='l2h-82' class="function">bindnames</tt></b>(</nobr></td>
|
|
<td><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Return the list of bind variable names bound to the statement. Note that the
|
|
statement must have been prepared first.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this method.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-83' xml:id='l2h-83' class="function">callfunc</tt></b>(</nobr></td>
|
|
<td><var><var>name</var>, <var>returnType</var>,
|
|
</var><big>[</big><var><var>parameters=[]</var></var><big>]</big><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Call a function with the given name. The return type is specified in the
|
|
same notation as is required by setinputsizes(). The sequence of parameters
|
|
must contain one entry for each argument that the function expects.
|
|
The result of the call is the return value of the function.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-84' xml:id='l2h-84' class="function">callproc</tt></b>(</nobr></td>
|
|
<td><var><var>name</var>, </var><big>[</big><var><var>parameters=[]</var></var><big>]</big><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Call a procedure with the given name. The sequence of parameters must contain
|
|
one entry for each argument that the procedure expects. The result of the
|
|
call is a modified copy of the input sequence. Input parameters are left
|
|
untouched; output and input/output parameters are replaced with possibly new
|
|
values.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-85' xml:id='l2h-85' class="function">close</tt></b>(</nobr></td>
|
|
<td><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Close the cursor now, rather than whenever __del__ is called. The cursor will
|
|
be unusable from this point forward; an Error exception will be raised if any
|
|
operation is attempted with the cursor.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><b><tt id='l2h-86' xml:id='l2h-86'>connection</tt></b></dt>
|
|
<dd>
|
|
This read-only attribute returns a reference to the connection object on
|
|
which the cursor was created.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> This attribute is an extension to the DB API definition but it
|
|
is mentioned in PEP 249 as an optional extension.
|
|
</dd></dl>
|
|
|
|
<p>
|
|
<dl><dt><b><tt id='l2h-87' xml:id='l2h-87'>description</tt></b></dt>
|
|
<dd>
|
|
This read-only attribute is a sequence of 7-item sequences. Each of these
|
|
sequences contains information describing one result column: (name, type,
|
|
display_size, internal_size, precision, scale, null_ok). This attribute will
|
|
be None for operations that do not return rows or if the cursor has not had
|
|
an operation invoked via the execute() method yet.
|
|
|
|
<p>
|
|
The type will be one of the type objects defined at the module level.
|
|
</dd></dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-88' xml:id='l2h-88' class="function">execute</tt></b>(</nobr></td>
|
|
<td><var><var>statement</var>, </var><big>[</big><var><var>parameters</var></var><big>]</big><var>,
|
|
<var>**keywordParameters</var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Execute a statement against the database. Parameters may be passed as a
|
|
dictionary or sequence or as keyword arguments. If the arguments are a
|
|
dictionary, the values will be bound by name and if the arguments are a
|
|
sequence the values will be bound by position.
|
|
|
|
<p>
|
|
A reference to the statement will be retained by the cursor. If None or the
|
|
same string object is passed in again, the cursor will execute that
|
|
statement again without performing a prepare or rebinding and redefining.
|
|
This is most effective for algorithms where the same statement is used, but
|
|
different parameters are bound to it (many times).
|
|
|
|
<p>
|
|
For maximum efficiency when reusing an statement, it is best to use the
|
|
setinputsizes() method to specify the parameter types and sizes ahead of
|
|
time; in particular, None is assumed to be a string of length 1 so any
|
|
values that are later bound as numbers or dates will raise a TypeError
|
|
exception.
|
|
|
|
<p>
|
|
If the statement is a query, a list of variable objects (<a href="varobj.html#varobj">4</a>) will
|
|
be returned corresponding to the list of variables into which data will be
|
|
fetched with the fetchone(), fetchmany() and fetchall() methods; otherwise,
|
|
None will be returned.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define the return value of this
|
|
method.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-89' xml:id='l2h-89' class="function">executemany</tt></b>(</nobr></td>
|
|
<td><var><var>statement</var>, <var>parameters</var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Prepare a statement for execution against a database and then execute it
|
|
against all parameter mappings or sequences found in the sequence parameters.
|
|
The statement is managed in the same way as the execute() method manages it.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-90' xml:id='l2h-90' class="function">executemanyprepared</tt></b>(</nobr></td>
|
|
<td><var><var>numIters</var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Execute the previously prepared and bound statement the given number of
|
|
times. The variables that are bound must have already been set to their
|
|
desired value before this call is made. This method was designed for the
|
|
case where optimal performance is required as it comes at the expense of
|
|
compatibility with the DB API.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this method.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-91' xml:id='l2h-91' class="function">fetchall</tt></b>(</nobr></td>
|
|
<td><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Fetch all (remaining) rows of a query result, returning them as a list of
|
|
tuples. An empty list is returned if no more rows are available. Note that
|
|
the cursor's arraysize attribute can affect the performance of this
|
|
operation, as internally reads from the database are done in batches
|
|
corresponding to the arraysize.
|
|
|
|
<p>
|
|
An exception is raised if the previous call to execute() did not produce any
|
|
result set or no call was issued yet.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-92' xml:id='l2h-92' class="function">fetchmany</tt></b>(</nobr></td>
|
|
<td><var></var><big>[</big><var><var>numRows=cursor.arraysize</var></var><big>]</big><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Fetch the next set of rows of a query result, returning a list of tuples. An
|
|
empty list is returned if no more rows are available. Note that the cursor's
|
|
arraysize attribute can affect the performance of this operation.
|
|
|
|
<p>
|
|
The number of rows to fetch is specified by the parameter. If it is not
|
|
given, the cursor's arrysize attribute determines the number of rows to be
|
|
fetched. If the number of rows available to be fetched is fewer than the
|
|
amount requested, fewer rows will be returned.
|
|
|
|
<p>
|
|
An exception is raised if the previous call to execute() did not produce any
|
|
result set or no call was issued yet.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-93' xml:id='l2h-93' class="function">fetchone</tt></b>(</nobr></td>
|
|
<td><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Fetch the next row of a query result set, returning a single tuple or None
|
|
when no more data is available.
|
|
|
|
<p>
|
|
An exception is raised if the previous call to execute() did not produce any
|
|
result set or no call was issued yet.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-94' xml:id='l2h-94' class="function">fetchraw</tt></b>(</nobr></td>
|
|
<td><var></var><big>[</big><var><var>numRows=cursor.arraysize</var></var><big>]</big><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Fetch the next set of rows of a query result into the internal buffers of the
|
|
defined variables for the cursor. The number of rows actually fetched is
|
|
returned. This method was designed for the case where optimal performance is
|
|
required as it comes at the expense of compatibility with the DB API.
|
|
|
|
<p>
|
|
An exception is raised if the previous call to execute() did not produce any
|
|
result set or no call was issued yet.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this method.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-95' xml:id='l2h-95' class="function">__iter__</tt></b>(</nobr></td>
|
|
<td><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Returns the cursor itself to be used as an iterator.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> This method is an extension to the DB API definition but it
|
|
is mentioned in PEP 249 as an optional extension.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-96' xml:id='l2h-96' class="function">next</tt></b>(</nobr></td>
|
|
<td><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Fetch the next row of a query result set, using the same semantics as
|
|
the method fetchone().
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> This method is an extension to the DB API definition but it
|
|
is mentioned in PEP 249 as an optional extension.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><b><tt id='l2h-97' xml:id='l2h-97'>numbersAsStrings</tt></b></dt>
|
|
<dd>
|
|
This integer attribute defines whether or not numbers should be returned as
|
|
strings rather than integers or floating point numbers. This is useful to get
|
|
around the fact that Oracle floating point numbers have considerably greater
|
|
precision than C floating point numbers and not require a change to the SQL
|
|
being executed.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this attribute.
|
|
</dd></dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-98' xml:id='l2h-98' class="function">parse</tt></b>(</nobr></td>
|
|
<td><var><var>statement</var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
This can be used to parse a statement without actually executing it (this
|
|
step is done automatically by Oracle when a statement is executed).
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this method.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-99' xml:id='l2h-99' class="function">prepare</tt></b>(</nobr></td>
|
|
<td><var><var>statement</var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
This can be used before a call to execute() to define the statement that will
|
|
be executed. When this is done, the prepare phase will not be performed when
|
|
the call to execute() is made with None or the same string object as the
|
|
statement.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this method.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><b><tt id='l2h-100' xml:id='l2h-100'>rowcount</tt></b></dt>
|
|
<dd>
|
|
This read-only attribute specifies the number of rows that have currently
|
|
been fetched from the cursor (for select statements) or that have been
|
|
affected by the operation (for insert, update and delete statements).
|
|
</dd></dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-101' xml:id='l2h-101' class="function">setinputsizes</tt></b>(</nobr></td>
|
|
<td><var><var>*args</var>, <var>**keywordArgs</var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
This can be used before a call to execute() to predefine memory areas for the
|
|
operation's parameters. Each parameter should be a type object corresponding
|
|
to the input that will be used or it should be an integer specifying the
|
|
maximum length of a string parameter. Use keyword arguments when binding by
|
|
name and positional arguments when binding by position. The singleton None
|
|
can be used as a parameter when using positional arguments to indicate that
|
|
no space should be reserved for that position.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-102' xml:id='l2h-102' class="function">setoutputsize</tt></b>(</nobr></td>
|
|
<td><var><var>size</var>, </var><big>[</big><var><var>column</var></var><big>]</big><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
This can be used before a call to execute() to predefine memory areas for the
|
|
long columns that will be fetched. The column is specified as an index into
|
|
the result sequence. Not specifying the column will set the default size for
|
|
all large columns in the cursor.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><b><tt id='l2h-103' xml:id='l2h-103'>statement</tt></b></dt>
|
|
<dd>
|
|
This read-only attribute provides the string object that was previously
|
|
prepared with prepare() or executed with execute().
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this attribute.
|
|
</dd></dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-104' xml:id='l2h-104' class="function">var</tt></b>(</nobr></td>
|
|
<td><var><var>dataType</var>, </var><big>[</big><var><var>size</var></var><big>]</big><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
Create a variable associated with the cursor of the given type and size and
|
|
return a variable object (<a href="varobj.html#varobj">4</a>). If the size is not specified and the
|
|
type is a string or binary, 4000 bytes (maximum allowable by Oracle) is
|
|
allocated; if the size is not specified and the type is a long string or long
|
|
binary, 128KB is allocated. This method was designed for use with PL/SQL
|
|
in/out variables where the length or type cannot be determined automatically
|
|
from the Python object passed in.
|
|
|
|
<p>
|
|
<strong>NOTE:</strong> The DB API definition does not define this method.
|
|
</dl>
|
|
|
|
<p>
|
|
|
|
<div class="navigation">
|
|
<div class='online-navigation'>
|
|
<p></p><hr />
|
|
<table align="center" width="100%" cellpadding="0" cellspacing="2">
|
|
<tr>
|
|
<td class='online-navigation'><a rel="prev" title="2. connection Objects"
|
|
href="connobj.html"><img src='previous.png'
|
|
border='0' height='32' alt='Previous Page' width='32' /></a></td>
|
|
<td class='online-navigation'><a rel="parent" title="cx_Oracle"
|
|
href="cx_Oracle.html"><img src='up.png'
|
|
border='0' height='32' alt='Up one Level' width='32' /></a></td>
|
|
<td class='online-navigation'><a rel="next" title="4. variable Objects"
|
|
href="varobj.html"><img src='next.png'
|
|
border='0' height='32' alt='Next Page' width='32' /></a></td>
|
|
<td align="center" width="100%">cx_Oracle</td>
|
|
<td class='online-navigation'><a rel="contents" title="Table of Contents"
|
|
href="contents.html"><img src='contents.png'
|
|
border='0' height='32' alt='Contents' width='32' /></a></td>
|
|
<td class='online-navigation'><img src='blank.png'
|
|
border='0' height='32' alt='' width='32' /></td>
|
|
<td class='online-navigation'><img src='blank.png'
|
|
border='0' height='32' alt='' width='32' /></td>
|
|
</tr></table>
|
|
<div class='online-navigation'>
|
|
<b class="navlabel">Previous:</b>
|
|
<a class="sectref" rel="prev" href="connobj.html">2. Connection Objects</a>
|
|
<b class="navlabel">Up:</b>
|
|
<a class="sectref" rel="parent" href="cx_Oracle.html">cx_Oracle</a>
|
|
<b class="navlabel">Next:</b>
|
|
<a class="sectref" rel="next" href="varobj.html">4. Variable Objects</a>
|
|
</div>
|
|
</div>
|
|
<hr />
|
|
<span class="release-info">Release 4.3.1, documentation updated on April 18, 2007.</span>
|
|
</div>
|
|
<!--End of Navigation Panel-->
|
|
|
|
</body>
|
|
</html>
|