.TH "OpenDBX::Result" 3 "Fri Sep 5 2014" "Version 1.4.6" "opendbx" \" -*- nroff -*-
.ad l
.nh
.SH NAME
OpenDBX::Result \- 
.PP
Provides result sets from the database\&.  

.SH SYNOPSIS
.br
.PP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "unsigned long \fBcolumnCount\fP ()  throw ( std::exception )"
.br
.RI "\fIReturns the number of columns available in this result set\&. \fP"
.ti -1c
.RI "const string \fBcolumnName\fP (unsigned long pos)  throw ( std::exception )"
.br
.RI "\fIReturns the name of the column in the current result set\&. \fP"
.ti -1c
.RI "unsigned long \fBcolumnPos\fP (const string &name)  throw ( std::exception )"
.br
.RI "\fIMaps the column name to the column number required by other methods\&. \fP"
.ti -1c
.RI "odbxtype \fBcolumnType\fP (unsigned long pos)  throw ( std::exception )"
.br
.RI "\fIReturns the type of the column in the current result set\&. \fP"
.ti -1c
.RI "unsigned long \fBfieldLength\fP (unsigned long pos)  throw ( std::exception )"
.br
.RI "\fIReturns the size of the content in the current row at the specified postion\&. \fP"
.ti -1c
.RI "const char * \fBfieldValue\fP (unsigned long pos)  throw ( std::exception )"
.br
.RI "\fIReturns a pointer to the content in the current row at the specified postion\&. \fP"
.ti -1c
.RI "void \fBfinish\fP ()  throw ( std::exception )"
.br
.RI "\fIRetrieves unfetched rows and cleans up the available result sets\&. \fP"
.ti -1c
.RI "\fBLob\fP \fBgetLob\fP (const char *value)  throw ( std::exception )"
.br
.RI "\fICreates a large object instance if supported by the database\&. \fP"
.ti -1c
.RI "odbxres \fBgetResult\fP (struct timeval *timeout=NULL, unsigned long chunk=0)  throw ( std::exception )"
.br
.RI "\fIFetches one result set from the database server\&. \fP"
.ti -1c
.RI "odbxrow \fBgetRow\fP ()  throw ( std::exception )"
.br
.RI "\fIMakes data of next row available\&. \fP"
.ti -1c
.RI "\fBResult\fP & \fBoperator=\fP (const \fBResult\fP &ref)  throw ()"
.br
.RI "\fIAssigns a \fBResult\fP instance to another one\&. \fP"
.ti -1c
.RI "\fBResult\fP (const \fBResult\fP &ref)  throw ()"
.br
.RI "\fICopy constructor\&. \fP"
.ti -1c
.RI "uint64_t \fBrowsAffected\fP ()  throw ( std::exception )"
.br
.RI "\fIReturns the number of rows affected by DELETE, INSERT of UPDATE statements\&. \fP"
.ti -1c
.RI "\fB~Result\fP ()  throw ()"
.br
.RI "\fIDestroys a \fBResult\fP instance if no other references exist\&. \fP"
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "\fBResult\fP ()  throw ()"
.br
.RI "\fIDefault constructor\&. \fP"
.ti -1c
.RI "\fBResult\fP (Result_Iface *impl)  throw ( std::exception )"
.br
.RI "\fICreates a \fBResult\fP instance\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
Provides result sets from the database\&. 


.PP
\fBAuthor:\fP
.RS 4
Norbert Sendetzky norbert@linuxnetworks.de 
.RE
.PP
\fBVersion:\fP
.RS 4
1\&.0 
.RE
.PP

.SH "Constructor & Destructor Documentation"
.PP 
.SS "OpenDBX::Result::Result ()\fC [inline]\fP, \fC [protected]\fP"

.PP
Default constructor\&. The default constructor isn't part of the public interface as the object must not be created manually\&. Instead, the \fBStmt::execute()\fP method is a factory for instances of the \fBResult\fP class\&.
.PP
\fBReturns:\fP
.RS 4
\fBResult\fP instance 
.RE
.PP

.SS "OpenDBX::Result::Result (Result_Iface *impl)std::exception\fC [protected]\fP"

