The Sybase extension module for Python
Dave Cole <dave@itga.com.au>


   The Sybase extension module is licensed under the terms included in
the accompanying file copyright.

Requirements
------------

You will need a functional Python installation.  To date, only 1.5.2
has been tested.  On Debian GNU/Linux systems, you will need to
install the python-dev package.

Installation:
-------------

If you are installing on a Linux machine, you should be able to simply
do the following:

make -f Makefile.pre.in boot
make

Then as root:

make install

If you are not building the module on a Linux machine, you will almost
certainly need to edit the SYBROOT and SYBLIB lines in Setup.in.

Notes:
------

The module is an almost complete implementation of the Python Database
API Specification 2.0.  There are a number of small deviations:

1- Currently there is no way to specify the target database in the
   Connect object constructor.  All this means is that you need to do
   something like the following:

	import Sybase
	db = Sybase.connect(host, user, password)
	db.execute('use mydb')

2- The Connect object does not implement commit() and rollback(). In a
   pinch, you could probably do something like the following:

	db = Sybase.connect(host, user, passwd)
	db.execute('begin transaction mytrans')
	db.execute('...')
	db.execute('...')
	db.execute('commit transaction mytrans')

3- Cursor Objects

   The Cursor.callproc() method has not been implemented as the same
   thing can be achieved via the Connect.execute() method.

   The Cursor.nextset() method is not implemented.

   Connect.cursor() takes an optional update argument with a default
   of 0.  This allows you to select for update:

            db.execute('begin transaction update_id')
            c = db.cursor(update = 1)
            c.execute('select value from numbers'
                      '  where name = "%s"'
                      '  for update of value' % (name,))
            self.value = c.fetchone()[0] + 1
            c.close()
            db.execute('update numbers'
                       '  set value = value + 1'
                       '  where name = "%s"' % (name,))
            db.execute('commit transaction update_id')

4- None of the following types and functions have been implemented:

	Date(year, month, day) 
	      You can supply numeric dates in the format 19990909. 
	Time(hour, minute, second) 
	      No alternative has been tried yet. 
	Timestamp(year, month, day, hour, minute, second) 
	      No alternative has been tried yet. 
	DateFromTicks(ticks) 
	      No alternative has been tried yet. 
	TimeFromTicks(ticks) 
	      No alternative has been tried yet. 
	Binary(string) 
	      No alternative has been tried yet.

5- Bulkcopy Objects

   A Bulkcopy object is returned by the Connect.bulkcopy()
   method. Bulkcopy objects provide an interface to the bulk copy
   import interface to Sybase.

   An example of Bulkcopy usage: 

	import Sybase
	
	data = (('pencils',  5),
		('books',  300),
		('videos',  11))
	
	db = Sybase.connect('SYBASE', 'user', 'password', bulkcopy = 1)
	db.execute('create table #order (name varchar(40), num int)')
	
	bcp = db.bulkcopy('#order')
	for line in data:
	    bcp.rowxfer(line)
	print 'Loaded', bcp.done(), 'rows'

   Bulkcopy objects support the following interface:

   format(column, type) 
	The Sybase bulkcopy library provides a mechanism for querying
	the structure of a table. Unfortunately, no distinction is
	made between char and varchar columns. By optionally using
	this method to indicate which columns are varchar, the CSV
	input parsing of rowxfer() can be made more resistant to
	commas in the middle of column values.

	column is assumed to be an integer column number, starting at
	one to be consistent with Sybase. type is assumed to be a
	string description of the type of the column. The following
	types are recognised:
		char(length) 
		binary(length) 
		longchar(length) 
		longbinary(length) 
		text 
		image 
		tinyint 
		smallint 
		int 
		real 
		float 
		bit 
		datetime 
		smalldatetime 
		money 
		smallmoney 
		numeric(precision,scale) 
		numeric(precision) 
		decimal(precision,scale) 
		decimal(precision) 
		varchar(length) 
		varbinary(length) 
		long 
		ushort 

   rowxfer(data) 
	Currently the Bulkcopy object only supports table loading, not
	dumping. data can be either a CSV string, or a list / tuple of
	field values.

   split(data) 
	Splits a CSV string into fields. Returns a list of the fields.

   batch() 
	Forces a data transfer from the client to the server. Returns
	the number of rows loaded since the previous call to batch(),
	if no previous call, it returns the number of rows loaded so
	far.

   done() 
	Explicitly complete the bulk data transfer. Returns the number
	of rows loaded since the previous call to batch(), batch() was
	not called, it returns the number of rows loaded in the
	session.
