# 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. 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. 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. 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. 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. prepareFileQuery(path, file) Prepare to execute the contents of path/filename. 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. 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. getOutputBind(variable) Retrieve the value of an 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. 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. 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.