2 Sybase -- Provides interface to Sybase relational database

The Sybase module contains the following:

__version__
A string which specifies the version of the Sybase module.

use_datetime
When you import the Sybase module it will try to import the mxDateTime module. If the mxDateTime module is successfully imported then this variable will be set to 1. All datetime columns will then be returned as mxDateTime.DateTime objects.

If you do not wish to use mxDateTime.DateTime objects, set this to 0 immediately after importing the Sybase module. All datetime columns will then be returned as sybasect.DateTime objects.

apilevel
Specifies the level of DB-API compliance. Currently set to '2.0'.

threadsafety
Specifies the DB-API threadsafety. The Sybase module allows threads to share the module, connections and cursors.

paramstyle
Specifies the DB-API parameter style. This variable is set to the value 'named' which indicates that the Sybase module uses named parameters. For example:

c.execute("select * from titles where title like @arg",
          {'@arg': 'The %'})

exception Warning
Exception raised for important warnings like data truncations while inserting, etc. It is a subclass of the Python StandardError (defined in the module exceptions).

exception Error
Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement. It is a subclass of the Python StandardError (defined in the module exceptions).

exception InterfaceError
Exception raised for errors that are related to the database interface rather than the database itself. It is a subclass of Error.

exception DatabaseError
Exception raised for errors that are related to the database. It is a subclass of Error.

exception DataError
Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc. It is a subclass of DatabaseError.

exception OperationalError
Exception raised for errors that are related to the database's operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc. It is a subclass of DatabaseError.

exception IntegrityError
Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails. It is a subclass of DatabaseError.

exception InternalError
Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc. It is a subclass of DatabaseError.

exception ProgrammingError
Exception raised for programming errors, e.g. table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc. It is a subclass of DatabaseError.

exception NotSupportedError
Exception raised in case a method or database API was used which is not supported by the database, e.g. requesting a rollback() on a connection that does not support transaction or has transactions turned off. It is a subclass of DatabaseError.

This is the exception inheritance layout:

StandardError
|__Warning
|__Error
   |__InterfaceError
   |__DatabaseError
      |__DataError
      |__OperationalError
      |__IntegrityError
      |__InternalError
      |__ProgrammingError
      |__NotSupportedError

STRING
An instance of the DBAPITypeObject class which compares equal to all Sybase type codes for string-based column types (char, varchar, text).

BINARY
An instance of the DBAPITypeObject class which compares equal to all Sybase type codes which describe binary columns (image, binary, varbinary).

NUMBER
An instance of the DBAPITypeObject class which compares equal to all Sybase type codes which describe numeric columns (bit, tinyint, smallint, int, decimal, numeric, float, real, money, smallmoney).

DATETIME
An instance of the DBAPITypeObject class which compares equal to all Sybase type codes which describe date/time columns (datetime, smalldatetime).

ROWID
An instance of the DBAPITypeObject class which compares equal to all Sybase type codes which describe date/time columns (decimal, numeric).

Date( year, month, day)
DB-API 2.0 function which returns a Sybase datetime value for the supplied arguments.

Time( hour, minute, second)
Sybase does not have a native type for representing times - this DB-API 2.0 function is not implemented.

Timestamp( year, month, day, hour, minute, second)
DB-API 2.0 function which returns a Sybase datetime value for the supplied arguments.

DateFromTicks( ticks)
DB-API 2.0 function which returns a Sybase datetime value from the given ticks value (number of seconds since the epoch; see the documentation of the standard Python time module for details).

TimeFromTicks( ticks)
Sybase does not have a native type for representing times - this DB-API 2.0 function is not implemented.

TimestampFromTicks( ticks)
DB-API 2.0 function which returns a Sybase datetime value from the given ticks value (number of seconds since the epoch; see the documentation of the standard Python time module for details).

Binary( str)
DB-API 2.0 function which constructs an object capable of holding a binary (long) string value.

class Cursor( owner)
Return a new instance of the Cursor class which implements the DB-API 2.0 cursor functionality.

Cursor objects are usually created via the cursor() method of the Connection object.

The owner argument must be an instance of the Connection class.

class Bulkcopy( owner, table, direction = CS_BLK_IN, arraysize = 20)
Return a new instance of the Bulkcopy class.

The owner argument must be an instance of the Connection class. A bulk copy context will be established for the table named in the table argument, the bulkcopy direction must be either CS_BLK_IN or CS_BLK_OUT as defined in the Sybase module. arraysize specifies the number of in-memory rows that will be batched for each DB request.

This functionality can only be called when the Connection is in auto_commit mode. Otherwise a ProgrammingError exception is raised.

Bulkcopy objects are usually created via the bulkcopy() method of the Connection object.

This is an extension of the DB-API 2.0 specification.

class Connection( dsn, user, passwd [, ...])
Return a new instance of the Connection class which implements the DB-API 2.0 connection functionality.

The dsn argument identifies the Sybase server, user and passwd are the Sybase username and password respectively.

The optional arguments are the same as those supported by the connect() function.

connect( dsn, user, passwd [, ...])
Implements the DB-API 2.0 connect() function.

Creates a new Connection object passing the function arguments to the Connection constructor. The optional arguments and their effect are:

database = None

Specifies the database to use - has the same effect as the following SQL.

use database

strip = 0

If non-zero then all char columns will be right stripped of whitespace.

auto_commit = 0

Controls Sybase chained transaction mode. When non-zero, chained transaction mode is turned off. From the Sybase SQL manual:

If you set chained transaction mode, Adaptive Server implicitly invokes a begin transaction before the following statements: delete, insert, open, fetch, select, and update. You must still explicitly close the transaction with a commit.

bulkcopy = 0

Must be non-zero if you are going to perform bulkcopy operations on the connection. You will also need to turn off chained transactions in order to use bulkcopy (auto_commit=1).

delay_connect = 0

If non-zero the returned Connection object will be initialised but not connected. This allows you to set additional options on the connection before completing the connection to the server. Call the connect() method to complete the connection.

db = Sybase.connect('SYBASE', 'sa', '', delay_connect = 1)
db.set_property(Sybase.CS_HOSTNAME, 'secret')
db.connect()

locale = None

Controls the locale of the connection to match that of the server.

db = Sybase.connect('SYBASE', 'sa', '', locale = 'utf8')

locking = 1

Controls whether or not thread locks will be used on the connection object. When non-zero, the connection allows connections and cursors to be shared between threads. If your program is not multi-threaded you can gain a slight performance improvement by passing zero in this argument.

datetime = ``auto''

Controls the type used when returning a date or time.

The Sybase module imports the low level sybasect extension module via

from sybasect import *

which means that the Sybase module inherits all of the objects defined in that module.

Some of the functions will be useful in your programs.

datetime( str [, type = CS_DATETIME_TYPE])
Creates a new instance of the DateTime class. This is used to construct native Sybase datetime and smalldatetime values.

The string passed in the str argument is converted to a datetime value of the type specified in the optional type argument.

CS_DATETIME_TYPE represents the datetime Sybase type and CS_DATETIME4_TYPE represents smalldatetime.

The DateTime class is described in the sybasect module.

money( num)
Creates a new instance of the Money class. This is used to construct native Sybase money values.

The value passed in the num argument is converted to a native Sybase money value.

The DateTime class is described in the sybasect module.

numeric( num, [precision = -1 [, scale = -1]])
Creates a new instance of the Numeric class. This is used to construct native Sybase numeric and decimal values.

Converts the value passed in the num argument to a native Sybase numeric value. The precision and scale arguments control the precision and scale of the returned value.

The Numeric class is described in the sybasect module.



Subsections