# Copyright (c) 2001 David Muse
# See the file COPYING for more information
class SQLRConnection
A wrapper for the sqlrelay connection API. Closely follows the C++ API.
new(host, port, socket, user, password, retrytime, tries)
Opens a connection to the sqlrelay server and authenticates with
user and password. Failed connections are retried for tries times
at retrytime interval.
Initiates a connection to "server" on "port"
or to the unix "socket" on the local machine
and authenticates with "user" and "password".
Failed connections will be retried for
"tries" times on interval "retrytime".
If "tries" is 0 then retries will continue
forever. If "retrytime" is 0 then retries
will be attempted on a default interval.
endSession()
Ends the current session.
suspendSession()
Disconnects this connection from the current
session but leaves the session open so
that another connection can connect to it
using resumeSession().
getConnectionPort()
Returns the inet port that the connection is
communicating over. This parameter may be
passed to another connection for use in
the resumeSession() method.
getConnectionSocket()
Returns the unix socket that the connection is
communicating over. This parameter may be
passed to another connection for use in
the resumeSession() method.
resumeSession(port, socket)
Resumes a session previously left open
using suspendSession().
Returns 1 on success and 0 on failure.
ping()
Returns 1 if the database is up and 0
if it's down.
identify()
Returns the type of database
oracle7, oracle8, postgresql, mysql, etc.
autoCommitOn()
Instructs the database to perform a commit
after every successful query. Returns a 1
on success, 0 on failure and -1 if an error
occurred.
autoCommitOff()
Instructs the database to wait for the client
to tell it when to commit. Returns a 1 on
success, 0 on failure and -1 if an error
occurred.
commit()
Issues a commit. Returns a 1 if the commit
succeeded, 0 if it failed and -1 if an
error occurred.
rollback()
Issues a rollback. Returns a 1 if the rollback
succeeded, 0 if it failed and -1 if an
error occurred.
debugOn()
Turn verbose debugging on.
debugOff()
Turn verbose debugging off.
getDebug()
Returns 1 if debugging is turned on and 0 if debugging is turned off.
class SQLRCursor
A wrapper for the sqlrelay cursor API. Closely follows the C++ API.
new(sqlrcon)
setResultSetBufferSize(rows)
Sets the number of rows of the result set
to buffer at a time. 0 (the default)
means buffer the entire result set.
getResultSetBufferSize()
Returns the number of result set rows that
will be buffered at a time or 0 for the
entire result set.
dontGetColumnInfo()
Tells the server not to send any column
info (names, types, sizes). If you don't
need that info, you should call this
method to improve performance.
getColumnInfo()
Tells the server to send column info.
mixedCaseColumnNames()
Columns names are returned in the same
case as they are defined in the database.
This is the default.
upperCaseColumnNames()
Columns names are converted to upper case.
lowerCaseColumnNames()
Columns names are converted to lower case.
cacheToFile(filename)
Sets query caching on. Future queries
The full pathname of the file can be
retrieved using getCacheFileName().
A default time-to-live of 10 minutes is
also set.
Note that once cacheToFile() is called,
the result sets of all future queries will
be cached to that file until another call
to cacheToFile() changes which file to
cache to or a call to cacheOff() turns off
caching.
setCacheTtl(ttl)
Sets the time-to-live for cached result
sets. The sqlr-cachemanger will remove each
cached result set "ttl" seconds after it's
created.
getCacheFileName()
Returns the name of the file containing the most
recently cached result set.
cacheOff()
Sets query caching off.
If you don't need to use substitution or bind variables
in your queries, use these two methods.
sendQuery(query)
Send a SQL query to the server and
gets a result set.
sendQueryWithLength(query)
Sends "query" with length "length" and gets
a result set. This method must be used if
the query contains binary data.
sendFileQuery(path, file)
Send the SQL query in path/file to the server and
gets a result set.
If you need to use substitution or bind variables, in your
queries use the following methods. See the API documentation
for more information about substitution and bind variables.
prepareQuery(query)
Prepare to execute query.
prepareQueryWithLength(query, length)
Prepare to execute "query" with length
"length". This method must be used if the
query contains binary data.
prepareFileQuery(path, file)
Prepare to execute the contents of path/filename.
clearBinds()
Clear all bind variables.
countBindVariables()
Parses the previously prepared query,
counts the number of bind variables defined
in it and returns that number.
substitute(variable, value, [precision, scale])
Define a substitution variable.
Precision and scale are only
necessary for floating point
values.
inputBind(variable, value, [precision, scale])
Define an input bind varaible.
Precision and scale are only
necessary for floating point
values.
defineOutputBind(variable, length)
Define an output bind varaible.
"length" bytes will be reserved to store the result.
defineOutputBindBlob(variable, length)
Define a BLOB output bind varaible.
defineOutputBindClob(variable, length)
Define a CLOB output bind varaible.
defineOutputBindCursor(variable, length)
Define a cursor output bind varaible.
These functions take arrays for parameters
substitutions(variables, values, [precisions, scales])
Define substitution variables.
Precisions and scales are only
necessary for floating point
values.
inputBinds(variables, values, [precisions, scales])
Define input bind variables.
Precisions and scales are only
necessary for floating point
values.
validateBinds()
If you are binding to any variables that
might not actually be in your query, call
this to ensure that the database won't try
to bind them unless they really are in the
query.
executeQuery()
Execute the query that was previously
prepared and bound.
fetchFromBindCursor()
Fetch from a cursor that was returned as
an output bind variable.
getOutputBind(variable)
Retrieve the value of an output bind variable.
getOutputBindLength(variable)
Get the length of the value stored in a
previously defined output bind variable.
getOutputBindCursor(variable)
Get the cursor associated with a previously
defined output bind variable.
openCachedResultSet(filename)
Open a result set after a sendCachedQeury
colCount()
Returns the number of columns in the current result set.
rowCount()
Returns the number of rows in the current result set.
totalRows()
Returns the total number of rows that will
be returned in the result set. Not all
databases support this call. Don't use it
for applications which are designed to be
portable across databases. -1 is returned
by databases which don't support this option.
affectedRows()
Returns the number of rows that were
updated, inserted or deleted by the query.
Not all databases support this call. Don't
use it for applications which are designed
to be portable across databases. -1 is
returned by databases which don't support
this option.
firstRowIndex()
Returns the index of the first buffered row.
This is useful when buffering only part of
the result set at a time.
endOfResultSet()
Returns 0 if part of the result set is still
pending on the server and 1 if not. This
method can only return 0 if
setResultSetBufferSize() has been called
with a parameter other than 0.
errorMessage()
If the query failed, the error message will be returned
from this method. Otherwise, it returns None.
getNullsAsEmptyStrings()
Tells the cursor to return NULL fields and output
bind variables as empty strings.
This is the default.
getNullsAsNone()
Tells the cursor to return NULL fields and output
bind variables as NULL's.
getField(row, col)
Returns the value of the specified row and
column. col may be a column name or number.
getFieldLength(row, col)
Returns the length of the specified row and
column. col may be a column name or number.
getRow(row)
Returns a list of values in the given row.
getRowHash(row)
Returns the requested row as values in a dictionary
with column names for keys.
getRowRange(beg, end)
Returns a list of lists of the rows between beg and end.
Note this function has no equivalent in other SQL Relay API's.
getRowLengths(row)
Returns a list of lengths in the given row.
getRowLengthsHash(row)
Returns the requested row lengths as values in a dictionary
with column names for keys.
getRowLengthsRange(beg, end)
Returns a list of lists of the lengths of rows between beg and end.
Note this function has no equivalent in other SQL Relay API's.
getColumnName(col)
Returns the name of column number col.
getColumnNames()
Returns a list of column names in the current result set.
getColumnType(col)
Returns the type of the specified column. col may
be a name or number.
getColumnLength(col)
Returns the length of the specified column. col may
be a name or number.
getColumnPrecision(col)
Returns the precision of the specified
column.
Precision is the total number of digits in
a number. eg: 123.45 has a precision of 5.
For non-numeric types, it's the number of
characters in the string.
getColumnScale(col)
Returns the scale of the specified column.
Scale is the total number of digits to the
right of the decimal point in a number.
eg: 123.45 has a scale of 2.
getColumnIsNullable(col)
Returns 1 if the specified column can
contain nulls and 0 otherwise.
getColumnIsPrimaryKey(col)
Returns 1 if the specified column is a
primary key and 0 otherwise.
getColumnIsUnique(col)
Returns 1 if the specified column is
unique and 0 otherwise.
getColumnIsPartOfKey(col)
Returns 1 if the specified column is
part of a composite key and 0 otherwise.
getColumnIsUnsigned(col)
Returns 1 if the specified column is
an unsigned number and 0 otherwise.
getColumnIsZeroFilled(col)
Returns 1 if the specified column was
created with the zero-fill flag and 0
otherwise.
getColumnIsBinary(col)
Returns 1 if the specified column
contains binary data and 0
otherwise.
getColumnIsAutoIncrement(col)
Returns 1 if the specified column
auto-increments and 0 otherwise.
getLongest(col)
Returns the length of the specified column. col may
be a name or number.
getResultSetId()
Returns the internal ID of this result set.
This parameter may be passed to another
cursor for use in the resumeResultSet()
method.
suspendResultSet()
Tells the server to leave this result
set open when the cursor calls
suspendSession() so that another cursor can
connect to it using resumeResultSet() after
it calls resumeSession().
resumeResultSet(id)
Resumes a result set previously left open
using suspendSession().
Returns 1 on success and 0 on failure.
resumeCachedResultSet(id, filename)
Resumes a result set previously left open
using suspendSession() and continues caching
Returns 1 on success and 0 on failure.