Cursor

- NAME
- SYNOPSIS
- DESCRIPTION
- AUTHOR

# 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