.PP
Creates a \fBResult\fP instance\&. The constructor isn't part of the public interface as the object must not be created manually\&. Instead, the \fBStmt::execute()\fP method is a factory for instances of the \fBResult\fP class\&.
.PP
\fBParameters:\fP
.RS 4
\fIimpl\fP Pointer to private implementation 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fIstd::exception\fP If an error occures 
.RE
.PP
\fBReturns:\fP
.RS 4
\fBResult\fP instance 
.RE
.PP

.SS "OpenDBX::Result::~Result ()"

.PP
Destroys a \fBResult\fP 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\&. 
.SS "OpenDBX::Result::Result (const \fBResult\fP &ref)"

.PP
Copy constructor\&. Enables the transfer of the internal state of an object \fIref\fP 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIref\fP Original result object instance 
.RE
.PP

.SH "Member Function Documentation"
.PP 
.SS "unsigned long OpenDBX::Result::columnCount ()std::exception"

.PP
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 \fBgetRow()\fP before\&. Therefore, the column count might change in this special situation\&.
.PP
\fBReturns:\fP
.RS 4
Number of columns 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "const string OpenDBX::Result::columnName (unsigned longpos)std::exception"

.PP
Returns the name of the column in the current result set\&. Gets the name of the column specified by \fIpos\fP 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 \fBgetResult()\fP was called again\&.
.PP
\fBParameters:\fP
.RS 4
\fIpos\fP Position of column in result set 
.RE
.PP
\fBReturns:\fP
.RS 4
Column name 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "unsigned long OpenDBX::Result::columnPos (const string &name)std::exception"

.PP
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 \fIname\fP\&. The column index will not change within the result set\&.
.PP
\fBParameters:\fP
.RS 4
\fIname\fP Name of the column in the result set 
.RE
.PP
\fBReturns:\fP
.RS 4
Position of column in result set 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "odbxtype OpenDBX::Result::columnType (unsigned longpos)std::exception"

.PP
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 \fBgetRow()\fP\&. 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:
.PP
Exact numeric values:
.IP "\(bu" 2
ODBX_TYPE_BOOLEAN: True/false values
.IP "\(bu" 2
ODBX_TYPE_SMALLINT: Signed 16 bit integer
.IP "\(bu" 2
ODBX_TYPE_INTEGER: Signed 32 bit integer
.IP "\(bu" 2
ODBX_TYPE_BIGINT: Signed 64 bit integer
.IP "\(bu" 2
ODBX_TYPE_DECIMAL: Exact signed numeric values with user defined precision
.PP
.PP
Approximate numeric values:
.IP "\(bu" 2
ODBX_TYPE_REAL: Approximate numeric values (signed) with 32 bit precision
.IP "\(bu" 2
ODBX_TYPE_DOUBLE: Approximate numeric values (signed) with 64 bit precision
.IP "\(bu" 2
ODBX_TYPE_FLOAT: Approximate numeric values (signed) with user defined precision
.PP
.PP
String values:
.IP "\(bu" 2
ODBX_TYPE_CHAR: Fixed number of characters
.IP "\(bu" 2
ODBX_TYPE_NCHAR: Fixed number of characters using a national character set
.IP "\(bu" 2
ODBX_TYPE_VARCHAR: Variable number of characters
.IP "\(bu" 2
ODBX_TYPE_NVARCHAR: Variable number of characters using a national character set
.PP
.PP
Large objects:
.IP "\(bu" 2
ODBX_TYPE_CLOB: Large text object
.IP "\(bu" 2
ODBX_TYPE_NCLOB: Large text object using a national character set
.IP "\(bu" 2
ODBX_TYPE_XML: XML tree in text format
.IP "\(bu" 2
ODBX_TYPE_BLOB: Large binary object
.PP
.PP
Date and time values:
.IP "\(bu" 2
ODBX_TYPE_TIME: Time including hours, minutes and seconds
.IP "\(bu" 2
ODBX_TYPE_TIME_TZ: Time with timezone information
.IP "\(bu" 2
ODBX_TYPE_TIMESTAMP: Date and time
.IP "\(bu" 2
ODBX_TYPE_TIMESTAMP_TZ: Date and time with timezone information
.IP "\(bu" 2
ODBX_TYPE_DATE: Date including year, month and day
.IP "\(bu" 2
ODBX_TYPE_INTERVAL: Date interval
.PP
.PP
Arrays and sets:
.IP "\(bu" 2
ODBX_TYPE_ARRAY: Array of values
.IP "\(bu" 2
ODBX_TYPE_MULTISET: Associative arrays
.PP
.PP
External links:
.IP "\(bu" 2
ODBX_TYPE_DATALINK: URI locators like URL links
.PP
.PP
Data types provided by database implementations which are not covered by the SQL2003 standard are subsumed as ODBX_TYPE_UNKNOWN\&.
.PP
\fBParameters:\fP
.RS 4
\fIpos\fP Position of column in result set 
.RE
.PP
\fBReturns:\fP
.RS 4
Column type 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP
\fBSee also:\fP
.RS 4
odbxtype 
.RE
.PP

