Provided by: libopendbx1-dev_1.4.6-13build3_amd64 bug

NAME

       OpenDBX::Result - Provides result sets from the database.

SYNOPSIS

   Public Member Functions
       unsigned long columnCount ()  throw ( std::exception )
           Returns the number of columns available in this result set.
       const string columnName (unsigned long pos)  throw ( std::exception )
           Returns the name of the column in the current result set.
       unsigned long columnPos (const string &name)  throw ( std::exception )
           Maps the column name to the column number required by other methods.
       odbxtype columnType (unsigned long pos)  throw ( std::exception )
           Returns the type of the column in the current result set.
       unsigned long fieldLength (unsigned long pos)  throw ( std::exception )
           Returns the size of the content in the current row at the specified postion.
       const char * fieldValue (unsigned long pos)  throw ( std::exception )
           Returns a pointer to the content in the current row at the specified postion.
       void finish ()  throw ( std::exception )
           Retrieves unfetched rows and cleans up the available result sets.
       Lob getLob (const char *value)  throw ( std::exception )
           Creates a large object instance if supported by the database.
       odbxres getResult (struct timeval *timeout=NULL, unsigned long chunk=0)  throw (
           std::exception )
           Fetches one result set from the database server.
       odbxrow getRow ()  throw ( std::exception )
           Makes data of next row available.
       Result & operator= (const Result &ref)  throw ()
           Assigns a Result instance to another one.
       Result (const Result &ref)  throw ()
           Copy constructor.
       uint64_t rowsAffected ()  throw ( std::exception )
           Returns the number of rows affected by DELETE, INSERT of UPDATE statements.
       ~Result ()  throw ()
           Destroys a Result instance if no other references exist.

   Protected Member Functions
       Result ()  throw ()
           Default constructor.
       Result (Result_Iface *impl)  throw ( std::exception )
           Creates a Result instance.

Detailed Description

       Provides result sets from the database.

       Author:
           Norbert Sendetzky norbert@linuxnetworks.de

       Version:
           1.0

Constructor & Destructor Documentation

   OpenDBX::Result::Result () [inline],  [protected]
       Default constructor. The default constructor isn't part of the public interface as the
       object must not be created manually. Instead, the Stmt::execute() method is a factory for
       instances of the Result class.

       Returns:
           Result instance

   OpenDBX::Result::Result (Result_Iface * impl)std::exception [protected]
       Creates a Result instance. The constructor isn't part of the public interface as the
       object must not be created manually. Instead, the Stmt::execute() method is a factory for
       instances of the Result class.

       Parameters:
           impl Pointer to private implementation

       Exceptions:
           std::exception If an error occures

       Returns:
           Result instance

   OpenDBX::Result::~Result ()
       Destroys a Result instance if no other references exist. Each result object uses a
       reference counter to remember if the internal variables are shared with other objects. If
       this isn't the case or if this object is the last one referencing the variables, the
       object is cleanup up and the allocated memory freed.

   OpenDBX::Result::Result (const Result & ref)
       Copy constructor. Enables the transfer of the internal state of an object ref of the same
       type to this object. Both objects share the same variables and the reference counter
       afterwards. The reference counter is incremented each time an object is copied and will be
       decremented if it is destroyed.

       Parameters:
           ref Original result object instance

