--------------------------------------------------------------------------------

Python driver is a dynamically loaded library.
Its source code is written in C programming language. 
To load the driver into a Python language program 
you should do the following:

import LinPy

(file LinPy.so must be located in /usr/local/lib/python2.5 , for example
or in the directory specified by the PYTHONPATH environment variable)

--------------------------------------------------------------------------------
1. The driver exports the following functions and features accessible
   from Python program:

1.1 connect() - creates an object of the Connection type and connects to 
database. Argument list can contain either unnamed parameters

    (username, password[, database[, mode]])

or named parameters

    'user'     - database user name
    'password' - database user password
    'database' - database name (NODE name). If this parameter is omitted 
                 or empty, connection to local database will be performed
    'mode'     - transaction isolation mode (possible values are M_EXCLUSIVE, 
                 M_OPTIMISTIC and M_AUTOCOMMIT)
	    
see also Connection class description (p. 2)

Example 1:

    # user SYSTEM connects to local database using password MANAGER
    connection = LinPy.connect('SYSTEM', 'MANAGER')
    
Example 2:

    # user BORIS connects to database UNCLE using password 123
    # in AUTOCOMMIT transaction mode
    connection = LinPy.connect(
        user     = 'BORIS',
	password = '123', 
        database = 'UNCLE',
	mode     = LinPy.M_AUTOCOMMIT)

--------------------------------------------------------------------------------
1.2 Date object creation function - Date()

Format:

    Date(year,month,day)
    
Example:

    # 1st January 2003
    d = Date(2003, 1, 1)

--------------------------------------------------------------------------------
1.3 Time object creation function - Time()

Format:

    Time(hour,minute,second[,fractional_second])

Example:

    # noon
    t = Time(12, 0, 0)

--------------------------------------------------------------------------------
1.4 Timestamp object creation function - Timestamp()

Format:

    Timestamp(year,month,day,hour,minute,second[,fractional_second])

Example:

    # 5th April 2003 06:07:08.09
    ts = Timestamp(2003, 4, 5, 6, 7, 8, 9)

--------------------------------------------------------------------------------
1.5 Date object creation from tick value  - DateFromTicks()

Format:

    DateFromTicks(ticks)

Example:

    # current date
    d = DateFromTicks(time())

(see documentation for time standard module of Python language)

--------------------------------------------------------------------------------
1.6 Time object creation from tick value  - TimeFromTicks()

Format:

    TimeFromTicks(ticks)

Example:
    
    # current time
    t = TimeFromTicks(time())

(see documentation for time standard module of Python language)

--------------------------------------------------------------------------------
1.7 Timestamp object creation from tick value  - TimestampFromTicks()

Format:

    TimestampFromTicks(ticks)
    
Example:

    # current date and time
    ts = TimestampFromTicks(time())

(see documentation for time standard module of Python language)

--------------------------------------------------------------------------------
BINARY(string) - function creating an object that can contain
(long) binary string value.

STRING - object type used for character string database columns
(having CHAR, VARCHAR, NCHAR, NVARCHAR types).

BINARY - object type used for binary string database columns
(having BYTE and VARBYTE types).

NUMBER - object type used for numeric database columns
(having SMALLINT, INTEGER, BIGINT, REAL, DOUBLE, DECIMAL types).

DATETIME - object type used for datetime database columns
(having DATE type).

--------------------------------------------------------------------------------

1.8 Module global variables

apilevel - string constant containing DB API supported level value. 
In the current version this string constant is '2.0'.

threadsafety - integer constant containing value of the thread safety level 
supported by DB API. Possible values are:
0 = module cannot be shared by threads
1 = module can be shared by threads, but connections cannot
2 = module and connections can be shared by threads
3 = module, connections and cursors can be shared by threads

Note. Sharing means here that two threads can use the same object without
calling auxiliary objects (mutexes) for synchronization. Not that sometimes 
even using mutexes cannot provide thread safety: the shared resource can use
gloval variables or other uncontrolled resources.

paramstyle - a string constant containing expected parameter marker type.
Possible values corresponding to DB API 2.0 specifications are:
'qmark' = question marker type like '...WHERE name=?'
'numeric' = numeric (positional) marker type like '...WHERE name=:1'
'named' = named marker type like '...WHERE name=:name'
'format' = ANSI C printf format code like '...WHERE name=%s'
'pyformat' = extended Python format code like '...WHERE name=%(name)s'

Note. Linter DBMS supports parameter marking both by name and by question
mark. The second method allows to reach a better performance.

--------------------------------------------------------------------------------
1.9 Exceptions

Module provides all the information about errors by means of the following
exceptions:

Warning - exception called for important warnings like data truncation 
during inserting process etc. This class is a subclass of Python StandardError 
class (defined in exceptions module).

Error - a base class for all error exceptions.You can use it to catch
all exceptions by a single 'except' statement. Warnings are not treated
as errors so they do not belong to this class. This class is a subclass 
of Python StandardError class (defined in exceptions module).

