.TH "OpenDBX" 3 "Thu May 11 2023" "Version 1.4.6" "opendbx" \" -*- nroff -*-
.ad l
.nh
.SH NAME
OpenDBX \- \fBOpenDBX\fP C++ API\&.  

.SH SYNOPSIS
.br
.PP
.SS "Classes"

.in +1c
.ti -1c
.RI "class \fBConn\fP"
.br
.RI "Encapsulates a connection to a database\&. "
.ti -1c
.RI "class \fBException\fP"
.br
.RI "Exceptions thrown by the \fBOpenDBX\fP classes\&. "
.ti -1c
.RI "class \fBLob\fP"
.br
.RI "Handling large objects if supported by the database\&. "
.ti -1c
.RI "class \fBResult\fP"
.br
.RI "Provides result sets from the database\&. "
.ti -1c
.RI "class \fBStmt\fP"
.br
.RI "Statement object\&. "
.in -1c
.SH "Detailed Description"
.PP 
\fBOpenDBX\fP C++ API\&. 

The \fBOpenDBX\fP C++ API is an object-oriented database abstraction layer based on the procedural C API of the \fBOpenDBX\fP library\&. The C++ API provides objects encapsulating connections, statements, result sets and large objects\&.
.PP
Using the API starts with establishing a connection to the database server by creating an instance of the \fBConn\fP class with the parameters backend, host and port\&. \fBConn::getCapability()\fP tests the implemented capabilites of the underlying database library while \fBConn::getOption()\fP and \fBConn::setOption()\fP has be used to test for and change a number of options\&. The options must be changed before authenticating the connection with the \fBConn::bind()\fP method to have any effect\&. It's also possible to rebind a connection using different credentials after \fBConn::unbind()\fP had been called\&. Additionally, the \fBConn\fP class is able to escape potentially dangerous character sequences with \fBConn::escape()\fP if e\&.g\&. user input should be part of a statement as value\&.
.PP
The \fBConn::create()\fP method creates and initializes a new statement instance from a SQL string\&. Currently, there are only simple statement objects implemented, which needs to be complete statements which can be sent to the database with \fBStmt::execute()\fP\&. This method returns a \fBResult\fP object encapsulating one or more result sets returned by the database depending on the statement sent\&.
.PP
Each result set must be retrieved using \fBResult::getResult()\fP, while Result::getRows() fetches a row from the current result set if the statement was a SELECT like statement\&. Otherwise, \fBResult::rowsAffected()\fP can be used to get the number of rows that were touched by the statement\&. If the statement may return rows, the \fBResult::columnName()\fP and \fBResult::columnType()\fP methods are able to provide some informations about the columns indexed from 0 to n\&. It's also possible to map the column name with the \fBResult::columnPos()\fP method to the column index which is required be the other column methods\&. To get the actual value and length of the content in the current row at the given position, the \fBResult::fieldValue()\fP and \fBResult::fieldLength()\fP must be called\&.
.PP
In case the unterlying database library requires special handling of large objects (binary or text LOBs), the value of \fBResult::fieldValue()\fP has to be feed into the \fBResult::getLob()\fP method\&. It returns a \fBLob\fP object which enables the application to read from and write to a large object using \fBLob::read()\fP respectively \fBLob::write()\fP\&. This is only necessary if the \fBConn::getCapability()\fP method returns true when asking for ODBX_CAP_LO\&.
.PP
If an error occurs in any of the object methods, the objects will throw an instance of the \fBException\fP class with extends the runtime_error exception of the STL\&. The instance contains an error message, the \fBOpenDBX\fP error code and an error type indicating the severity of the error\&. This information can be retrieved by the methods Exception::what(), \fBException::getCode()\fP and \fBException::getType()\fP\&.
.PP
\fBAuthor\fP
.RS 4
Norbert Sendetzky norbert@linuxnetworks.de 
.RE
.PP
\fBVersion\fP
.RS 4
1\&.0 
.RE
.PP

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