Member Function Documentation

   unsigned long OpenDBX::Result::columnCount ()std::exception
       Returns the number of columns available in this result set. The number of columns will
       never change within a result set with one notable exception: MySQL returns all outstanding
       rows of a previous result set first if they were not fetched completely by getRow()
       before. Therefore, the column count might change in this special situation.

       Returns:
           Number of columns

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

   const string OpenDBX::Result::columnName (unsigned long pos)std::exception
       Returns the name of the column in the current result set. Gets the name of the column
       specified by pos in the current result set. The column names will not change within the
       result set with the exception of MySQL when the first result set wasn't retrieved
       completely before getResult() was called again.

       Parameters:
           pos Position of column in result set

       Returns:
           Column name

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

   unsigned long OpenDBX::Result::columnPos (const string & name)std::exception
       Maps the column name to the column number required by other methods. This method returns
       the index of the column which is named like the content of the string given via the
       parameter name. The column index will not change within the result set.

       Parameters:
           name Name of the column in the result set

       Returns:
           Position of column in result set

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

   odbxtype OpenDBX::Result::columnType (unsigned long pos)std::exception
       Returns the type of the column in the current result set. The column type applies to all
       fields at the same position of the rows fetched via getRow(). The definitions are based on
       the SQL2003 standard and the data types of the database server have to comply to the
       specification of the standard. These are:

       Exact numeric values:

       · ODBX_TYPE_BOOLEAN: True/false values

       · ODBX_TYPE_SMALLINT: Signed 16 bit integer

       · ODBX_TYPE_INTEGER: Signed 32 bit integer

       · ODBX_TYPE_BIGINT: Signed 64 bit integer

       · ODBX_TYPE_DECIMAL: Exact signed numeric values with user defined precision

       Approximate numeric values:

       · ODBX_TYPE_REAL: Approximate numeric values (signed) with 32 bit precision

       · ODBX_TYPE_DOUBLE: Approximate numeric values (signed) with 64 bit precision

       · ODBX_TYPE_FLOAT: Approximate numeric values (signed) with user defined precision

       String values:

       · ODBX_TYPE_CHAR: Fixed number of characters

       · ODBX_TYPE_NCHAR: Fixed number of characters using a national character set

       · ODBX_TYPE_VARCHAR: Variable number of characters

       · ODBX_TYPE_NVARCHAR: Variable number of characters using a national character set

       Large objects:

       · ODBX_TYPE_CLOB: Large text object

       · ODBX_TYPE_NCLOB: Large text object using a national character set

       · ODBX_TYPE_XML: XML tree in text format

       · ODBX_TYPE_BLOB: Large binary object

       Date and time values:

       · ODBX_TYPE_TIME: Time including hours, minutes and seconds

       · ODBX_TYPE_TIME_TZ: Time with timezone information

       · ODBX_TYPE_TIMESTAMP: Date and time

       · ODBX_TYPE_TIMESTAMP_TZ: Date and time with timezone information

       · ODBX_TYPE_DATE: Date including year, month and day

       · ODBX_TYPE_INTERVAL: Date interval

       Arrays and sets:

       · ODBX_TYPE_ARRAY: Array of values

       · ODBX_TYPE_MULTISET: Associative arrays

       External links:

       · ODBX_TYPE_DATALINK: URI locators like URL links

       Data types provided by database implementations which are not covered by the SQL2003
       standard are subsumed as ODBX_TYPE_UNKNOWN.

       Parameters:
           pos Position of column in result set

       Returns:
           Column type

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

       See also:
           odbxtype

   unsigned long OpenDBX::Result::fieldLength (unsigned long pos)std::exception
       Returns the size of the content in the current row at the specified postion. The field is
       part of the current row which was retrieved by the latest call to getRow() and is
       specified by the column index given by pos.

       Parameters:
           pos Position of column in result set

       Returns:
           Size of the data in bytes

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

   const char* OpenDBX::Result::fieldValue (unsigned long pos)std::exception
       Returns a pointer to the content in the current row at the specified postion. This
       function returns a pointer to the field data specified by the column index pos. The field
       is part of the current row which was retrieved by the latest call to getRow(). All values
       except binary objects are handed back as strings terminated by the zero character. This
       does also apply to numeric values, dates, etc. They have to be converted to their binary
       machine dependent representation before arithmetic operations can be done. If a value is
       undefined, i.e. 'NULL' is attached to the field in the database, an equivalent NULL
       pointer is returned.

       Parameters:
           pos Position of column in result set

       Returns:
           Pointer to the data

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

   void OpenDBX::Result::finish ()std::exception
       Retrieves unfetched rows and cleans up the available result sets. After executing a
       statement, at least one result set is returned by the database server. In case of data
       manipulation statements, there are no rows returned but you have to clean up the result
       set nevertheless. This is usually done by calling and getResult() in a loop until it
       returns 'done'. In order to simplify application development, the finish() method does
       this for you.

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

   Lob OpenDBX::Result::getLob (const char * value)std::exception
       Creates a large object instance if supported by the database. Returns a Lob class instance
       representing a large object stored in the database. It references the large object and
       provided methods for accessing and modifying its content.

       The parameter required by this method must be the value returned by the fieldValue()
       method of a large object column.

       This method must only be used if the underlying driver states that it supports large
       objects via the Conn::getCapabilities(). Otherwise, the content can be retrieved directly
       by the fieldValue() method.

       Parameters:
           value Pointer to the content of a field returned by fieldValue()

       Returns:
           Large object instance

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

       See also:
           Lob

   odbxres OpenDBX::Result::getResult (struct timeval * timeout = NULL, unsigned long chunk =
       0)std::exception
       Fetches one result set from the database server. Retrieves the result of a query statement
       from the database server. If the statement was an INSERT, UPDATE, DELETE or a similar
       statement, the number of affected rows is available via rowsAffected().

       The timeout parameter restricts the time the function is waiting for a result form the
       server. It may be NULL to wait until a result arrives. Otherwise, it can contain any
       number of seconds and microseconds in a timeval structure to wait for. The timeval
       structure must be set each time before calling getResult() because its content may get
       changed by the function. If the server doesn't respond within the timeout, the query isn't
       canceled! Instead, the next call to this function will wait for the same result set.
       Waiting the specified time may be implemented in the backends if it is possible, but there
       is no guarantee. If not, getResult() will return not before a responds arrives.

       Dependent on the native database library, it may be possible to retrieve all rows at once
       (if chunk is zero), one by one or more than one row at once. All positive values including
       zero are allowed as values for chunk If paging (more than one row at once) is not
       supported by the backend, it will use 'one by one' or 'all at once' if this is the only
       option provided.

       getResult() returns ODBX_RES_ROWS if a result set is available and ODBX_RES_DONE if no
       more results will be returned by the last successful query. ODBX_RES_NOROWS is returned if
       the statement was executed successfully but will not return a results set (like for
       INSERT, UPDATE and DELETE statements) and ODBX_RES_TIMEOUT indicates a timeout.

       Parameters:
           timeout Pointer to a timeval struct specifying how long to wait for a result set from
           the database server
           chunk Number of rows to fetch at once from the database server (zero means all rows at
           once)

       Returns:
           Status or error code

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

       See also:
           odbxres

   odbxrow OpenDBX::Result::getRow ()std::exception
       Makes data of next row available. Retrieves the values of a row from the current result
       set returned by getResult(). Until this function is invoked, no row and field data is
       available via fieldLength() or fieldValue() and these functions will throw an exception.

       getRow() will return ODBX_ROW_NEXT as long as rows are available from the result set.
       After the last row has been made available, further calls to this function will return
       ODBX_ROW_DONE indicating that the result set doesn't contain more rows.

       Returns:
           Status of the attempt to fetch one more row

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

   Result& OpenDBX::Result::operator= (const Result & ref)
       Assigns a Result instance to another one. Assigns the internal state of an object ref of
       the same type to this object. Both objects share the same variables and the reference
       counter afterwards. The reference counter is incremented each time an object is copied and
       will be decremented if it is destroyed.

       Parameters:
           ref Result instance

       Returns:
           Result reference of this instance

   uint64_t OpenDBX::Result::rowsAffected ()std::exception
       Returns the number of rows affected by DELETE, INSERT of UPDATE statements. Returns the
       number of rows that have been changed by the current statement whose result set was
       retrieved by getResult() and zero if the database server didn't alter any rows. Affected
       rows are only returned for DELETE, INSERT or UPDATE statements and their concrete number
       depends on the database implementation. Some database server like MySQL may return a lower
       number than expected because they doesn't modify records whose values wouldn't change.

       Returns:
           Number of rows touched

       Exceptions:
           OpenDBX::Exception If the underlying database library returns an error

Author

       Generated automatically by Doxygen for opendbx from the source code.