InterfaceError - exception called for errors related mostly to database
interface and not to database itself. This class is a subclass of Error
class.

DatabaseError - exception raised for errors related mostly to database
itself. This class is a subclass of Error class.

DataError - exception raised for errors related to data processing 
like division by zero, value overflow etc. This class is a subclass 
of DatabaseError class.

OperationalError - exception raised for errors related to database that 
sometimed cannot be controlled by a programmer, like unexpected connection 
termination, unknown data source name, transaction processing error, 
memory allocation error etc. This class is a subclass of DatabaseError class.

IntegrityError - exception raised for errors related to database integrity
violations like a foreign reference to non-existent primary key value.
This class is a subclass of DatabaseError class.

InternalError - exception raised in case of database internal error like
invalid cursor, non-synchronized transaction etc. This class is a subclass 
of DatabaseError class.

ProgrammingError - exception raised for errors possibly related to 
programming logic like unknown or already existing table, syntax error
in SQL statement, wrong parameter count etc. This class is a subclass 
of DatabaseError class.

NotSupportedError - exception raised in case of API call usage.
This class is a subclass of DatabaseError class.

Exception inheritance schema:

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

Note: all exceptions raised in the driver have an error code and a text 
message explaining error reason. To obtain additional information about
the exception you can use the following extended features absent in
DBAPI 2.0 specification:

code    - LINTER DBMS error code
message - error message text
linCode - a synonym for 'code'
apiCode - API error code
sysCode - operating system error code
object  - object that raised the exception

--------------------------------------------------------------------------------
2 Connection class

2.1 cursor() - create a cursor

Return a new Cursor Object using the connection.

Format:
    cursor([mode]|[mode = mode])
    where mode is a transaction isolation mode for the cursor, 
      mode is the same as commention mode by default

2.2 commit() - commit all changes made by the connection and its child cursors

Commit any pending transaction to the database. Note that Linter DBMS 
supports autocommit mode which is initially turned off by default. 
setautocommit() method can be used to turn autocommit mode on.

2.3 rollback() - roll back all changes made by the connection and its child cursors

Causes the the database to roll back to the start of any
pending transaction.  Closing a connection without
committing the changes first will cause an implicit
rollback to be performed.

2.4 close() - close connection

Close the connection now (rather than whenever __del__ is
called).  The connection will be unusable from this point
forward; an Error (or subclass) exception will be raised
if any operation is attempted with the connection. The
same applies to all cursor objects trying to use the
connection.  Note that closing a connection without
committing the changes first will cause an implicit
rollback to be performed.

2.5 setautocommit()

Turns autocommit transaction mode on.

--------------------------------------------------------------------------------
3 Cursor class

Cursor class objects are used for database cursors 
processing of selected rows set.

--------------------------------------------------------------------------------
3.1 execute() - execute a statement
    
