/usr/local/src/sqlrelay-0.25/doc/api/python/test.py.html

    # Copyright (c) 2000 Roman Milner
    # See the file COPYING for more information

    from SQLRelay import CSQLRelay

    class sqlrconnection:

        """
        A wrapper for the sqlrelay connection API.  Closely follows the C++ API.
        """

        def __init__(self, host, port, socket, user, password, retrytime=0, tries=1):
            """
            Opens a connection to the sqlrelay server and authenticates with
            user and password.  Failed connections are retried for tries times
            at retrytime interval.  If tries is 0 then retries will continue
            forever.  If retrytime is 0 then retries will be attempted on a
            default interval.
            """

        def setTimeout(self, timeoutsec, timeoutusec):
           """
          Sets the server connect timeout in seconds
          and milliseconds.  Setting either parameter
          to -1 disables the timeout.
          """

        def endSession(self):
            """
            Ends the current session.
            """

        def suspendSession(self):
            """
            Disconnects this connection from the current
            session but leaves the session open so
            that another connection can connect to it
            using resumeSession().
            """

        def getConnectionPort(self):
            """
            Returns the inet port that the connection is
            communicating over. This parameter may be
            passed to another connection for use in
            the resumeSession() method.
            Note: the value returned by this method is
            only valid after a call to suspendSession().
            """

        def getConnectionSocket(self):
            """
            Returns the unix socket that the connection is
            communicating over. This parameter may be
            passed to another connection for use in
            the resumeSession() method.
            Note: the value returned by this method is
            only valid after a call to suspendSession().
            """

        def resumeSession(self, port, socket):
            """
            Resumes a session previously left open
            using suspendSession().
            Returns 1 on success and 0 on failure.
            """

        def ping(self):
            """
            Returns 1 if the database is up and 0
            if it's down.
            """

        def identify(self):
            """
            Returns the type of database:
              oracle8, postgresql, mysql, etc.
            """

        def dbVersion(self):
            """
            Returns the version of the database
            """

        def serverVersion(self):
            """
            Returns the version of the SQL Relay server software
            """

        def clientVersion(self):
            """
            Returns the version of the SQL Relay client software
            """

        def bindFormat(self):
            """
            Returns a string representing the format
            of the bind variables used in the db.
            """

        def autoCommitOn(self):
            """
            Instructs the database to perform a commit
            after every successful query.
            """

        def autoCommitOff(self):
            """
            Instructs the database to wait for the
            client to tell it when to commit.
            """

        def commit(self):
            """
            Issues a commit.  Returns a 1 if the commit succeeded,
            0 if it failed and -1 if an error occurred.
            """

        def rollback(self):
            """
            Issues a rollback.  Returns a 1 if the rollback succeeded,
            0 if it failed and -1 if an error occurred.
            """

        def debugOn(self):
            """
            Turn verbose debugging on.
            """

        def debugOff(self):
            """
            Turn verbose debugging off.
            """

        def getDebug(self):
            """
            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.
        """

        def __init__(self, sqlrcon):
            self.cursor = CSQLRelay.sqlrcur_alloc(sqlrcon.connection)

        def __del__(self):
            CSQLRelay.sqlrcur_free(self.cursor)

        def setResultSetBufferSize(self, rows):
            """
            Sets the number of rows of the result set
            to buffer at a time.  0 (the default)
            means buffer the entire result set.
            """

        def getResultSetBufferSize(self):
            """
            Returns the number of result set rows that
            will be buffered at a time or 0 for the
            entire result set.
            """

        def dontGetColumnInfo(self):
            """
            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.
            """

        def getColumnInfo(self):
            """
            Tells the server to send column info.
            """

        def mixedCaseColumnNames(self):
            """
            Columns names are returned in the same
            case as they are defined in the database.
            This is the default.
            """

        def upperCaseColumnNames(self):
            """
            Columns names are converted to upper case.
            """

        def lowerCaseColumnNames(self):
            """
            Columns names are converted to lower case.
            """

        def cacheToFile(self, filename):
            """
            Sets query caching on.  Future queries
            will be cached to the file "filename".
            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.
            """

        def setCacheTtl(self, 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.
            """

        def getCacheFileName(self):
            """
            Returns the name of the file containing the most
            recently cached result set.
            """

        def cacheOff(self):
            """
            Sets query caching off.
            """

        """
        If you don't need to use substitution or bind variables
        in your queries, use these two methods.
        """
        def sendQuery(self, query):
            """
            Send a SQL query to the server and
            gets a result set.
            """

        def sendQueryWithLength(self, query, length):
            """
            Sends "query" with length "length" and gets
            a result set. This method must be used if
            the query contains binary data.
            """

        def sendFileQuery(self, 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.
        """
        def prepareQuery(self, query):
            """
            Prepare to execute query.
            """

        def prepareQueryWithLength(self, query, length):
            """
            Prepare to execute "query" with length
            "length".  This method must be used if the
            query contains binary data.
            """

        def prepareFileQuery(self, path, file):
            """
            Prepare to execute the contents of path/filename.
            """

        def substitution(self, variable, value, precision=0, scale=0):
            """
            Define a substitution variable.
            Returns true if the variable was successfully substituted or false if
            the variable isn't a string, integer or floating point number, or if
            precision and scale aren't provided for a floating point number.
            """

        def inputBind(self, variable, value, precision=0, scale=0):
            """
            Define an input bind varaible.
            Returns true if the variable was successfully bound or false if the
            variable isn't a string, integer or floating point number, or if
            precision and scale aren't provided for a floating point number.
            """

        def inputBindBlob(self, variable, value, length):
            """
            Define a BLOB input bind varaible.
            """

        def inputBindClob(self, variable, value, length):
            """
            Define a CLOB input bind varaible.
            """

        def defineOutputBindString(self, variable, length):
            """
            Define a string output bind varaible.
            "length" bytes will be reserved to store the value.
            """

        def defineOutputBindInteger(self, variable):
            """
            Define an integer output bind varaible.
            """

        def defineOutputBindDouble(self, variable):
            """
            Define a double precision floating point
            output bind varaible.
            """

        def defineOutputBindBlob(self, variable):
            """
            Define a BLOB output bind varaible.
            """

        def defineOutputBindClob(self, variable):
            """
            Define a CLOB output bind varaible.
            """

        def defineOutputBindCursor(self, variable):
            """
            Define a cursor output bind varaible.
            """

        def substitutions(self, variables, values, precisions=None, scales=None):
            """
            Define substitution variables.
            Returns true if the variables were successfully substituted or false if
            one of the variables wasn't a string, integer or floating point number,
            or if precision and scale weren't provided for a floating point number.
            """

        def inputBinds(self, variables, values, precisions=None, scales=None):
            """
            Define input bind variables.
            Returns true if the variables were successfully bound or false if one
            of the variables wasn't a string, integer or floating point number,
            or if precision and scale weren't provided for a floating point number.
            """

        def validateBinds(self):
            """
            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.
            """

        def validBind(self, variable):
            """
            Returns true if "variable" was a valid bind
            variable of the query.
            """

        def executeQuery(self):
            """
            Execute the query that was previously
            prepared and bound.
            """

        def fetchFromBindCursor(self):
            """
            Fetch from a cursor that was returned as
            an output bind variable.
            """

        def getOutputBindString(self, variable):
            """
            Retrieve the value of an output bind variable.
            """

        def getOutputBindBlob(self, variable):
            """
            Retrieve the value of an output bind variable.
            """

        def getOutputBindClob(self, variable):
            """
            Retrieve the value of an output bind variable.
            """

        def getOutputBindInteger(self, variable):
            """
            Retrieve the value of an output bind variable.
            """

        def getOutputBindDouble(self, variable):
            """
            Retrieve the value of an output bind variable.
            """

        def getOutputBindLength(self, variable):
            """
            Retrieve the length of an output bind variable.
            """

        def getOutputBindCursor(self, variable):
            """
            Get the cursor associated with a previously
            defined output bind variable.
            """

        def openCachedResultSet(self, filename):
            """
            Open a result set after a sendCachedQeury
            """

        def colCount(self):
            """
            Returns the number of columns in the current result set.
            """

        def rowCount(self):
            """
            Returns the number of rows in the current result set.
            """

        def totalRows(self):
            """
            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.
            """

        def affectedRows(self):
            """
            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.
            """

        def firstRowIndex(self):
            """
            Returns the index of the first buffered row.
            This is useful when buffering only part of
            the result set at a time.
            """

        def endOfResultSet(self):
            """
            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.
            """

        def errorMessage(self):
            """
            If the query failed, the error message will be returned
            from this method.  Otherwise, it returns None.
            """

        def getNullsAsEmptyStrings(self):
            """
            Tells the cursor to return NULL fields and output
            bind variables as empty strings.
            This is the default.
            """

        def getNullsAsNone(self):
            """
            Tells the cursor to return NULL fields and output
            bind variables as NULL's.
            """

        def getField(self, row, col):
            """
            Returns the value of the specified row and
            column.  col may be a column name or number.
            """

        def getFieldLength(self, row, col):
            """
            Returns the length of the specified row and
            column.  col may be a column name or number.
            """

        def getRow(self, row):
            """
            Returns a list of values in the given row.
            """

        def getRowDictionary(self, row):
            """
            Returns the requested row as values in a dictionary
            with column names for keys.
            """

        def getRowRange(self, 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.
            """

        def getRowLengths(self, row):
            """
            Returns a list of lengths in the given row.
            """

        def getRowLengthsDictionary(self, row):
            """
            Returns the requested row lengths as values in a dictionary
            with column names for keys.
            """

        def getRowLengthsRange(self, 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.
            """

        def getColumnName(self, col):
            """
            Returns the name of column number col.
            """

        def getColumnNames(self):
            """
            Returns a list of column names in the current result set.
            """

        def getColumnType(self, col):
            """
            Returns the type of the specified column.  col may
            be a name or number.
            """

        def getColumnLength(self, col):
            """
            Returns the length of the specified column.  col may
            be a name or number.
            """

        def getLongest(self, col):
            """
            Returns the length of the specified column.  col may
            be a name or number.
            """

        def getResultSetId(self):
            """
            Returns the internal ID of this result set.
            This parameter may be passed to another
            cursor for use in the resumeResultSet()
            method.
            Note: the value returned by this method is
            only valid after a call to suspendResultSet().
            """

        def suspendResultSet(self):
            """
            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().
            """

        def resumeResultSet(self, id):
            """
            Resumes a result set previously left open
            using suspendSession().
            Returns 1 on success and 0 on failure.
            """

        def resumeCachedResultSet(self, id, filename):
            """
            Resumes a result set previously left open
            using suspendSession() and continues caching
            the result set to "filename".
            Returns 1 on success and 0 on failure.
            """