2 Sybase -- Provides interface to Sybase relational database
Keywords: sybase

# 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 `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.

    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()

    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.

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

- 2.1 Connection Objects
- 2.2 Cursor Objects