NAME

SQLRelay::Cursor - Perl API for SQL Relay

SYNOPSIS

use SQLRelay::Connection;
use SQLRelay::Cursor;

my $sc=SQLRelay::Connection->new("testhost",9000,"",
                                  "testuser","testpassword",0,1);
my $ss=SQLRelay::Cursor->new($sc);

$ss->sendQuery("select table_name from user_tables");
$sc->endSession();

for (my $i=0; $i<$ss->rowCount(); $i++) {
        print $ss->getField($i,"table_name"), "\n";
}

DESCRIPTION

SQLRelay::Cursor

    new(sqlrclient);

    DESTROY();

    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(char *filename);
        # Sets query caching on.  Future queries
        # will be cached to the file "filename".
        #
        # 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(int 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, provided it's scanning the directory
        # containing the cache files.

    getCacheFileName();
        # Returns the name of the file containing the
        # cached result set.

    cacheOff();
        # Sets query caching off.

    getDatabaseList(wild);
        # Sends a query that returns a list of
        # databases/schemas matching "wild".  If wild is empty
        # or NULL then a list of all databases/schemas will be
        # returned.
    getTableList(wild);
        # Sends a query that returns a list of tables
        # matching "wild".  If wild is empty or NULL then
        # a list of all tables will be returned.
    getColumnList(table,wild);
        # Sends a query that returns a list of columns
        # in the table specified by the "table" parameter
        # matching "wild".  If wild is empty or NULL then
        # a list of all columns will be returned.


    # If you don't need to use substitution or bind variables
    # in your queries, use these two methods.
    sendQuery(query);
        # Sends "query" and gets a result set.

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

    sendFileQuery(path,filename);
        # Sends the query in file "path"/"filename" 
        # 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,filename);
        # Prepare to execute the contents 
        # of "path"/"filename".

    substitution(variable,value);
        # Define a substitution variable.

    clearBinds();
        # Clear all bind variables.

    countBindVariables();
        # Parses the previously prepared query,
        # counts the number of bind variables defined
        # in it and returns that number.

    inputBind(variable,value);
    inputBind(variable,value,length);
    inputBind(variable,value,precision,scale);
    inputBindBlob(variable,value,size);
    inputBindClob(variable,value,size);
        # Define an input bind variable.
        # (For floating point values, if you don't have the precision and
        # scale then they may both be set to 0.  However in that case you
        # may get unexpected rounding behavior if the server is faking
        # binds.)

    defineOutputBindString(variable,bufferlength);
        # Define an output bind variable.
        # "bufferlength" bytes will be reserved to store the value.
    defineOutputBindBlob(variable);
        # Define a BLOB output bind variable.
    defineOutputBindClob(variable);
        # Define a CLOB output bind variable.
    defineOutputBindCursor(variable);
        # Define a cursor output bind variable.

    substitutions(variables,values);
        # Define an array of substitution variables.

    inputBinds(variables,values);
        # Define an array of input bind variables.

    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.

    validBind(variable);
        # Returns true if "variable" was a valid
        # bind variable of 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.


    getOutputBindString(variable);
        # Get the value stored in a previously
        # defined output bind variable.

    getOutputBindBlob(variable);
        # Get the value stored in a previously
        # defined output bind variable.

    getOutputBindClob(variable);
        # Get the value stored in a previously
        # defined 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);
        # Opens a cached result set as if a query that
        # would have generated it had been executed.
        # Returns true on success and false on failure.



    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 bufferning only part of the
        # result set at a time.

    endOfResultSet();
        # Returns false if part of the result set is still
        # pending on the server and true if not.  This
        # method can only return false if 
        # setResultSetBufferSize() has been called
        # with a parameter other than 0.

    errorMessage();
        # If a query failed and generated an error, the
        # error message is available here.  If the 
        # query succeeded then this method returns NULL.

    errorNumber();
        # If a query failed and generated an
        # error, the error number is available here.
        # If there is no error then this method 
        # returns 0.

    getNullsAsEmptyStrings();
        # Tells the client to return NULL fields and 
        # output bind variables as empty strings.
        # This is the default.

    getNullsAsUndefined();
        # Tells the client to return NULL fields and 
        # output bind variables as undefined.

    getField(row, col);
        # Returns a pointer to the value of the 
        # specified row and column.

    getFieldLength(row, col);
        # Returns a the length of the 
        # specified row and column.

    getRow(row);
        # Returns an array of the values of the
        # specified row or an empty list if the
        # requested row is past the end of the
        # result set.

    getRowHash(row);
        # Returns the requested row as values in a
        # hash with column names for keys or an
        # empty list if the requested row is past
        # the end of the result set.

    getRowLengths(row);
        # Returns a null terminated array of the 
        # lengths of the specified row or an empty
        # list if the requested row is past the end
        # of the result set.

    getRowLengthsHash(row);
        # Returns the requested row lengths as values 
        # in a hash with column names for keys or an
        # empty list if the requested row is past
        # the end of the result set.

    getColumnNames();
        # Returns a null terminated array of the 
        # column names of the current result set.

    getColumnName(col);
        # Returns the name of the specified column.

    getColumnType(col);
        # Returns the type of the specified column.

    getColumnLength(col);
        # Returns the length of the specified column.

    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 longest field
        # in the specified column.

    suspendResultSet();
        # Tells the server to leave this result
        # set open when the client calls 
        # suspendSession() so that another client can 
        # connect to it using resumeResultSet() after 
        # it calls resumeSession().

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

    resumeResultSet(int id);
        # Resumes a result set previously left open 
        # using suspendSession().
        # Returns true on success and false on failure.

    resumeCachedResultSet(int id, char *filename);
        # Resumes a result set previously left open
        # using suspendSession() and continues caching
        # the result set to "filename".
        # Returns true on success and false on failure.

    closeResultSet();
        # Closes the current result set, if one is open.  Data
        # that has been fetched already is still available but
        # no more data may be fetched.  Server side resources
        # for the result set are freed as well.

AUTHOR

David Muse
david.muse@firstworks.com