.SS "unsigned long OpenDBX::Result::fieldLength (unsigned longpos)std::exception"

.PP
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 \fBgetRow()\fP and is specified by the column index given by \fIpos\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIpos\fP Position of column in result set 
.RE
.PP
\fBReturns:\fP
.RS 4
Size of the data in bytes 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "const char* OpenDBX::Result::fieldValue (unsigned longpos)std::exception"

.PP
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 \fIpos\fP\&. The field is part of the current row which was retrieved by the latest call to \fBgetRow()\fP\&. 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIpos\fP Position of column in result set 
.RE
.PP
\fBReturns:\fP
.RS 4
Pointer to the data 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "void OpenDBX::Result::finish ()std::exception"

.PP
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 \fBgetResult()\fP in a loop until it returns 'done'\&. In order to simplify application development, the \fBfinish()\fP method does this for you\&.
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "\fBLob\fP OpenDBX::Result::getLob (const char *value)std::exception"

.PP
Creates a large object instance if supported by the database\&. Returns a \fBLob\fP class instance representing a large object stored in the database\&. It references the large object and provided methods for accessing and modifying its content\&.
.PP
The parameter required by this method must be the value returned by the \fBfieldValue()\fP method of a large object column\&.
.PP
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 \fBfieldValue()\fP method\&.
.PP
\fBParameters:\fP
.RS 4
\fIvalue\fP Pointer to the content of a field returned by \fBfieldValue()\fP 
.RE
.PP
\fBReturns:\fP
.RS 4
Large object instance 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBLob\fP 
.RE
.PP

.SS "odbxres OpenDBX::Result::getResult (struct timeval *timeout = \fCNULL\fP, unsigned longchunk = \fC0\fP)std::exception"

.PP
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 \fBrowsAffected()\fP\&.
.PP
The \fItimeout\fP 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 \fBgetResult()\fP 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, \fBgetResult()\fP will return not before a responds arrives\&.
.PP
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 \fIchunk\fP 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\&.
.PP
\fBgetResult()\fP 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\&.
.PP
\fBParameters:\fP
.RS 4
\fItimeout\fP Pointer to a timeval struct specifying how long to wait for a result set from the database server 
.br
\fIchunk\fP Number of rows to fetch at once from the database server (zero means all rows at once) 
.RE
.PP
\fBReturns:\fP
.RS 4
Status or error code 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP
\fBSee also:\fP
.RS 4
odbxres 
.RE
.PP

.SS "odbxrow OpenDBX::Result::getRow ()std::exception"

.PP
Makes data of next row available\&. Retrieves the values of a row from the current result set returned by \fBgetResult()\fP\&. Until this function is invoked, no row and field data is available via \fBfieldLength()\fP or \fBfieldValue()\fP and these functions will throw an exception\&.
.PP
\fBgetRow()\fP 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\&.
.PP
\fBReturns:\fP
.RS 4
Status of the attempt to fetch one more row 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "\fBResult\fP& OpenDBX::Result::operator= (const \fBResult\fP &ref)"

.PP
Assigns a \fBResult\fP instance to another one\&. Assigns the internal state of an object \fIref\fP 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIref\fP \fBResult\fP instance 
.RE
.PP
\fBReturns:\fP
.RS 4
\fBResult\fP reference of this instance 
.RE
.PP

.SS "uint64_t OpenDBX::Result::rowsAffected ()std::exception"

.PP
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 \fBgetResult()\fP 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\&.
.PP
\fBReturns:\fP
.RS 4
Number of rows touched 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP


.SH "Author"
.PP 
Generated automatically by Doxygen for opendbx from the source code\&.