Prepare and execute a database operation (query or
command).  Parameters may be provided as sequence or
mapping and will be bound to variables in the operation.
Variables are specified in a database-specific notation
(see the module's paramstyle attribute for details). [5]

A reference to the operation will be retained by the
cursor.  If the same operation object is passed in again,
then the cursor can optimize its behavior.  This is most
effective for algorithms where the same operation is used,
but different parameters are bound to it (many times).


Format:
    execute(statement[,parameters]) 

Examples:

    # a statement without parameters
    cursor.execute("insert into PEOPLE (ID, NAME, BDAY) values (1, 'BORIS', '1980.05.27')")

    # named parameters
    cursor.execute("insert into PEOPLE (ID, NAME, BDAY) values (:I, :N, :D)",
        I = 1, N = "BORIS", D = Date(1980, 5, 27))

    # dictionary parameters
    cursor.execute("insert into PEOPLE (ID, NAME, BDAY) values (:I, :N, :D)",
        {"I" : 1, "N" : "BORIS", "D" : Date(1980, 5, 27)})
    
    # tuple parameters
    cursor.execute("insert into PEOPLE (ID, NAME) values (?, ?)",
        (1, "BORIS", Date(1980, 5, 27)))

3.2 fetchall() - fetch all remaining rows

Format:

    fetchall()

Fetch all (remaining) rows of a query result, returning
them as a sequence of sequences (e.g. a list of tuples).
Note that the cursor's arraysize attribute can affect the
performance of this operation.

An Error (or subclass) exception is raised if the previous
call to executeXXX() did not produce any result set or no
call was issued yet.

3.3 fetchone() - fetch one row

Format:

    fetchone() 

Fetches the next row from a selected set (query result). Returns a single 
sequence or None if no more rows selected. Error (or some Error subclass) 
exception is raised if executeXXX() was not previously called or this call 
did not return a result set.

3.4 fetchmany() - fetch several rows

Format:

    fetchmany([size=cursor.arraysize]) 

Fetch the next set of rows of a query result, returning a
sequence of sequences (e.g. a list of tuples). An empty
sequence is returned when no more rows are available.

The number of rows to fetch per call is specified by the
parameter.  If it is not given, the cursor's arraysize
determines the number of rows to be fetched. The method
should try to fetch as many rows as indicated by the size
parameter. If this is not possible due to the specified
number of rows not being available, fewer rows may be
returned.

An Error (or subclass) exception is raised if the previous
call to executeXXX() did not produce any result set or no
call was issued yet.

Note there are performance considerations involved with
the size parameter.  For optimal performance, it is
usually best to use the arraysize attribute.  If the size
parameter is used, then it is best for it to retain the
same value from one fetchmany() call to the next.

3.5 prepare() - prepare a query

Fromat:

    prepare(query)

3.6 setinputsizes() - specify memory area sizes for operation parameters

This can be used before a call to executeXXX() to
predefine memory areas for the operation's parameters.

sizes is specified as a sequence -- one item for each
input parameter.  The item should be a Type Object that
corresponds to the input that will be used, or it should
be an integer specifying the maximum length of a string
parameter.  If the item is None, then no predefined memory
area will be reserved for that column (this is useful to
avoid predefined areas for large inputs).

This method would be used before the executeXXX() method
is invoked.
            
3.7 executemany() - execute several queries at a time

Prepare a database operation (query or command) and then
execute it against all parameter sequences or mappings
found in the sequence seq_of_parameters.

Format:

    executemany(operation[,parameters]) 

Examples:

    cursor.executemany("insert into PEOPLE (ID, NAME) values (:I, :N)",
        [{"I" : 1, "N" : "BORIS"},
         {"I" : 2, "N" : "SASHA"}])
    cursor.executemany("insert into PEOPLE (ID, NAME) values (?, ?)",
        [(1, "BORIS"),
         (2, "SASHA")])

3.8 callproc() - call a stored procedure

Call a stored database procedure with the given name. The
sequence of parameters contains one entry for each
argument that the procedure expects. 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.

The procedure may also provide a result set as
output. This then is made available through the
standard fetchXXX() methods.

Format:

    callproc(procedure_name[,parameters])

3.9 executemanyprepared() - execute prepared queries

3.10 setoutputsize() - specify column size for large column values fetching

Set a column buffer size for fetches of BLOB columns.
The column is specified as an index into the result sequence.  
Not specifying the column will set the default size for all 
BLOB columns in the cursor.
            
This method would be used before the executeXXX() method
is invoked.

3.11 commit() - commit all changes made through the cursor

3.12 rollback() - rollback all changes made through the cursor

3.13 close() - close the cursor

Close the cursor now (rather than whenever __del__ is
called).  The cursor will be unusable from this point
forward; an Error (or subclass) exception will be raised
if any operation is attempted with the cursor.

3.14 nextset() - skip to the next available set

This method will make the cursor skip to the next
available set, discarding any remaining rows from the
current set.

If there are no more sets, the method returns
None. Otherwise, it returns a true value and subsequent
calls to the fetch methods will return rows from the next
result set.

An Error (or subclass) exception is raised if the previous
call to executeXXX() did not produce any result set or no
call was issued yet.

--------------------------------------------------------------------------------
3. Features

description - this read-only attribute is a sequence of 7-item
            sequences.  Each of these sequences contains information
            describing one result column: (name, type_code,
            display_size, internal_size, precision, scale,
            null_ok). The first two items (name and type_code) are
            mandatory, the other five are optional and must be set to
            None if meaningfull values are not provided.

            This attribute will be None for operations that
            do not return rows or if the cursor has not had an
            operation invoked via the executeXXX() method yet.
            
            The type_code can be interpreted by comparing it to the
            Type Objects.


rowcount - this read-only attribute specifies the number of rows that
           the last executeXXX() produced (for DQL statements like
           'select') or affected (for DML statements like 'update' or
           'insert').
            
           The attribute is -1 in case no executeXXX() has been
           performed on the cursor or the rowcount of the last
           operation is not determinable by the interface.

arraysize - 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.
            
mode      - this read-only attribute contains transaction isolation mode 
            value for the cursor.

name      - this read/write attribute contains the cursor name that can
            be used in WHERE CURRENT OF clause.

--------------------------------------------------------------------------------

Note. If a selected row set contains BLOB column, the arraysize
value is ignored and only one row can be fetched for each call.

The following operations are available for BLOB type:

write(obj[, type]) - write an object that have buffer interface into BLOB.
        Object can be buffer, string, unicode or array. type argument
        is an integer value specifying the type of stored data.
read([pos[, len]]) - read data from BLOB value.
        If pos arguments is specified, data reading starts from the specified
        position, otherwise from the BLOB value beginning.
        If len argument is specified, the len bytes will be read,
        or all remaining BLOB bytes if the remaining BLOB length is less 
        than len.
clear() - clear BLOB value.

The following read attributes are available for BLOB values:

length - the current length of BLOB value
type   - BLOB value type

Note. BLOB value offsets begin from 1, i.e.:
    blob.read(1,1) is the 1st byte
    blob.read(blob.length,1) is the last byte

--------------------------------------------------------------------------------

