2.2 Cursor Objects

Implements the DB-API 2.0 Cursor class.

Cursor objects have the following interface:

description

The DB-API 2.0 cursor description member.

A list of 7-item tuples. Each of the tuples describes one result column: (name, type_code, display_size, internal_size, precision, scale, null_ok). This attribute will be None for operations which do not return rows or if the cursor has not had an operation invoked via execute() or executemany().

The type_code can be interpreted by comparing it to the DBAPITypeObject objects STRING, BINARY, NUMBER, DATETIME, or ROWID.

rowcount

The DB-API 2.0 cursor rowcount member.

This attribute reports the number of rows that the last execute() or executemany() method produced or affected.

The attribute is -1 if no execute() or executemany() has been performed on the cursor.

callproc( procname [, parameters])

Implements the DB-API 2.0 cursor callproc() method.

Calls the stored database procedure named in the procname argument. The optional parameters argument can be a sequence or dictionary which contains one entry for each argument that the procedure expects. For example:

c.callproc('sp_help', ['titles'])
c.callproc('sp_help', {'@objname': 'titles'})

The DB-API 2.0 specification says:

The result of the call is returned as modified copy of the input sequence. Input parameters are left untouched, output and input/output parameters replaced with possibly new values.

This method is is not DB-API compliant in because there does not seem to be a way to query Sybase to determine which parameters are output parameters. This method returns None.

The procedure may also provide a result set as output. This can be retrieved via the fetchone(), fetchmany(), and fetchall() methods.

close( )

Implements the DB-API 2.0 cursor close() method.

Cancels any pending results immediately. Any operation on the cursor after calling this method will raise an exception.

This method is called by the __del__() method.

execute( sql [, params])

Implements the DB-API 2.0 cursor execute() method.

Prepares a dynamic SQL command on the Sybase server and executes it. The optional params argument is a dictionary of parameters which are bound as parameters to the dynamic SQL command. Sybase uses name place holders to specify which the parameters will be used by the SQL command.

import Sybase
db = Sybase.connect('SYBASE', 'sa', '', 'pubs2')
c = db.cursor()
c.execute("select * from titles where price > @price", {'@price': 15.00})
c.fetchall()

The prepared dynamic SQL will be reused by the cursor if the same SQL is passed in the sql argument. This is most effective for algorithms where the same operation is used, but different parameters are bound to it (many times).

The method returns None.

executemany( sql, params_seq)

Implements the DB-API 2.0 cursor executemany() method.

Calls the execute() method for every parameter sequence in the sequence passed as the params_seq argument.

The method returns None.

fetchone( ): Implements the DB-API 2.0 cursor fetchone() method.
Fetches the next row of a logical result and returns it as a tuple. None is returned when no more rows are available in the logical result.

fetchmany( [size = cursor.arraysize])

Implements the DB-API 2.0 cursor fetchmany() method.

Fetches the next set of rows of a logical result, returning a list of tuples. An empty list is returned when no more rows are available.

The number of rows to fetch per call is specified by the optional size argument. If size is not supplied, the arraysize member determines the number of rows to be fetched. The method will try to fetch the number of rows indicated by the size parameter. If this is not possible due to the specified number of rows not being available, fewer rows will be returned.

fetchall( ): Implements the DB-API 2.0 cursor fetchall() method.
Fetches all remaining rows of a logical result returning them as a list of tuples.

nextset( )

Implements the DB-API 2.0 cursor nextset() method.

Makes the cursor skip to the next logical result, discarding any remaining rows from the current logical result.

If there are no more logical results, the method returns None. Otherwise, it returns 1 and subsequent calls to the fetchone(), fetchmany(), and fetchall() methods will return rows from the next logical result.

arraysize: The DB-API 2.0 cursor arraysize member.
This read/write attribute specifies the number of rows to fetch at a time with fetchmany(). It defaults to 1 meaning to fetch a single row at a time.

setinputsizes( size): Implements the DB-API 2.0 cursor setinputsizes() method.
This method does nothing - it is provided for DB-API compliance.

setoutputsize( size [, column]): Implements the DB-API 2.0 cursor setoutputsize() method.
This method does nothing - it is provided for DB-API compliance.