From 00b961c37f82977615ab9c4d03e185229cc55154 Mon Sep 17 00:00:00 2001 From: Casper van Donderen Date: Fri, 27 Apr 2012 15:18:27 +0200 Subject: Doc: Fix most qdoc errors in QtSql. - Move 2 images from qtdoc. - Add "make docs" command for qtsql - Fix qdoc command usage errors. Change-Id: Id2f0548d09ed8f77b2317863d443c19d1cccdd83 Reviewed-by: Lars Knoll --- src/sql/doc/doc.pri | 3 + src/sql/doc/images/foreignkeys.png | Bin 0 -> 3739 bytes src/sql/doc/images/insertrowinmodelview.png | Bin 0 -> 3867 bytes src/sql/doc/images/noforeignkeys.png | Bin 0 -> 3282 bytes src/sql/doc/images/qdatawidgetmapper-simple.png | Bin 0 -> 26994 bytes src/sql/doc/images/relationaltable.png | Bin 0 -> 4274 bytes src/sql/doc/qtsql.qdocconf | 92 +++ src/sql/doc/snippets/code/doc_src_qtsql.cpp | 43 ++ src/sql/doc/snippets/code/doc_src_qtsql.pro | 3 + src/sql/doc/snippets/code/doc_src_sql-driver.cpp | 82 ++ src/sql/doc/snippets/code/doc_src_sql-driver.qdoc | 235 ++++++ .../snippets/code/src_sql_kernel_qsqldatabase.cpp | 135 ++++ .../snippets/code/src_sql_kernel_qsqldriver.cpp | 64 ++ .../doc/snippets/code/src_sql_kernel_qsqlerror.cpp | 46 ++ .../doc/snippets/code/src_sql_kernel_qsqlquery.cpp | 80 ++ .../snippets/code/src_sql_kernel_qsqlresult.cpp | 85 +++ .../code/src_sql_models_qsqlquerymodel.cpp | 52 ++ src/sql/doc/snippets/sqldatabase/sqldatabase.cpp | 559 ++++++++++++++ src/sql/doc/src/qsqldatatype-table.qdoc | 570 ++++++++++++++ src/sql/doc/src/qtsql.qdoc | 45 ++ src/sql/doc/src/sql-driver.qdoc | 830 +++++++++++++++++++++ src/sql/doc/src/sql-programming.qdoc | 609 +++++++++++++++ src/sql/kernel/qsql.qdoc | 2 +- src/sql/kernel/qsqldatabase.cpp | 60 +- src/sql/kernel/qsqldriver.cpp | 42 +- src/sql/kernel/qsqlerror.cpp | 12 +- src/sql/kernel/qsqlfield.cpp | 59 +- src/sql/kernel/qsqlquery.cpp | 69 +- src/sql/kernel/qsqlrecord.cpp | 20 +- src/sql/kernel/qsqlresult.cpp | 6 +- src/sql/models/qsqlquerymodel.cpp | 12 +- src/sql/models/qsqlrelationaldelegate.cpp | 2 +- src/sql/models/qsqlrelationaltablemodel.cpp | 12 +- src/sql/models/qsqltablemodel.cpp | 4 +- src/sql/sql.pro | 1 + 35 files changed, 3667 insertions(+), 167 deletions(-) create mode 100644 src/sql/doc/doc.pri create mode 100644 src/sql/doc/images/foreignkeys.png create mode 100644 src/sql/doc/images/insertrowinmodelview.png create mode 100644 src/sql/doc/images/noforeignkeys.png create mode 100644 src/sql/doc/images/qdatawidgetmapper-simple.png create mode 100644 src/sql/doc/images/relationaltable.png create mode 100644 src/sql/doc/qtsql.qdocconf create mode 100644 src/sql/doc/snippets/code/doc_src_qtsql.cpp create mode 100644 src/sql/doc/snippets/code/doc_src_qtsql.pro create mode 100644 src/sql/doc/snippets/code/doc_src_sql-driver.cpp create mode 100644 src/sql/doc/snippets/code/doc_src_sql-driver.qdoc create mode 100644 src/sql/doc/snippets/code/src_sql_kernel_qsqldatabase.cpp create mode 100644 src/sql/doc/snippets/code/src_sql_kernel_qsqldriver.cpp create mode 100644 src/sql/doc/snippets/code/src_sql_kernel_qsqlerror.cpp create mode 100644 src/sql/doc/snippets/code/src_sql_kernel_qsqlquery.cpp create mode 100644 src/sql/doc/snippets/code/src_sql_kernel_qsqlresult.cpp create mode 100644 src/sql/doc/snippets/code/src_sql_models_qsqlquerymodel.cpp create mode 100644 src/sql/doc/snippets/sqldatabase/sqldatabase.cpp create mode 100644 src/sql/doc/src/qsqldatatype-table.qdoc create mode 100644 src/sql/doc/src/qtsql.qdoc create mode 100644 src/sql/doc/src/sql-driver.qdoc create mode 100644 src/sql/doc/src/sql-programming.qdoc (limited to 'src') diff --git a/src/sql/doc/doc.pri b/src/sql/doc/doc.pri new file mode 100644 index 0000000000..2bc2e005d4 --- /dev/null +++ b/src/sql/doc/doc.pri @@ -0,0 +1,3 @@ +qtPrepareTool(QDOC, qdoc) +docs.commands += $$QDOC $$QT.sql.sources/doc/qtsql.qdocconf +QMAKE_EXTRA_TARGETS += docs diff --git a/src/sql/doc/images/foreignkeys.png b/src/sql/doc/images/foreignkeys.png new file mode 100644 index 0000000000..7a6a19bb43 Binary files /dev/null and b/src/sql/doc/images/foreignkeys.png differ diff --git a/src/sql/doc/images/insertrowinmodelview.png b/src/sql/doc/images/insertrowinmodelview.png new file mode 100644 index 0000000000..bddc401ad2 Binary files /dev/null and b/src/sql/doc/images/insertrowinmodelview.png differ diff --git a/src/sql/doc/images/noforeignkeys.png b/src/sql/doc/images/noforeignkeys.png new file mode 100644 index 0000000000..62a4452277 Binary files /dev/null and b/src/sql/doc/images/noforeignkeys.png differ diff --git a/src/sql/doc/images/qdatawidgetmapper-simple.png b/src/sql/doc/images/qdatawidgetmapper-simple.png new file mode 100644 index 0000000000..784a433c0b Binary files /dev/null and b/src/sql/doc/images/qdatawidgetmapper-simple.png differ diff --git a/src/sql/doc/images/relationaltable.png b/src/sql/doc/images/relationaltable.png new file mode 100644 index 0000000000..bdfd40f703 Binary files /dev/null and b/src/sql/doc/images/relationaltable.png differ diff --git a/src/sql/doc/qtsql.qdocconf b/src/sql/doc/qtsql.qdocconf new file mode 100644 index 0000000000..85e0cfc9f1 --- /dev/null +++ b/src/sql/doc/qtsql.qdocconf @@ -0,0 +1,92 @@ +include(../../../doc/global/qt-cpp-ignore.qdocconf) + +project = QtSql +description = Qt SQL Reference Documentation +url = http://qt-project.org/doc/qt-5.0/qtsql +version = 5.0.0 + +sourceencoding = UTF-8 +outputencoding = UTF-8 +naturallanguage = en_US +qhp.projects = QtSql + +qhp.QtCore.file = qtsql.qhp +qhp.Qt.namespace = org.qt-project.qtsql.500 +qhp.Qt.virtualFolder = qdoc +qhp.Qt.indexTitle = Qt SQL Reference Documentation +qhp.Qt.indexRoot = + +qhp.Qt.filterAttributes = qtsql 5.0.0 qtrefdoc +qhp.Qt.customFilters.Qt.name = QtSql 5.0.0 +qhp.Qt.customFilters.Qt.filterAttributes = qtsql 5.0.0 +qhp.Qt.subprojects = classes overviews examples +qhp.Qt.subprojects.classes.title = Classes +qhp.Qt.subprojects.classes.indexTitle = Qt SQL's Classes +qhp.Qt.subprojects.classes.selectors = class fake:headerfile +qhp.Qt.subprojects.classes.sortPages = true +qhp.Qt.subprojects.overviews.title = Overviews +qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs +qhp.Qt.subprojects.overviews.selectors = fake:page,group,module +qhp.Qt.subprojects.examples.title = Qt Core Tutorials and Examples +qhp.Qt.subprojects.examples.indexTitle = Qt Core Examples +qhp.Qt.subprojects.examples.selectors = fake:example + +dita.metadata.default.author = Qt Project +dita.metadata.default.permissions = all +dita.metadata.default.publisher = Qt Project +dita.metadata.default.copyryear = 2012 +dita.metadata.default.copyrholder = Nokia +dita.metadata.default.audience = programmer + +sources.fileextensions = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc" +headers.fileextensions = "*.ch *.h *.h++ *.hh *.hpp *.hxx" + +examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css" +examples.imageextensions = "*.png" + +outputdir = ../../../doc/qtsql +tagfile = ../../../doc/qtsql/qtsql.tags + +HTML.generatemacrefs = "true" +HTML.nobreadcrumbs = "true" + +HTML.templatedir = . + +HTML.stylesheets = ../../../doc/global/style/offline.css + +HTML.headerstyles = \ + " \n" + +HTML.endheader = \ + "\n" \ + +defines = Q_QDOC \ + QT_.*_SUPPORT \ + QT_.*_LIB \ + QT_COMPAT \ + QT_KEYPAD_NAVIGATION \ + QT_NO_EGL \ + Q_WS_.* \ + Q_OS_.* \ + Q_BYTE_ORDER \ + QT_DEPRECATED \ + QT_DEPRECATED_* \ + Q_NO_USING_KEYWORD \ + __cplusplus \ + Q_COMPILER_INITIALIZER_LISTS + +versionsym = QT_VERSION_STR + +codeindent = 1 + +depends += qtcore + +headerdirs += .. + +sourcedirs += .. + +exampledirs += ../../../examples \ + ../ \ + snippets + +imagedirs += images diff --git a/src/sql/doc/snippets/code/doc_src_qtsql.cpp b/src/sql/doc/snippets/code/doc_src_qtsql.cpp new file mode 100644 index 0000000000..88b80ba710 --- /dev/null +++ b/src/sql/doc/snippets/code/doc_src_qtsql.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include +//! [0] diff --git a/src/sql/doc/snippets/code/doc_src_qtsql.pro b/src/sql/doc/snippets/code/doc_src_qtsql.pro new file mode 100644 index 0000000000..1fb8e4dea3 --- /dev/null +++ b/src/sql/doc/snippets/code/doc_src_qtsql.pro @@ -0,0 +1,3 @@ +#! [1] +QT += sql +#! [1] diff --git a/src/sql/doc/snippets/code/doc_src_sql-driver.cpp b/src/sql/doc/snippets/code/doc_src_sql-driver.cpp new file mode 100644 index 0000000000..5ad00eae3c --- /dev/null +++ b/src/sql/doc/snippets/code/doc_src_sql-driver.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [2] +QSqlQuery q; +q.exec("call qtestproc (@outval1, @outval2)"); +q.exec("select @outval1, @outval2"); +q.next(); +qDebug() << q.value(0) << q.value(1); // outputs "42" and "43" +//! [2] + + +//! [10] +// STORED_PROC uses the return statement or returns multiple result sets +QSqlQuery query; +query.setForwardOnly(true); +query.exec("{call STORED_PROC}"); +//! [10] + + +//! [24] +db.setHostName("MyServer"); +db.setDatabaseName("C:\\test.gdb"); +//! [24] + + +//! [25] +// connect to database using the Latin-1 character set +db.setConnectOptions("ISC_DPB_LC_CTYPE=Latin1"); +db.open(); +//! [25] + + +//! [26] +QSqlQuery q; +q.exec("execute procedure my_procedure"); +q.next(); +qDebug() << q.value(0); // outputs the first RETURN/OUT value +//! [26] + + +//! [31] +QSqlDatabase: QMYSQL driver not loaded +QSqlDatabase: available drivers: QMYSQL +//! [31] diff --git a/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc b/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc new file mode 100644 index 0000000000..3fe8d6fbbd --- /dev/null +++ b/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc @@ -0,0 +1,235 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +-no-sql- ... Disable SQL entirely. +-qt-sql- ... Enable a SQL in the Qt Library, by default + none are turned on. +-plugin-sql- Enable SQL as a plugin to be linked to + at run time. + + Possible values for : + [ db2 ibase mysql oci odbc psql sqlite sqlite2 tds ] +//! [0] + + +//! [1] +create procedure qtestproc (OUT param1 INT, OUT param2 INT) +BEGIN + set param1 = 42; + set param2 = 43; +END +//! [1] + + +//! [3] +cd $QTDIR/src/plugins/sqldrivers/mysql +qmake "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient_r" mysql.pro +make +//! [3] + + +//! [4] +cd $QTDIR/src/plugins/sqldrivers/mysql +make install +//! [4] + + +//! [5] +cd %QTDIR%\src\plugins\sqldrivers\mysql +qmake "INCLUDEPATH+=C:\MySQL\include" "LIBS+=C:\MYSQL\MySQL Server \lib\opt\libmysql.lib" mysql.pro +nmake +//! [5] + + +//! [6] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc9" oci.pro +make +//! [6] + + +//! [7] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=/usr/include/oracle/10.1.0.3/client/" "LIBS+=-L/usr/lib/oracle/10.1.0.3/client/lib -lclntsh" oci.pro +make +//! [7] + + +//! [8] +set INCLUDE=%INCLUDE%;c:\oracle\oci\include +set LIB=%LIB%;c:\oracle\oci\lib\msvc +cd %QTDIR%\src\plugins\sqldrivers\oci +qmake oci.pro +nmake +//! [8] + + +//! [9] +set PATH=%PATH%;c:\oracle\bin +//! [9] + + +//! [11] +cd $QTDIR/src/plugins/sqldrivers/odbc +qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc" +make +//! [11] + + +//! [12] +cd %QTDIR%\src\plugins\sqldrivers\odbc +qmake odbc.pro +nmake +//! [12] + + +//! [13] +cd $QTDIR/src/plugins/sqldrivers/psql +qmake "INCLUDEPATH+=/usr/include/pgsql" "LIBS+=-L/usr/lib -lpq" psql.pro +make +//! [13] + + +//! [14] +cd $QTDIR/src/plugins/sqldrivers/psql +make install +//! [14] + + +//! [15] +cd %QTDIR%\src\plugins\sqldrivers\psql +qmake "INCLUDEPATH+=C:\psql\include" "LIBS+=C:\psql\lib\ms\libpq.lib" psql.pro +nmake +//! [15] + + +//! [16] +cd $QTDIR/src/plugins/sqldrivers/tds +qmake "INCLUDEPATH=$SYBASE/include" "LIBS=-L$SYBASE/lib -lsybdb" +make +//! [16] + + +//! [17] +cd %QTDIR%\src\plugins\sqldrivers\tds +qmake "LIBS+=NTWDBLIB.LIB" tds.pro +nmake +//! [17] + + +//! [18] +cd $QTDIR/src/plugins/sqldrivers/db2 +qmake "INCLUDEPATH+=$DB2DIR/include" "LIBS+=-L$DB2DIR/lib -ldb2" +make +//! [18] + + +//! [19] +cd $QTDIR/src/plugins/sqldrivers/db2 +make install +//! [19] + + +//! [20] +cd %QTDIR%\src\plugins\sqldrivers\db2 +qmake "INCLUDEPATH+=/sqllib/include" "LIBS+=/sqllib/lib/db2cli.lib" +nmake +//! [20] + + +//! [21] +cd $QTDIR/src/plugins/sqldrivers/sqlite +qmake "INCLUDEPATH+=$SQLITE/include" "LIBS+=-L$SQLITE/lib -lsqlite" +make +//! [21] + + +//! [22] +cd $QTDIR/src/plugins/sqldrivers/sqlite +make install +//! [22] + + +//! [23] +cd %QTDIR%\src\plugins\sqldrivers\sqlite +qmake "INCLUDEPATH+=C:\SQLITE\INCLUDE" "LIBS+=C:\SQLITE\LIB\SQLITE3.LIB" sqlite.pro +nmake +//! [23] + + +//! [27] +cd $QTDIR/src/plugins/sqldrivers/ibase +qmake "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro +make +//! [27] + + +//! [28] +cd $QTDIR/src/plugins/sqldrivers/ibase +qmake "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib -lfbclient" ibase.pro +make +//! [28] + + +//! [29] +cd %QTDIR%\src\plugins\sqldrivers\ibase +qmake "INCLUDEPATH+=C:\interbase\include" ibase.pro +nmake +//! [29] + + +//! [30] +cd %QTDIR%\src\plugins\sqldrivers\ibase +qmake "INCLUDEPATH+=C:\interbase\include" "LIBS+=-lfbclient" ibase.pro +nmake +//! [30] + + +//! [32] +configure -I /usr/include/oracle/10.1.0.3/client -L /usr/lib/oracle/10.1.0.3/client/lib -R /usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10 +make +//! [32] + +//! [33] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=/usr/include/oracle/10.1.0.3/client" "LIBS+=-L/usr/lib/oracle/10.1.0.3/client/lib -Wl,-rpath,/usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10" oci.pro +make +//! [33] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqldatabase.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqldatabase.cpp new file mode 100644 index 0000000000..d181b6eb14 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqldatabase.cpp @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// WRONG +QSqlDatabase db = QSqlDatabase::database("sales"); +QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db); +QSqlDatabase::removeDatabase("sales"); // will output a warning + +// "db" is now a dangling invalid database connection, +// "query" contains an invalid result set +//! [0] + + +//! [1] +{ + QSqlDatabase db = QSqlDatabase::database("sales"); + QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db); +} +// Both "db" and "query" are destroyed because they are out of scope +QSqlDatabase::removeDatabase("sales"); // correct +//! [1] + + +//! [2] +QSqlDatabase::registerSqlDriver("MYDRIVER", + new QSqlDriverCreator); +QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER"); +//! [2] + + +//! [3] +... +db = QSqlDatabase::addDatabase("QODBC"); +db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb)};FIL={MS Access};DBQ=myaccessfile.mdb"); +if (db.open()) { + // success! +} +... +//! [3] + + +//! [4] +... +// MySQL connection +db.setConnectOptions("CLIENT_SSL=1;CLIENT_IGNORE_SPACE=1"); // use an SSL connection to the server +if (!db.open()) { + db.setConnectOptions(); // clears the connect option string + ... +} +... +// PostgreSQL connection +db.setConnectOptions("requiressl=1"); // enable PostgreSQL SSL connections +if (!db.open()) { + db.setConnectOptions(); // clear options + ... +} +... +// ODBC connection +db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); // set ODBC options +if (!db.open()) { + db.setConnectOptions(); // don't try to set this option + ... +} +//! [4] + + +//! [5] +#include "qtdir/src/sql/drivers/psql/qsql_psql.cpp" +//! [5] + + +//! [6] +PGconn *con = PQconnectdb("host=server user=bart password=simpson dbname=springfield"); +QPSQLDriver *drv = new QPSQLDriver(con); +QSqlDatabase db = QSqlDatabase::addDatabase(drv); // becomes the new default connection +QSqlQuery query; +query.exec("SELECT NAME, ID FROM STAFF"); +... +//! [6] + + +//! [7] +unix:LIBS += -lpq +win32:LIBS += libpqdll.lib +//! [7] + + +//! [8] +QSqlDatabase db; +qDebug() << db.isValid(); // Returns false + +db = QSqlDatabase::database("sales"); +qDebug() << db.isValid(); // Returns true if "sales" connection exists + +QSqlDatabase::removeDatabase("sales"); +qDebug() << db.isValid(); // Returns false +//! [8] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqldriver.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqldriver.cpp new file mode 100644 index 0000000000..254a35aba2 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqldriver.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlDatabase db = ...; +QVariant v = db.driver()->handle(); +if (v.isValid() && qstrcmp(v.typeName(), "sqlite3*")==0) { + // v.data() returns a pointer to the handle + sqlite3 *handle = *static_cast(v.data()); + if (handle != 0) { // check that it is not NULL + ... + } +} +//! [0] + + +//! [1] +if (v.typeName() == "PGconn*") { + PGconn *handle = *static_cast(v.data()); + if (handle != 0) ... +} + +if (v.typeName() == "MYSQL*") { + MYSQL *handle = *static_cast(v.data()); + if (handle != 0) ... +} +//! [1] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqlerror.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqlerror.cpp new file mode 100644 index 0000000000..9914206193 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqlerror.cpp @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlQueryModel model; +model.setQuery("select * from myTable"); +if (model.lastError().isValid()) + qDebug() << model.lastError(); +//! [0] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqlquery.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqlquery.cpp new file mode 100644 index 0000000000..c540f8bd59 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqlquery.cpp @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +SELECT forename, surname FROM people; +//! [0] + + +//! [1] +QSqlQuery q("select * from employees"); +QSqlRecord rec = q.record(); + +qDebug() << "Number of columns: " << rec.count(); + +int nameCol = rec.indexOf("name"); // index of the field "name" +while (q.next()) + qDebug() << q.value(nameCol).toString(); // output all names +//! [1] + + +//! [2] +QSqlQuery q; +q.prepare("insert into myTable values (?, ?)"); + +QVariantList ints; +ints << 1 << 2 << 3 << 4; +q.addBindValue(ints); + +QVariantList names; +names << "Harald" << "Boris" << "Trond" << QVariant(QVariant::String); +q.addBindValue(names); + +if (!q.execBatch()) + qDebug() << q.lastError(); +//! [2] + + +//! [3] +1 Harald +2 Boris +3 Trond +4 NULL +//! [3] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqlresult.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqlresult.cpp new file mode 100644 index 0000000000..773af85ab9 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqlresult.cpp @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlQuery q; +q.prepare("insert into test (i1, i2, s) values (?, ?, ?)"); + +QVariantList col1; +QVariantList col2; +QVariantList col3; + +col1 << 1 << 3; +col2 << 2 << 4; +col3 << "hello" << "world"; + +q.bindValue(0, col1); +q.bindValue(1, col2); +q.bindValue(2, col3); + +if (!q.execBatch()) + qDebug() << q.lastError(); +//! [0] + + +//! [1] +QSqlQuery query = ... +QVariant v = query.result()->handle(); +if (v.isValid() && qstrcmp(v.typeName(), "sqlite3_stmt*")) { + // v.data() returns a pointer to the handle + sqlite3_stmt *handle = *static_cast(v.data()); + if (handle != 0) { // check that it is not NULL + ... + } +} +//! [1] + + +//! [2] +if (v.typeName() == "PGresult*") { + PGresult *handle = *static_cast(v.data()); + if (handle != 0) ... +} + +if (v.typeName() == "MYSQL_STMT*") { + MYSQL_STMT *handle = *static_cast(v.data()); + if (handle != 0) ... +} +//! [2] diff --git a/src/sql/doc/snippets/code/src_sql_models_qsqlquerymodel.cpp b/src/sql/doc/snippets/code/src_sql_models_qsqlquerymodel.cpp new file mode 100644 index 0000000000..71c96b0207 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_models_qsqlquerymodel.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +while (myModel->canFetchMore()) + myModel->fetchMore(); +//! [0] + + +//! [1] +QSqlQueryModel model; +model.setQuery("select * from MyTable"); +if (model.lastError().isValid()) + qDebug() << model.lastError(); +//! [1] diff --git a/src/sql/doc/snippets/sqldatabase/sqldatabase.cpp b/src/sql/doc/snippets/sqldatabase/sqldatabase.cpp new file mode 100644 index 0000000000..81f806309a --- /dev/null +++ b/src/sql/doc/snippets/sqldatabase/sqldatabase.cpp @@ -0,0 +1,559 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include + +#include + +using namespace std; + +QString tr(const char *text) +{ + return QApplication::translate(text, text); +} + +void QSqlDatabase_snippets() +{ + { +//! [0] + QSqlDatabase db = QSqlDatabase::addDatabase("QPSQL"); + db.setHostName("acidalia"); + db.setDatabaseName("customdb"); + db.setUserName("mojito"); + db.setPassword("J0a1m8"); + bool ok = db.open(); +//! [0] + Q_UNUSED(ok); + } + + { +//! [1] + QSqlDatabase db = QSqlDatabase::database(); +//! [1] + } +} + +void QSqlField_snippets() +{ +#if 0 + { +//! [2] + QSqlField field("age", QVariant::Int); + field.setValue(QPixmap()); // WRONG +//! [2] + } +#endif + + { +//! [3] + QSqlField field("age", QVariant::Int); + field.setValue(QString("123")); // casts QString to int +//! [3] + } + + { +//! [4] + QSqlQuery query; +//! [4] //! [5] + QSqlRecord record = query.record(); +//! [5] //! [6] + QSqlField field = record.field("country"); +//! [6] + } +} + +void doSomething(const QString &) +{ +} + +void QSqlQuery_snippets() +{ + { + // typical loop +//! [7] + QSqlQuery query("SELECT country FROM artist"); + while (query.next()) { + QString country = query.value(0).toString(); + doSomething(country); + } +//! [7] + } + + { + // field index lookup +//! [8] + QSqlQuery query("SELECT * FROM artist"); + int fieldNo = query.record().indexOf("country"); + while (query.next()) { + QString country = query.value(fieldNo).toString(); + doSomething(country); + } +//! [8] + } + + { + // named with named +//! [9] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (:id, :forename, :surname)"); + query.bindValue(":id", 1001); + query.bindValue(":forename", "Bart"); + query.bindValue(":surname", "Simpson"); + query.exec(); +//! [9] + } + + { + // positional with named +//! [10] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (:id, :forename, :surname)"); + query.bindValue(0, 1001); + query.bindValue(1, "Bart"); + query.bindValue(2, "Simpson"); + query.exec(); +//! [10] + } + + { + // positional 1 +//! [11] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (?, ?, ?)"); + query.bindValue(0, 1001); + query.bindValue(1, "Bart"); + query.bindValue(2, "Simpson"); + query.exec(); +//! [11] + } + + { + // positional 2 +//! [12] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (?, ?, ?)"); + query.addBindValue(1001); + query.addBindValue("Bart"); + query.addBindValue("Simpson"); + query.exec(); +//! [12] + } + + { + // stored +//! [13] + QSqlQuery query; + query.prepare("CALL AsciiToInt(?, ?)"); + query.bindValue(0, "A"); + query.bindValue(1, 0, QSql::Out); + query.exec(); + int i = query.boundValue(1).toInt(); // i is 65 +//! [13] + Q_UNUSED(i); + } + + QSqlQuery query; + + { + // examine with named binding +//! [14] + QMapIterator i(query.boundValues()); + while (i.hasNext()) { + i.next(); + cout << i.key().toAscii().data() << ": " + << i.value().toString().toAscii().data() << endl; + } +//! [14] + } + + { + // examine with positional binding +//! [15] + QList list = query.boundValues().values(); + for (int i = 0; i < list.size(); ++i) + cout << i << ": " << list.at(i).toString().toAscii().data() << endl; +//! [15] + } +} + +void QSqlQueryModel_snippets() +{ + { +//! [16] + QSqlQueryModel *model = new QSqlQueryModel; + model->setQuery("SELECT name, salary FROM employee"); + model->setHeaderData(0, Qt::Horizontal, tr("Name")); + model->setHeaderData(1, Qt::Horizontal, tr("Salary")); + +//! [17] + QTableView *view = new QTableView; +//! [17] //! [18] + view->setModel(model); +//! [18] //! [19] + view->show(); +//! [16] //! [19] //! [20] + view->setEditTriggers(QAbstractItemView::NoEditTriggers); +//! [20] + } + +//! [21] + QSqlQueryModel model; + model.setQuery("SELECT * FROM employee"); + int salary = model.record(4).value("salary").toInt(); +//! [21] + Q_UNUSED(salary); + + { +//! [22] + int salary = model.data(model.index(4, 2)).toInt(); +//! [22] + Q_UNUSED(salary); + } + + for (int row = 0; row < model.rowCount(); ++row) { + for (int col = 0; col < model.columnCount(); ++col) { + qDebug() << model.data(model.index(row, col)); + } + } +} + +class MyModel : public QSqlQueryModel +{ +public: + QVariant data(const QModelIndex &item, int role) const; + + int m_specialColumnNo; +}; + +//! [23] +QVariant MyModel::data(const QModelIndex &item, int role) const +{ + if (item.column() == m_specialColumnNo) { + // handle column separately + } + return QSqlQueryModel::data(item, role); +} +//! [23] + +void QSqlTableModel_snippets() +{ +//! [24] + QSqlTableModel *model = new QSqlTableModel(parentObject, database); + model->setTable("employee"); + model->setEditStrategy(QSqlTableModel::OnManualSubmit); + model->select(); + model->setHeaderData(0, Qt::Horizontal, tr("Name")); + model->setHeaderData(1, Qt::Horizontal, tr("Salary")); + + QTableView *view = new QTableView; + view->setModel(model); + view->hideColumn(0); // don't show the ID + view->show(); +//! [24] + + { +//! [25] + QSqlTableModel model; + model.setTable("employee"); + QString name = model.record(4).value("name").toString(); +//! [25] + } +} + +void sql_intro_snippets() +{ + { +//! [26] + QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL"); + db.setHostName("bigblue"); + db.setDatabaseName("flightdb"); + db.setUserName("acarlson"); + db.setPassword("1uTbSbAs"); + bool ok = db.open(); +//! [26] + Q_UNUSED(ok); + } + + { +//! [27] + QSqlDatabase firstDB = QSqlDatabase::addDatabase("QMYSQL", "first"); + QSqlDatabase secondDB = QSqlDatabase::addDatabase("QMYSQL", "second"); +//! [27] + } + + { +//! [28] + QSqlDatabase defaultDB = QSqlDatabase::database(); +//! [28] //! [29] + QSqlDatabase firstDB = QSqlDatabase::database("first"); +//! [29] //! [30] + QSqlDatabase secondDB = QSqlDatabase::database("second"); +//! [30] + } + + { + // SELECT1 +//! [31] + QSqlQuery query; + query.exec("SELECT name, salary FROM employee WHERE salary > 50000"); +//! [31] + +//! [32] + while (query.next()) { + QString name = query.value(0).toString(); + int salary = query.value(1).toInt(); + qDebug() << name << salary; + } +//! [32] + } + + { + // FEATURE +//! [33] + QSqlQuery query; + int numRows; + query.exec("SELECT name, salary FROM employee WHERE salary > 50000"); + + QSqlDatabase defaultDB = QSqlDatabase::database(); + if (defaultDB.driver()->hasFeature(QSqlDriver::QuerySize)) { + numRows = query.size(); + } else { + // this can be very slow + query.last(); + numRows = query.at() + 1; + } +//! [33] + } + + { + // INSERT1 +//! [34] + QSqlQuery query; + query.exec("INSERT INTO employee (id, name, salary) " + "VALUES (1001, 'Thad Beaumont', 65000)"); +//! [34] + } + + { + // NAMED BINDING +//! [35] + QSqlQuery query; + query.prepare("INSERT INTO employee (id, name, salary) " + "VALUES (:id, :name, :salary)"); + query.bindValue(":id", 1001); + query.bindValue(":name", "Thad Beaumont"); + query.bindValue(":salary", 65000); + query.exec(); +//! [35] + } + + { + // POSITIONAL BINDING +//! [36] + QSqlQuery query; + query.prepare("INSERT INTO employee (id, name, salary) " + "VALUES (?, ?, ?)"); + query.addBindValue(1001); + query.addBindValue("Thad Beaumont"); + query.addBindValue(65000); + query.exec(); +//! [36] + } + + { + // UPDATE1 +//! [37] + QSqlQuery query; + query.exec("UPDATE employee SET salary = 70000 WHERE id = 1003"); +//! [37] + } + + { + // DELETE1 +//! [38] + QSqlQuery query; + query.exec("DELETE FROM employee WHERE id = 1007"); +//! [38] + } + + { + // TRANSACTION +//! [39] + QSqlDatabase::database().transaction(); + QSqlQuery query; + query.exec("SELECT id FROM employee WHERE name = 'Torild Halvorsen'"); + if (query.next()) { + int employeeId = query.value(0).toInt(); + query.exec("INSERT INTO project (id, name, ownerid) " + "VALUES (201, 'Manhattan Project', " + + QString::number(employeeId) + ')'); + } + QSqlDatabase::database().commit(); +//! [39] + } + + { + // SQLQUERYMODEL1 +//! [40] + QSqlQueryModel model; + model.setQuery("SELECT * FROM employee"); + + for (int i = 0; i < model.rowCount(); ++i) { + int id = model.record(i).value("id").toInt(); + QString name = model.record(i).value("name").toString(); + qDebug() << id << name; + } +//! [40] + } + + { + // SQLTABLEMODEL1 +//! [41] + QSqlTableModel model; + model.setTable("employee"); + model.setFilter("salary > 50000"); + model.setSort(2, Qt::DescendingOrder); + model.select(); + + for (int i = 0; i < model.rowCount(); ++i) { + QString name = model.record(i).value("name").toString(); + int salary = model.record(i).value("salary").toInt(); + qDebug() << name << salary; + } +//! [41] + } + + { + // SQLTABLEMODEL2 + QSqlTableModel model; + model.setTable("employee"); + +//! [42] + for (int i = 0; i < model.rowCount(); ++i) { + QSqlRecord record = model.record(i); + double salary = record.value("salary").toInt(); + salary *= 1.1; + record.setValue("salary", salary); + model.setRecord(i, record); + } + model.submitAll(); +//! [42] + + // SQLTABLEMODEL3 + int row = 1; + int column = 2; +//! [43] + model.setData(model.index(row, column), 75000); + model.submitAll(); +//! [43] + + // SQLTABLEMODEL4 +//! [44] + model.insertRows(row, 1); + model.setData(model.index(row, 0), 1013); + model.setData(model.index(row, 1), "Peter Gordon"); + model.setData(model.index(row, 2), 68500); + model.submitAll(); +//! [44] + +//! [45] + model.removeRows(row, 5); +//! [45] //! [46] + model.submitAll(); +//! [46] + } +} + +//! [47] +class XyzResult : public QSqlResult +{ +public: + XyzResult(const QSqlDriver *driver) + : QSqlResult(driver) {} + ~XyzResult() {} + +protected: + QVariant data(int /* index */) { return QVariant(); } + bool isNull(int /* index */) { return false; } + bool reset(const QString & /* query */) { return false; } + bool fetch(int /* index */) { return false; } + bool fetchFirst() { return false; } + bool fetchLast() { return false; } + int size() { return 0; } + int numRowsAffected() { return 0; } + QSqlRecord record() const { return QSqlRecord(); } +}; +//! [47] + +//! [48] +class XyzDriver : public QSqlDriver +{ +public: + XyzDriver() {} + ~XyzDriver() {} + + bool hasFeature(DriverFeature /* feature */) const { return false; } + bool open(const QString & /* db */, const QString & /* user */, + const QString & /* password */, const QString & /* host */, + int /* port */, const QString & /* options */) + { return false; } + void close() {} + QSqlResult *createResult() const { return new XyzResult(this); } +}; +//! [48] + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QSqlDatabase_snippets(); + QSqlField_snippets(); + QSqlQuery_snippets(); + QSqlQueryModel_snippets(); + QSqlTableModel_snippets(); + + XyzDriver driver; + XyzResult result(&driver); +} diff --git a/src/sql/doc/src/qsqldatatype-table.qdoc b/src/sql/doc/src/qsqldatatype-table.qdoc new file mode 100644 index 0000000000..a7e03cf28f --- /dev/null +++ b/src/sql/doc/src/qsqldatatype-table.qdoc @@ -0,0 +1,570 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page sql-types.html + \title Data Types for Qt-supported Database Systems + \brief Recommended data types for database systems + + \ingroup qt-sql + + \section1 Recommended Data Types for Qt-Supported Database Systems + + This table shows the recommended data types for extracting data from + the databases supported in Qt. Note that types used in Qt are not + necessarily valid as input types to a specific database + system. e.g., A double might work perfectly as input for floating + point records in a particular database, but not necessarily as a + storage format for output from that database, because it would be + stored with 64-bit precision in C++. + + \tableofcontents + + \section2 IBM DB2 Data Types + + \table 90% + \header + \li IBM DB2 data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li INTEGER + \li 32-bit signed integer + \li typedef qint32 + \row + \li BIGINT + \li 64-bit signed integer + \li typedef qint64 + \row + \li REAL + \li 32-bit Single-precision floating point + \li By default mapping to QString + \row + \li DOUBLE PRECISION + \li 64-bit Double-precision floating point + \li By default mapping to QString + \row + \li FLOAT + \li 64-bit Double-precision floating point + \li By default mapping to QString + \row + \li CHAR + \li Fixed-length, null-terminated character string + \li Mapped to QString + \row + \li VARCHAR + \li Null-terminated varying length string + \li Mapped to QString + \row + \li LONG VARCHAR + \li Not null-terminated varying length character string + \li Mapped to QString + \row + \li BLOB + \li Not null-terminated varying binary string with 4-byte string + length indicator + \li Mapped to QByteArray + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li DATE + \li Null-terminated character string of the following format: + yyyy-mm-dd + \li Mapped to QDate + \row + \li TIME + \li Null-terminated character string of the following format: hh.mm.ss + \li Mapped to QTime + \row + \li TIMESTAMP + \li Null-terminated character string of the following format: yyyy-mm-dd-hh.mm.ss.nnnnnn + \li Mapped to QDateTime + \endtable + + \section2 Borland InterBase Data Types + + \table 90% + \header + \li Borland InterBase data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li BOOLEAN + \li Boolean + \li bool + \row + \li TINYINT + \li 8 bit signed integer + \li typedef qint8 + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li INTEGER + \li 32-bit signed integer + \li typedef qint32 + \row + \li BIGINT LONG + \li 64-bit signed integer + \li typedef qint64 + \row + \li REAL FLOAT + \li 32-bit floating point + \li By default mapping to QString + \row + \li FLOAT + \li 64-bit floating point + \li By default mapping to QString + \row + \li DOUBLE + \li 64-bit floating point + \li By default mapping to QString + \row + \li DOUBLE PRECISION + \li 64-bit Double-precision floating point + \li By default mapping to QString + \row + \li VARCHAR STRING + \li Character string, Unicode + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li DATE + \li Displays date. Format: 'yyyy-mm-dd' + \li Mapped to QDate + \row + \li TIME + \li Displays time. Format is 'hh:mm:ss' in 24-hour format + \li Mapped to QTime + \row + \li TIMESTAMP + \li Displays a timestamp. Format is 'yyyy-mm-dd hh:mm:ss' + \li Mapped to QDateTime + \endtable + + \section2 MySQL Data Types + + \table 90% + \header + \li MySQL data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li TINYINT + \li 8 bit signed integer + \li typedef qint8 + \row + \li TINYINT UNSIGNED + \li 8 bit unsigned integer + \li typedef quint8 + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li SMALLINT UNSIGNED + \li 16-bit unsigned integer + \li typedef quint16 + \row + \li INT + \li 32-bit signed integer + \li typedef qint32 + \row + \li INT UNSIGNED + \li 32-bit unsigned integer + \li typedef quint32 + \row + \li BIGINT + \li 64-bit signed integer + \li typedef qint64 + \row + \li FLOAT + \li 32-bit Floating Point + \li By default mapping to QString + \row + \li DOUBLE + \li 64-bit Floating Point + \li By default mapping to QString + \row + \li CHAR + \li Character string + \li Mapped to QString + \row + \li VARCHAR + \li Character string + \li Mapped to QString + \row + \li TINYTEXT + \li Character string + \li Mapped to QString + \row + \li TEXT + \li Character string + \li Mapped to QString + \row + \li MEDIUMTEXT + \li Character string + \li Mapped to QString + \row + \li LONGTEXT + \li Character string + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li all BLOB types + \li BLOB + \li Mapped to QByteArray + \row + \li DATE + \li Date without Time + \li Mapped to QDate + \row + \li DATETIME + \li Date and Time + \li Mapped to QDateTime + \row + \li TIMESTAMP + \li Date and Time + \li Mapped to QDateTime + \row + \li TIME + \li Time + \li Mapped to QTime + \row + \li YEAR + \li Year (int) + \li Mapped to QDateTime + \row + \li ENUM + \li Enumeration of Value Set + \li Mapped to QString + \endtable + + \section2 Oracle Call Interface Data Types + + \table 90% + \header + \li Oracle Call Interface data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li NUMBER + \li FLOAT, DOUBLE, PRECISIONc REAL + \li By default mapping to QString + \row + \li NUMBER(38) + \li INTEGER INT SMALLINT + \li typedef qint8/16/32/64 + \row + \li NUMBER(p,s) + \li NUMERIC(p,s) DECIMAL(p,s)a + \li By default mapping to QString + \row + \li NVARCHAR2(n) + \li Character string (NATIONAL CHARACTER VARYING(n) NATIONAL + CHAR VARYING(n) NCHAR VARYING(n)) + \li Mapped to QString + \row + \li NCHAR(n) + \li Character string (NATIONAL CHARACTER(n) NATIONAL CHAR(n) + NCHAR(n)) + \li Mapped to QString + \row + \li CHAR(n) + \li Character string (CHARACTER(n) CHAR(n)) + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li BLOB + \li A binary large object + \li Mapped to QByteArray + \row + \li TIMESTAMP + \li Year, month, and day values of date, as well as hour, minute, + and second values of time + \li Mapped to QDateTime + \endtable + + \section2 ODBC Data Types + + \table 90% + \header + \li ODBC data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li BIT + \li Boolean + \li BOOL + \row + \li TINYINT + \li 8 bit integer + \li typedef qint8 + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li INTEGER + \li 32-bit signed integer + \li typedef qint32 + \row + \li BIGINT + \li 64-bit signed integer + \li typedef qint64 + \row + \li REAL + \li 32-bit Single-precision floating point + \li By default mapping to QString + \row + \li FLOAT + \li 64-bit Double floating point + \li By default mapping to QString + \row + \li DOUBLE + \li 64-bit Double floating point + \li By default mapping to QString + \row + \li CHAR + \li Character string + \li Mapped to QString + \row + \li VARCHAR + \li Character string + \li Mapped to QString + \row + \li LONGVARCHAR + \li Character string + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li DATE + \li Character string + \li Mapped to QDate + \row + \li TIME + \li Character Time, Character string + \li Mapped to QTime + \row + \li TIMESTAMP + \li Character Time, Character string + \li Mapped to QDateTime + \endtable + + \section2 PostgreSQL Data Types + + \table 90% + \header + \li PostgreSQL data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li BOOLEAN + \li Boolean + \li bool + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li INTEGER + \li 32-bit signed integer + \li typedef qint32 + \row + \li BIGINT + \li 64-bit signed integer + \li typedef qint64 + \row + \li REAL + \li 32-bit variable-precision floating point + \li By default mapping to QString + \row + \li DOUBLE PRECISION + \li 64-bit variable-precision floating point + \li By default mapping to QString + \row + \li DECIMAL VARIABLE + \li user-specified precision, exact + \li Mapped to QString + \row + \li NUMERIC VARIABLE + \li user-specified precision, exact + \li Mapped to QString + \row + \li VARCHAR + \li variable-length character string + \li Mapped to QString + \row + \li CHARACTER + \li Character string of fixed-length + \li Mapped to QString + \row + \li TEXT + \li Character string of variable-length + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li TIMESTAMP + \li 8 bytes, both date and time + \li Mapped to QDateTime + \row + \li TIMESTAMP + \li 8 bytes, both date and time, with time zone + \li Mapped to QDateTime + \row + \li DATE + \li 4 bytes, dates only + \li Mapped to QDate + \row + \li TIME + \li 8 bytes, times of day only 00:00:00.00 - 23:59:59.99 + \li Mapped to QTime + \row + \li TIME + \li 12 bytes times of day only, with time zone 00:00:00.00+12 + \li Mapped to QDateTime + \endtable + + \section2 QSQLITE SQLite version 3 Data Types + + \table 90% + \header + \li QSQLITE SQLite version 3 data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li NULL + \li NULL value. + \li NULL + \row + \li INTEGER + \li Signed integer, stored in 8, 16, 24, 32, 48, or 64-bits + depending on the magnitude of the value. + \li typedef qint8/16/32/64 + \row + \li REAL + \li 64-bit floating point value. + \li By default mapping to QString + \row + \li TEXT + \li Character string (UTF-8, UTF-16BE or UTF-16-LE). + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li BLOB + \li The value is a BLOB of data, stored exactly as it was input. + \li Mapped to QByteArray + \endtable + + \section2 Sybase Adaptive Server Data Types + + \table 90% + \header + \li Sybase Adaptive Server data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li BINARY + \li Describes a fixed-length binary value up to 255 bytes in size. + \li Mapped to QByteArray + \row + \li CHAR + \li Character String + \li Mapped to QString + \row + \li DATETIME + \li Date and time. Range: 1753-01-01 00:00:00 through 9999-12-31 23:59:59. + \li Mapped to QDateTime + \row + \li NCHAR + \li Character String of fixed length + \li Mapped to QString + \row + \li NVARACHAR + \li Character String of variable length + \li Mapped to QString + \row + \li VARCHAR + \li Character String of fixed length + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li TIMESTAMP + \li A unique number within a database + \li Mapped to QString + \row + \li SMALLDATETIME + \li Date and time. Range: 1900-01-01 00:00 through 2079-12-31 23:59 + \li Mapped to QDateTime + \row + \li UNICHAR + \li Character String of fixed length.(Unicode) + \li Mapped to QString + \row + \li UNIVARCHAR + \li Character String of variable length.(Unicode) + \li Mapped to QString + \row + \li VARBINARY + \li Describes a variable-length binary value up to 255 bytes in size + \li Mapped to QByteArray + \endtable + + \section2 SQLite Version 2 + + SQLite version 2 is "typeless". This means that you can store any kind of + data you want in any column of any table, regardless of the declared + data type of that column. We recommend that you map the data to QString. +*/ diff --git a/src/sql/doc/src/qtsql.qdoc b/src/sql/doc/src/qtsql.qdoc new file mode 100644 index 0000000000..594a812bb9 --- /dev/null +++ b/src/sql/doc/src/qtsql.qdoc @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtSql + \title Qt SQL Module + \ingroup modules + + To include the definitions of the module's classes, use the + following directive: + + \snippet code/doc_src_qtsql.cpp 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet code/doc_src_qtsql.pro 1 + + See the \l{SQL Programming} guide for information about using this + module in your applications. +*/ diff --git a/src/sql/doc/src/sql-driver.qdoc b/src/sql/doc/src/sql-driver.qdoc new file mode 100644 index 0000000000..7311416563 --- /dev/null +++ b/src/sql/doc/src/sql-driver.qdoc @@ -0,0 +1,830 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page sql-driver.html + \title SQL Database Drivers + \brief How to configure and install Qt SQL drivers for supported databases. + + \ingroup qt-sql + + The Qt SQL module uses driver \l{How to Create Qt + Plugins}{plugins} to communicate with the different database + APIs. Since Qt's SQL Module API is database-independent, all + database-specific code is contained within these drivers. Several + drivers are supplied with Qt and other drivers can be added. The + driver source code is supplied and can be used as a model for + \l{#development}{writing your own drivers}. + + \tableofcontents + + \section1 Supported Databases + + The table below lists the drivers included with Qt. Due to + license incompatibilities with the GPL, not all of the plugins + are provided with Open Source Versions of Qt. + + \table + \header \li Driver name \li DBMS + \row \li \link #QDB2 QDB2\endlink \li IBM DB2 (version 7.1 and above) + \row \li \link #QIBASE QIBASE\endlink \li Borland InterBase + \row \li \link #QMYSQL QMYSQL\endlink \li MySQL + \row \li \link #QOCI QOCI\endlink \li Oracle Call Interface Driver + \row \li \link #QODBC QODBC\endlink + \li Open Database Connectivity (ODBC) - Microsoft SQL Server and other + ODBC-compliant databases + \row \li \link #QPSQL QPSQL\endlink \li PostgreSQL (versions 7.3 and above) + \row \li \link #QSQLITE2 QSQLITE2\endlink \li SQLite version 2 + \row \li \link #QSQLITE QSQLITE\endlink \li SQLite version 3 + \row \li \link #QTDS QTDS\endlink \li Sybase Adaptive Server \note obsolete from Qt 4.7 + \endtable + + SQLite is the in-process database system with the best test coverage + and support on all platforms. Oracle via OCI, and PostreSQL and MySQL + through either ODBC or a native driver are well-tested on Windows and + Linux. The completeness of the support for other systems depends on the + availability and quality of client libraries. + + \b{Note:} To build a driver plugin you need to have the appropriate + client library for your Database Management System (DBMS). This provides + access to the API exposed by the DBMS, and is typically shipped with it. + Most installation programs also allow you to install "development + libraries", and these are what you need. These libraries are responsible + for the low-level communication with the DBMS. + + \target building + \section1 Building the Drivers Using Configure + + On Unix and Mac OS X, the Qt \c configure script tries to + automatically detect the available client libraries on your + machine. Run \c{configure -help} to see what drivers can be + built. You should get an output similar to this: + + \snippet code/doc_src_sql-driver.qdoc 0 + + The \c configure script cannot detect the necessary libraries + and include files if they are not in the standard paths, so it + may be necessary to specify these paths using the \c -I and \c -L + command-line options. For example, if your MySQL include files + are installed in \c /usr/local/mysql (or in \c{C:\mysql\include} + on Windows), then pass the following parameter to configure: \c + -I/usr/local/mysql (or \c{-I C:\mysql\include} for Windows). + + On Windows the \c -I parameter doesn't accept spaces in + filenames, so use the 8.3 name instead; for example, use + \c{C:\progra~1\mysql} instead of \c{C:\Program Files\mysql}. + + Use the \c{-qt-sql-} parameter to build the database driver + statically into your Qt library or \c{-plugin-sql-} to build + the driver as a plugin. Look at the sections that follow for + additional information about required libraries. + + \target buildingmanually + \section1 Building the Plugins Manually + + \target QMYSQL + \section2 QMYSQL for MySQL 4 and higher + + \section3 QMYSQL Stored Procedure Support + + MySQL 5 introduces stored procedure support at the SQL level, but no + API to control IN, OUT and INOUT parameters. Therefore, parameters + have to be set and read using SQL commands instead of QSqlQuery::bindValue(). + + Example stored procedure: + + \snippet code/doc_src_sql-driver.qdoc 1 + + Source code to access the OUT values: + + \snippet code/doc_src_sql-driver.cpp 2 + + \b{Note:} \c{@outval1} and \c{@outval2} are variables local to the current + connection and will not be affected by queries sent from another host + or connection. + + \section3 Embedded MySQL Server + + The MySQL embedded server is a drop-in replacement for the normal + client library. With the embedded MySQL server, a MySQL server is + not required to use MySQL functionality. + + To use the embedded MySQL server, simply link the Qt plugin to \c + libmysqld instead of libmysqlclient. This can be done by replacing + \c -lmysqlclient_r by \c -lmysqld in the \c qmake command in the + section below. + + Please refer to the MySQL documentation, chapter "libmysqld, the Embedded + MySQL Server Library" for more information about the MySQL embedded server. + + \section3 How to Build the QMYSQL Plugin on Unix and Mac OS X + + You need the MySQL header files and as well as the shared library + \c{libmysqlclient.so}. Depending on your Linux distribution you may + need to install a package which is usually called "mysql-devel". + + Tell \l qmake where to find the MySQL header files and shared + libraries (here it is assumed that MySQL is installed in + \c{/usr/local}) and run \c{make}: + + \snippet code/doc_src_sql-driver.qdoc 3 + + After installing Qt, as described in the \l{Installing Qt for X11 + Platforms} document, you also need to install the plugin in the + standard location: + + \snippet code/doc_src_sql-driver.qdoc 4 + + \section3 How to Build the QMYSQL Plugin on Windows + + You need to get the MySQL installation files. Run \c SETUP.EXE and + choose "Custom Install". Install the "Libs & Include Files" Module. + Build the plugin as follows (here it is assumed that MySQL is + installed in \c{C:\MySQL}): + + \snippet code/doc_src_sql-driver.qdoc 5 + + If you are not using a Microsoft compiler, replace \c nmake with \c + make in the line above. + + \note This database plugin is not supported for Windows CE. + + \note Including \c{"-o Makefile"} as an argument to \l qmake to + tell it where to build the makefile can cause the plugin to be + built in release mode only. If you are expecting a debug version + to be built as well, don't use the \c{"-o Makefile"} option. + + \section3 How to build the MySQL driver for MinGW users + + The following steps have been used successfully for WinXP SP3. In + this example, Qt 4.6.2 is shown. + + \list + + \li Download the following components: + \list + \li \c{MinGW-5.1.6.exe} + \li \c{mingw-utils-0.3.tar.gz} + \li Qt sources, e.g. \c{qt-everywhere-opensource-src-4.6.2.zip} + \li \c{mysql-5.1.35-win32.msi} + \endlist + + \li Install \c{MinGW-5.1.6.exe} in, e.g. \c{C:\MinGW}. + + \li Extract \c{mingw-utils-0.3.tar.gz} into, e.g. \c{C:\MinGW}. + + \li Add the path for \c{MinGW-5.1.6.exe} to your \c{PATH} variable, + e.g. \c{C:\MinGW\bin;} + + \li Extract the Qt sources, (\c{qt-everywhere-opensource-src-4.6.2.zip}), + into, e.g. \c{C:\Qt}. + + \li Add the path for the eventual Qt binary to your \c{PATH} variable, + e.g. \c{C:\Qt\4.6.2\bin;}. + + \li Install MySQL (\c{mysql-5.1.35-win32.msi}), customizing the + components. Select only the headers and libraries. Install in, + e.g. \c{C:\MySQL\MySQL51}. + + \li Open the DOS prompt, go to \c{C:\MySQL\MySQL51\lib\opt}, and run + the following commands: + \list + \li \c{reimp -d libmysql.lib} + \li \c{dlltool -k -d libmysql.def -l libmysql.a} + \endlist + + \li Open the DOS prompt, go to \c{C:\Qt\4.6.2} and run the following commands: + \list + \li \c{configure.exe -debug-and-release -platform win32-g++ -qt-sql-mysql + -l mysql -I C:\MySQL\MySQL51\include -L C:\MySQL\MySQL51\lib\opt} + \li \c{mingw32-make sub-src} + \endlist + This step takes a long time. + + \li Open the DOS prompt, go to + \c{C:\Qt\4.6.2\src\plugins\sqldrivers\mysql} and run the + following command: + \list + \li \c{qmake "INCLUDEPATH+=C:\MySQL\MySQL51\include" "LIBS+=-L. mysql" mysql.pro} + \endlist + + \li Now the following libraries are ready in \c{C:\Qt\4.6.2\plugins\sqldrivers}. + \list + \li \c{libqsqlmysql4.a} + \li \c{libqsqlmysqld4.a} + \li \c{qsqlmysql4.dll} + \li \c{qsqlmysqld4.dll} + \endlist + To use the SDK and QtCreator directly, copy these libraries to + your \c{C:\Qt\...\qt\plugins\sqldrivers\}, and copy + \c{C:\MySQL\MySQL51\lib\opt\libmysql.dll} to your \c{C:\Qt\...\qt\bin\}. + + \endlist + + \target QOCI + \section2 QOCI for the Oracle Call Interface (OCI) + + \section3 General Information about the OCI plugin + + The Qt OCI plugin supports Oracle 9i, 10g and higher. After + connecting to the Oracle server, the plugin will auto-detect the + database version and enable features accordingly. + + It's possible to connect to a Oracle database without a tnsnames.ora file. + This requires that the database SID is passed to the driver as the database + name and that a hostname is given. + + \section3 OCI User Authentication + + The Qt OCI plugin supports authentication using + external credentials (OCI_CRED_EXT). Usually, this means that the database + server will use the user authentication provided by the operating system + instead of its own authentication mechanism. + + Leave the username and password empty when opening a connection with + QSqlDatabase to use the external credentials authentication. + + \section3 OCI BLOB/LOB Support + + Binary Large Objects (BLOBs) can be read and written, but be aware + that this process may require a lot of memory. You should use a forward + only query to select LOB fields (see QSqlQuery::setForwardOnly()). + + Inserting BLOBs should be done using either a prepared query where the + BLOBs are bound to placeholders or QSqlTableModel, which uses a prepared + query to do this internally. + + \section3 How to Build the OCI Plugin on Unix and Mac OS X + + For Oracle 10g, all you need is the "Instant Client Package - Basic" and + "Instant Client Package - SDK". For Oracle prior to 10g, you require + the standard Oracle client and the SDK packages. + + Oracle library files required to build the driver: + + \list + \li \c libclntsh.so (all versions) + \li \c libwtc9.so (only Oracle 9) + \endlist + + Tell \c qmake where to find the Oracle header files and shared + libraries and run make: + + For Oracle version 9: + \snippet code/doc_src_sql-driver.qdoc 6 + + For Oracle version 10, we assume that you installed the RPM packages of the + Instant Client Package SDK (you need to adjust the version number accordingly): + \snippet code/doc_src_sql-driver.qdoc 7 + + \b{Note:} If you are using the Oracle Instant Client package, + you will need to set LD_LIBRARY_PATH when building the OCI SQL plugin + and when running an application that uses the OCI SQL plugin. You can + avoid this requirement by setting and RPATH and listing all of the + libraries to link to. Here is an example: + \snippet code/doc_src_sql-driver.qdoc 32 + + If you wish to build the OCI plugin manually with this method the procedure looks like this: + \snippet code/doc_src_sql-driver.qdoc 33 + + \section3 How to Build the OCI Plugin on Windows + + Choosing the option "Programmer" in the Oracle Client Installer from + the Oracle Client Installation CD is generally sufficient to build the + plugin. For some versions of Oracle Client, you may also need to select + the "Call Interface (OCI)" option if it is available. + + Build the plugin as follows (here it is assumed that Oracle Client is + installed in \c{C:\oracle}): + + \snippet code/doc_src_sql-driver.qdoc 8 + + If you are not using a Microsoft compiler, replace \c nmake with \c + make in the line above. + + When you run your application you will also need to add the \c oci.dll + path to your \c PATH environment variable: + + \snippet code/doc_src_sql-driver.qdoc 9 + + \b{Note:} This database plugin is not supported for Windows CE. + + \target QODBC + \section2 QODBC for Open Database Connectivity (ODBC) + + \section3 General Information about the ODBC plugin + + ODBC is a general interface that allows you to connect to multiple + DBMSs using a common interface. The QODBC driver allows you to connect + to an ODBC driver manager and access the available data sources. Note + that you also need to install and configure ODBC drivers for the ODBC + driver manager that is installed on your system. The QODBC plugin + then allows you to use these data sources in your Qt applications. + + \b{Note:} You should use native drivers in preference to the ODBC + driver where they are available. ODBC support can be used as a fallback + for compliant databases if no native drivers are available. + + On Windows an ODBC driver manager should be installed by default. + For Unix systems there are some implementations which must be + installed first. Note that every client that uses your application is + required to have an ODBC driver manager installed, otherwise the + QODBC plugin will not work. + + Be aware that when connecting to an ODBC datasource you must pass in + the name of the ODBC datasource to the QSqlDatabase::setDatabaseName() + function rather than the actual database name. + + The QODBC Plugin needs an ODBC compliant driver manager version 2.0 or + later to work. Some ODBC drivers claim to be version 2.0 compliant, + but do not offer all the necessary functionality. The QODBC plugin + therefore checks whether the data source can be used after a + connection has been established and refuses to work if the check + fails. If you don't like this behavior, you can remove the \c{#define + ODBC_CHECK_DRIVER} line from the file \c{qsql_odbc.cpp}. Do this at + your own risk! + + By default, Qt instructs the ODBC driver to behave as an ODBC 2.x + driver. However, for some \e{driver-manager/ODBC 3.x-driver} + combinations (e.g., \e{unixODBC/MaxDB ODBC}), telling the ODBC + driver to behave as a 2.x driver can cause the driver plugin to + have unexpected behavior. To avoid this problem, instruct the ODBC + driver to behave as a 3.x driver by + \l{QSqlDatabase::setConnectOptions()} {setting the connect option} + \c{"SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3"} before you + \l{QSqlDatabase::open()} {open your database connection}. Note + that this will affect multiple aspects of ODBC driver behavior, + e.g., the SQLSTATEs. Before setting this connect option, consult + your ODBC documentation about behavior differences you can expect. + + If you experience very slow access of the ODBC datasource, make sure + that ODBC call tracing is turned off in the ODBC datasource manager. + + Some drivers don't support scrollable cursors. In that case case only + queries in forwardOnly mode can be used successfully. + + \section3 ODBC Stored Procedure Support + + With Microsoft SQL Server the result set returned by a stored + procedure that uses the return statement, or returns multiple result + sets, will be accessible only if you set the query's forward only + mode to \e forward using \l QSqlQuery::setForwardOnly(). + + \snippet code/doc_src_sql-driver.cpp 10 + + \b{Note:} The value returned by the stored procedure's return statement + is discarded. + + \section3 ODBC Unicode Support + + The QODBC Plugin will use the Unicode API if UNICODE is defined. On + Windows NT based systems, this is the default. Note that the ODBC + driver and the DBMS must also support Unicode. + + Some driver managers and drivers don't support UNICODE. To use the + QODBC plugin with such drivers it has to be compiled with the + Q_ODBC_VERSION_2 defined. + + For the Oracle 9 ODBC driver (Windows), it is necessary to check + "SQL_WCHAR support" in the ODBC driver manager otherwise Oracle + will convert all Unicode strings to local 8-bit. + + \section3 How to Build the ODBC Plugin on Unix and Mac OS X + + It is recommended that you use unixODBC. You can find the latest + version and ODBC drivers at \l http://www.unixodbc.org. + You need the unixODBC header files and shared libraries. + + Tell \c qmake where to find the unixODBC header files and shared + libraries (here it is assumed that unixODBC is installed in + \c{/usr/local/unixODBC}) and run \c{make}: + + \snippet code/doc_src_sql-driver.qdoc 11 + + \section3 How to Build the ODBC Plugin on Windows + + The ODBC header and include files should already be installed in the + right directories. You just have to build the plugin as follows: + + \snippet code/doc_src_sql-driver.qdoc 12 + + If you are not using a Microsoft compiler, replace \c nmake with \c + make in the line above. + + \b{Note:} This database plugin is not officially supported for Windows CE. + + \target QPSQL + \section2 QPSQL for PostgreSQL (Version 7.3 and Above) + + \section3 General Information about the QPSQL driver + + The QPSQL driver supports version 7.3 and higher of the PostgreSQL server. + We recommend that you use a client library from version 7.3.15, 7.4.13, + 8.0.8, 8.1.4 or more recent as these versions contain security fixes, and + as the QPSQL driver might not build with older versions of the client + library depending on your platform. + + For more information about PostgreSQL visit \l http://www.postgresql.org. + + \section3 QPSQL Unicode Support + + The QPSQL driver automatically detects whether the PostgreSQL + database you are connecting to supports Unicode or not. Unicode is + automatically used if the server supports it. Note that the driver + only supports the UTF-8 encoding. If your database uses any other + encoding, the server must be compiled with Unicode conversion + support. + + Unicode support was introduced in PostgreSQL version 7.1 and it will + only work if both the server and the client library have been compiled + with multibyte support. More information about how to set up a + multibyte enabled PostgreSQL server can be found in the PostgreSQL + Administrator Guide, Chapter 5. + + \section3 QPSQL BLOB Support + + Binary Large Objects are supported through the \c BYTEA field type in + PostgreSQL server versions >= 7.1. + + \section3 How to Build the QPSQL Plugin on Unix and Mac OS X + + You need the PostgreSQL client library and headers installed. + + To make \c qmake find the PostgreSQL header files and shared + libraries, run \c qmake the following way (assuming that the + PostgreSQL client is installed in \c{/usr}): + + \snippet code/doc_src_sql-driver.qdoc 13 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet code/doc_src_sql-driver.qdoc 14 + + \section3 How to Build the QPSQL Plugin on Windows + + Install the appropriate PostgreSQL developer libraries for your + compiler. Assuming that PostgreSQL was installed in \c{C:\psql}, + build the plugin as follows: + + \snippet code/doc_src_sql-driver.qdoc 15 + + Users of MinGW may wish to consult the following online document: + \l{PostgreSQL MinGW/Native Windows}. + + \b{Note:} This database plugin is not supported for Windows CE. + + \target QTDS + \section2 QTDS for Sybase Adaptive Server + + \note TDS is no longer used by MS Sql Server, and is superceded by + \l{QODBC}{ODBC}. QTDS is obsolete from Qt 4.7. + + \section3 General Information about QTDS + + It is not possible to set the port with QSqlDatabase::setPort() due to limitations in the + Sybase client library. Refer to the Sybase documentation for information on how to set up + a Sybase client configuration file to enable connections to databases on non-default ports. + + \section3 How to Build the QTDS Plugin on Unix and Mac OS X + + Under Unix, two libraries are available which support the TDS protocol: + + \list + \li FreeTDS, a free implementation of the TDS protocol + (\l{http://www.freetds.org}). Note that FreeTDS is not yet stable, + so some functionality may not work as expected. + + \li Sybase Open Client, available from \l{http://www.sybase.com}. + Note for Linux users: Get the Open Client RPM from + \l{http://linux.sybase.com}. + \endlist + + Regardless of which library you use, the shared object file + \c{libsybdb.so} is needed. Set the \c SYBASE environment variable to + point to the directory where you installed the client library and + execute \c{qmake}: + + \snippet code/doc_src_sql-driver.qdoc 16 + + \section3 How to Build the QDTS Plugin on Windows + + You can either use the DB-Library supplied by Microsoft or the Sybase + Open Client (\l{http://www.sybase.com}). You must include \c + NTWDBLIB.LIB to build the plugin: + + \snippet code/doc_src_sql-driver.qdoc 17 + + By default the Microsoft library is used on Windows, if you want to + force the use of the Sybase Open Client, you must define \c + Q_USE_SYBASE in \c{%QTDIR%\src\sql\drivers\tds\qsql_tds.cpp}. If you + are not using a Microsoft compiler, replace \c nmake with \c make in + the line above. + + \b{Note:} This database plugin is not supported for Windows CE. + + \target QDB2 + \section2 QDB2 for IBM DB2 (Version 7.1 and Above) + + \section3 General Information about QDB2 + + The Qt DB2 plugin makes it possible to access IBM DB2 databases. It + has been tested with IBM DB2 v7.1 and 7.2. You must install the IBM + DB2 development client library, which contains the header and library + files necessary for compiling the QDB2 plugin. + + The QDB2 driver supports prepared queries, reading/writing of Unicode + strings and reading/writing of BLOBs. + + We suggest using a forward-only query when calling stored procedures + in DB2 (see QSqlQuery::setForwardOnly()). + + \section3 How to Build the QDB2 Plugin on Unix and Mac OS X + + \snippet code/doc_src_sql-driver.qdoc 18 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet code/doc_src_sql-driver.qdoc 19 + + \section3 How to Build the QDB2 Plugin on Windows + + The DB2 header and include files should already be installed in the + right directories. You just have to build the plugin as follows: + + \snippet code/doc_src_sql-driver.qdoc 20 + + If you are not using a Microsoft compiler, replace \c nmake + with \c make in the line above. + + \b{Note:} This database plugin is not supported for Windows CE. + + \target QSQLITE2 + \section2 QSQLITE2 for SQLite Version 2 + + The Qt SQLite 2 plugin is offered for compatibility. Whenever + possible, use the \l{#QSQLITE}{version 3 plugin} instead. The + build instructions for version 3 apply to version 2 as well. + + \target QSQLITE + \section2 QSQLITE for SQLite (Version 3 and Above) + + \section3 General Information about QSQLITE + + The Qt SQLite plugin makes it possible to access SQLite + databases. SQLite is an in-process database, which means that it + is not necessary to have a database server. SQLite operates on a + single file, which must be set as the database name when opening + a connection. If the file does not exist, SQLite will try to + create it. SQLite also supports in-memory databases, simply pass + ":memory:" as the database name. + + SQLite has some restrictions regarding multiple users and + multiple transactions. If you try to read/write on a resource from different + transactions, your application might freeze until one transaction commits + or rolls back. The Qt SQLite driver will retry to write to a locked resource + until it runs into a timeout (see \c{QSQLITE_BUSY_TIMEOUT} + at QSqlDatabase::setConnectOptions()). + + In SQLite any column, with the exception of an INTEGER PRIMARY KEY column, + may be used to store any type of value. For instance, a column declared as + INTEGER may contain an integer value in one row and a text value in the + next. This is due to SQLite associating the type of a value with the value + itself rather than with the column it is stored in. A consequence of this + is that the type returned by QSqlField::type() only indicates the field's + recommended type. No assumption of the actual type should be made from + this and the type of the individual values should be checked. + + The driver is locked for updates while a select is executed. This + may cause problems when using QSqlTableModel because Qt's item views + fetch data as needed (with QSqlQuery::fetchMore() in the case of + QSqlTableModel). + + You can find information about SQLite on \l{http://www.sqlite.org}. + + \section3 How to Build the QSQLITE Plugin + + SQLite version 3 is included as a third-party library within Qt. + It can be built by passing the following parameters to the + configure script: \c{-plugin-sql-sqlite} (build as a plugin) or + \c{-qt-sql-sqlite} (linked directly into the Qt library). + + If you don't want to use the SQLite library included with Qt, you + can pass \c{-system-sqlite} to the configure script to use sqlite + libraries in the operating system. Alternatively, you can build + it manually (replace \c $SQLITE with the directory where + SQLite resides): + + \snippet code/doc_src_sql-driver.qdoc 21 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet code/doc_src_sql-driver.qdoc 22 + + On Windows: + + \snippet code/doc_src_sql-driver.qdoc 23 + + \section3 QSQLITE File Format Compatibility + + SQLite minor releases sometimes break file format forward compatibility. + For example, SQLite 3.3 can read database files created with SQLite 3.2, + but databases created with SQLite 3.3 cannot be read by SQLite 3.2. + Please refer to the SQLite documentation and change logs for information about + file format compatibility between versions. + + Qt minor releases usually follow the SQLite minor releases, while Qt patch releases + follow SQLite patch releases. Patch releases are therefore both backward and forward + compatible. + + To force SQLite to use a specific file format, it is necessary to build and + ship your own database plugin with your own SQLite library as illustrated above. + Some versions of SQLite can be forced to write a specific file format by setting + the \c{SQLITE_DEFAULT_FILE_FORMAT} define when building SQLite. + + \target QIBASE + \section2 QIBASE for Borland InterBase + + \section3 General Information about QIBASE + + The Qt InterBase plugin makes it possible to access the InterBase and + Firebird databases. InterBase can either be used as a client/server or + without a server in which case it operates on local files. The + database file must exist before a connection can be established. Firebird + must be used with a server configuration. + + Note that InterBase requires you to specify the full path to the + database file, no matter whether it is stored locally or on another + server. + + \snippet code/doc_src_sql-driver.cpp 24 + + You need the InterBase/Firebird development headers and libraries + to build this plugin. + + Due to license incompatibilities with the GPL, users of the Qt Open Source + Edition are not allowed to link this plugin to the commercial editions of + InterBase. Please use Firebird or the free edition of InterBase. + + \section3 QIBASE Unicode Support and Text Encoding + + By default the driver connects to the database using UNICODE_FSS. This can + be overridden by setting the ISC_DPB_LC_CTYPE parameter with + QSqlDatabase::setConnectOptions() before opening the connection. + + \snippet code/doc_src_sql-driver.cpp 25 + + If Qt doesn't support the given text encoding the driver will issue a + warning message and connect to the database using UNICODE_FSS. + + Note that if the text encoding set when connecting to the database is + not the same as in the database, problems with transliteration might arise. + + \section3 QIBASE Stored procedures + + InterBase/Firebird return OUT values as result set, so when calling stored + procedure, only IN values need to be bound via QSqlQuery::bindValue(). The + RETURN/OUT values can be retrieved via QSqlQuery::value(). Example: + + \snippet code/doc_src_sql-driver.cpp 26 + + \section3 How to Build the QIBASE Plugin on Unix and Mac OS X + + The following assumes InterBase or Firebird is installed in + \c{/opt/interbase}: + + If you are using InterBase: + + \snippet code/doc_src_sql-driver.qdoc 27 + + If you are using Firebird, the Firebird library has to be set explicitly: + + \snippet code/doc_src_sql-driver.qdoc 28 + + \section3 How to Build the QIBASE Plugin on Windows + + The following assumes InterBase or Firebird is installed in + \c{C:\interbase}: + + If you are using InterBase: + + \snippet code/doc_src_sql-driver.qdoc 29 + + If you are using Firebird, the Firebird library has to be set explicitly: + + \snippet code/doc_src_sql-driver.qdoc 30 + + If you are not using a Microsoft compiler, replace \c nmake + with \c make in the line above. + + Note that \c{C:\interbase\bin} must be in the \c PATH. + + \b{Note:} This database plugin is not supported for Windows CE. + + \target troubleshooting + \section1 Troubleshooting + + You should always use client libraries that have been compiled with + the same compiler as you are using for your project. If you cannot get + a source distibution to compile the client libraries yourself, you + must make sure that the pre-compiled library is compatible with + your compiler, otherwise you will get a lot of "undefined symbols" + errors. Some compilers have tools to convert libraries, e.g. Borland + ships the tool \c{COFF2OMF.EXE} to convert libraries that have been + generated with Microsoft Visual C++. + + If the compilation of a plugin succeeds but it cannot be loaded, + make sure that the following requirements are met: + + \list + \li Ensure that you are using a shared Qt library; you cannot use the + plugins with a static build. + \li Ensure that the plugin is in the correct directory. You can use + QApplication::libraryPaths() to determine where Qt looks for plugins. + \li Ensure that the client libraries of the DBMS are available on the + system. On Unix, run the command \c{ldd} and pass the name of the + plugin as parameter, for example \c{ldd libqsqlmysql.so}. You will + get a warning if any of the client libraries couldn't be found. + On Windows, you can use Visual Studio's dependency walker. + \li Compile Qt with \c{QT_DEBUG_COMPONENT} defined to get very verbose + debug output when loading plugins. + \endlist + + Make sure you have followed the guide to \l{Deploying Plugins}. + If you experience plugin load problems and see output like this: + + \snippet code/doc_src_sql-driver.cpp 31 + + the problem is usually that the plugin had the wrong \l{Deploying + Plugins#The Build Key}{build key}. This might require removing an + entry from the \l{Deploying Plugins#The Plugin Cache} {plugin cache}. + + \target development + \section1 How to Write Your Own Database Driver + + QSqlDatabase is responsible for loading and managing database driver + plugins. When a database is added (see QSqlDatabase::addDatabase()), + the appropriate driver plugin is loaded (using QSqlDriverPlugin). + QSqlDatabase relies on the driver plugin to provide interfaces for + QSqlDriver and QSqlResult. + + QSqlDriver is an abstract base class which defines the functionality + of a SQL database driver. This includes functions such as + QSqlDriver::open() and QSqlDriver::close(). QSqlDriver is responsible + for connecting to a database, establish the proper environment, etc. + In addition, QSqlDriver can create QSqlQuery objects appropriate for + the particular database API. QSqlDatabase forwards many of its + function calls directly to QSqlDriver which provides the concrete + implementation. + + QSqlResult is an abstract base class which defines the functionality + of a SQL database query. This includes statements such as \c{SELECT}, + \c{UPDATE}, and \c{ALTER} \c{TABLE}. QSqlResult contains functions + such as QSqlResult::next() and QSqlResult::value(). QSqlResult is + responsible for sending queries to the database, returning result + data, etc. QSqlQuery forwards many of its function calls directly to + QSqlResult which provides the concrete implementation. + + QSqlDriver and QSqlResult are closely connected. When implementing a + Qt SQL driver, both of these classes must to be subclassed and the + abstract virtual methods in each class must be implemented. + + To implement a Qt SQL driver as a plugin (so that it is + recognized and loaded by the Qt library at runtime), the driver + must use the Q_EXPORT_PLUGIN2() macro. Read \l{How to Create Qt + Plugins} for more information on this. You can also check out how + this is done in the SQL plugins that are provided with Qt in + \c{QTDIR/src/plugins/sqldrivers} and \c{QTDIR/src/sql/drivers}. + + The following code can be used as a skeleton for a SQL driver: + + \snippet sqldatabase/sqldatabase.cpp 47 + \codeline + \snippet sqldatabase/sqldatabase.cpp 48 +*/ diff --git a/src/sql/doc/src/sql-programming.qdoc b/src/sql/doc/src/sql-programming.qdoc new file mode 100644 index 0000000000..53f89e72c9 --- /dev/null +++ b/src/sql/doc/src/sql-programming.qdoc @@ -0,0 +1,609 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group database + \title Database Classes + + \brief Database related classes, e.g. for SQL databases. +*/ + +/*! + \page sql-programming.html + \title SQL Programming + \ingroup qt-sql + \nextpage Connecting to Databases + + \brief Database integration for Qt applications. + + This overview assumes that you have at least a basic knowledge of + SQL. You should be able to understand simple \c SELECT, \c + INSERT, \c UPDATE, and \c DELETE statements. Although the \l + QSqlTableModel class provides an interface to database browsing + and editing that does not require a knowledge of SQL, a basic + understanding of SQL is highly recommended. A standard text + covering SQL databases is \e {An Introduction to Database Systems} + (7th Ed.) by C. J. Date, ISBN 0201385902. + + \section1 Topics: + + \list + \li \l{Database Classes} + \li \l{Connecting to Databases} + \list + \li \l{SQL Database Drivers} + \endlist + \li \l{Executing SQL Statements} + \list + \li \l{Data Types for Qt-supported Database Systems} + \endlist + \li \l{Using the SQL Model Classes} + \li \l{Presenting Data in a Table View} + \li \l{Creating Data-Aware Forms} + \endlist + + \section1 Database Classes + + These classes provide access to SQL databases. + + \annotatedlist database + + The SQL classes are divided into three layers: + + \section2 Driver Layer + + This comprises the classes QSqlDriver, QSqlDriverCreator, + QSqlDriverCreatorBase, QSqlDriverPlugin, and QSqlResult. + + This layer provides the low-level bridge between the specific databases + and the SQL API layer. See \l{SQL Database Drivers} for more information. + + \section2 SQL API Layer + + These classes provide access to databases. Connections + are made using the QSqlDatabase class. Database + interaction is achieved by using the QSqlQuery class. + In addition to QSqlDatabase and QSqlQuery, the SQL API + layer is supported by QSqlError, QSqlField, QSqlIndex, + and QSqlRecord. + + \section2 User Interface Layer + + These classes link the data from a database to data-aware widgets. + They include QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel. + These classes are designed to work with Qt's + \l{Model/View Programming}{model/view framework}. + + Note that to use any of these classes, a QCoreApplication object + must have been instantiated first. +*/ + +/*! + \page sql-connecting.html + \title Connecting to Databases + \ingroup qt-sql + + \contentspage SQL Programming + \previouspage SQL Programming + \nextpage Executing SQL Statements + + To access a database with QSqlQuery or QSqlQueryModel, create and + open one or more database connections. Database connections are + normally identified by connection name, \e{not} by database name. + You can have multiple connections to the same database. + QSqlDatabase also supports the concept of a \e{default} + connection, which is an unnamed connection. When calling QSqlQuery + or QSqlQueryModel member functions that take a connection name + argument, if you don't pass a connection name, the default + connection will be used. Creating a default connection is + convenient when your application only requires one database + connection. + + Note the difference between creating a connection and opening it. + Creating a connection involves creating an instance of class + QSqlDatabase. The connection is not usable until it is opened. The + following snippet shows how to create a \e{default} connection + and then open it: + + \snippet sqldatabase/sqldatabase.cpp 26 + + The first line creates the connection object, and the last line + opens it for use. In between, we initialize some connection + information, including the \l{QSqlDatabase::setDatabaseName()} + {database name}, the \l{QSqlDatabase::setHostName()} {host name}, + the \l{QSqlDatabase::setUserName()} {user name}, and the + \l{QSqlDatabase::setPassword()} {password}. In this case, we are + connecting to the MySQL database \c{flightdb} on the host + \c{bigblue}. The \c{"QMYSQL"} argument to + \l{QSqlDatabase::addDatabase()} {addDatabase()} specifies the type + of database driver to use for the connection. The set of database + drivers included with Qt are shown in the table of \l{SQL Database + Drivers#Supported Databases} {supported database drivers}. + + The connection in the snippet will be the \e{default} connection, + because we don't pass the second argument to + \l{QSqlDatabase::addDatabase()} {addDatabase()}, which is the + connection name. For example, here we establish two MySQL database + connections named \c{"first"} and \c{"second"}: + + \snippet sqldatabase/sqldatabase.cpp 27 + + After these connections have been initialized, \l{QSqlDatabase::} + {open()} for each one to establish the live connections. If the + \l{QSqlDatabase::} {open()} fails, it returns false. In that case, + call QSqlDatabase::lastError() to get error information. + + Once a connection is established, we can call the static function + QSqlDatabase::database() from anywhere with a connection name to + get a pointer to that database connection. If we don't pass a + connection name, it will return the default connection. For + example: + + \snippet sqldatabase/sqldatabase.cpp 28 + \snippet sqldatabase/sqldatabase.cpp 29 + \snippet sqldatabase/sqldatabase.cpp 30 + + To remove a database connection, first close the database using + QSqlDatabase::close(), then remove it using the static method + QSqlDatabase::removeDatabase(). +*/ + +/*! + \page sql-sqlstatements.html + \title Executing SQL Statements + \ingroup qt-sql + + \previouspage Connecting to Databases + \contentspage SQL Programming + \nextpage Using the SQL Model Classes + + + The QSqlQuery class provides an interface for executing SQL + statements and navigating through the result set of a query. + + The QSqlQueryModel and QSqlTableModel classes described in the + next section provide a higher-level interface for accessing + databases. If you are unfamiliar with SQL, you might want to skip + directly to the next section (\l{Using the SQL Model Classes}). + + \section2 Executing a Query + + To execute an SQL statement, simply create a QSqlQuery object and + call QSqlQuery::exec() like this: + + \snippet sqldatabase/sqldatabase.cpp 31 + + The QSqlQuery constructor accepts an optional QSqlDatabase object + that specifies which database connection to use. In the example + above, we don't specify any connection, so the default connection + is used. + + If an error occurs, \l{QSqlQuery::exec()}{exec()} returns false. + The error is then available as QSqlQuery::lastError(). + + \section2 Navigating the Result Set + + QSqlQuery provides access to the result set one record at a time. + After the call to \l{QSqlQuery::exec()}{exec()}, QSqlQuery's + internal pointer is located one position \e{before} the first + record. We must call QSqlQuery::next() once to advance to the + first record, then \l{QSqlQuery::next()}{next()} again repeatedly + to access the other records, until it returns false. Here's a + typical loop that iterates over all the records in order: + + \snippet sqldatabase/sqldatabase.cpp 32 + + The QSqlQuery::value() function returns the value of a field in + the current record. Fields are specified as zero-based indexes. + QSqlQuery::value() returns a QVariant, a type that can hold + various C++ and core Qt data types such as \c int, QString, and + QByteArray. The different database types are automatically mapped + into the closest Qt equivalent. In the code snippet, we call + QVariant::toString() and QVariant::toInt() to convert + variants to QString and \c int. + + For an overview of the recommended types for use with Qt-supported + Databases, please refer to \l{Data Types for Qt-supported Database + Systems} {this table}. + + You can iterate back and forth using QSqlQuery::next(), + QSqlQuery::previous(), QSqlQuery::first(), QSqlQuery::last(), and + QSqlQuery::seek(). The current row index is returned by + QSqlQuery::at(), and the total number of rows in the result set + is available as QSqlQuery::size() for databases that support it. + + To determine whether a database driver supports a given feature, + use QSqlDriver::hasFeature(). In the following example, we call + QSqlQuery::size() to determine the size of a result set of + the underlying database supports that feature; otherwise, we + navigate to the last record and use the query's position to tell + us how many records there are. + + \snippet sqldatabase/sqldatabase.cpp 33 + + If you iterate through a result set only using next() and seek() + with positive values, you can call + QSqlQuery::setForwardOnly(true) before calling exec(). This is an + easy optimization that will speed up the query significantly when + operating on large result sets. + + \section2 Inserting, Updating, and Deleting Records + + QSqlQuery can execute arbitrary SQL statements, not just + \c{SELECT}s. The following example inserts a record into a table + using \c{INSERT}: + + \snippet sqldatabase/sqldatabase.cpp 34 + + If you want to insert many records at the same time, it is often + more efficient to separate the query from the actual values being + inserted. This can be done using placeholders. Qt supports two + placeholder syntaxes: named binding and positional binding. + Here's an example of named binding: + + \snippet sqldatabase/sqldatabase.cpp 35 + + Here's an example of positional binding: + + \snippet sqldatabase/sqldatabase.cpp 36 + + Both syntaxes work with all database drivers provided by Qt. If + the database supports the syntax natively, Qt simply forwards the + query to the DBMS; otherwise, Qt simulates the placeholder syntax + by preprocessing the query. The actual query that ends up being + executed by the DBMS is available as QSqlQuery::executedQuery(). + + When inserting multiple records, you only need to call + QSqlQuery::prepare() once. Then you call + \l{QSqlQuery::bindValue()}{bindValue()} or + \l{QSqlQuery::addBindValue()}{addBindValue()} followed by + \l{QSqlQuery::exec()}{exec()} as many times as necessary. + + Besides performance, one advantage of placeholders is that you + can easily specify arbitrary values without having to worry about + escaping special characters. + + Updating a record is similar to inserting it into a table: + + \snippet sqldatabase/sqldatabase.cpp 37 + + You can also use named or positional binding to associate + parameters to actual values. + + Finally, here's an example of a \c DELETE statement: + + \snippet sqldatabase/sqldatabase.cpp 38 + + \section2 Transactions + + If the underlying database engine supports transactions, + QSqlDriver::hasFeature(QSqlDriver::Transactions) will return + true. You can use QSqlDatabase::transaction() to initiate a + transaction, followed by the SQL commands you want to execute + within the context of the transaction, and then either + QSqlDatabase::commit() or QSqlDatabase::rollback(). When + using transactions you must start the transaction before you + create your query. + + Example: + + \snippet sqldatabase/sqldatabase.cpp 39 + + Transactions can be used to ensure that a complex operation is + atomic (for example, looking up a foreign key and creating a + record), or to provide a means of canceling a complex change in + the middle. + + \omit + It would be useful to mention transactions, and the fact that + some databases don't support them. + \endomit +*/ + +/*! + \page sql-model.html + \title Using the SQL Model Classes + \ingroup qt-sql + + \previouspage Executing SQL Statements + \contentspage SQL Programming + \nextpage Presenting Data in a Table View + + In addition to QSqlQuery, Qt offers three higher-level classes + for accessing databases. These classes are QSqlQueryModel, + QSqlTableModel, and QSqlRelationalTableModel. + + \table + \row \li QSqlQueryModel + \li A read-only model based on an arbitrary SQL query. + \row \li QSqlTableModel + \li A read-write model that works on a single table. + \row \li QSqlRelationalTableModel + \li A QSqlTableModel subclass with foreign key support. + \endtable + + These classes derive from QAbstractTableModel (which in turn + inherits from QAbstractItemModel) and make it easy to present + data from a database in an item view class such as QListView and + QTableView. This is explained in detail in the \l{Presenting Data + in a Table View} section. + + Another advantage of using these classes is that it can make your + code easier to adapt to other data sources. For example, if you + use QSqlTableModel and later decide to use XML files to store + data instead of a database, it is essentially just a matter of + replacing one data model with another. + + \section2 The SQL Query Model + + QSqlQueryModel offers a read-only model based on an SQL query. + + Example: + + \snippet sqldatabase/sqldatabase.cpp 40 + + After setting the query using QSqlQueryModel::setQuery(), you can + use QSqlQueryModel::record(int) to access the individual records. + You can also use QSqlQueryModel::data() and any of the other + functions inherited from QAbstractItemModel. + + There's also a \l{QSqlQueryModel::setQuery()}{setQuery()} + overload that takes a QSqlQuery object and operates on its result + set. This enables you to use any features of QSqlQuery to set up + the query (e.g., prepared queries). + + \section2 The SQL Table Model + + QSqlTableModel offers a read-write model that works on a single + SQL table at a time. + + Example: + + \snippet sqldatabase/sqldatabase.cpp 41 + + QSqlTableModel is a high-level alternative to QSqlQuery for + navigating and modifying individual SQL tables. It typically + results in less code and requires no knowledge of SQL syntax. + + Use QSqlTableModel::record() to retrieve a row in the table, and + QSqlTableModel::setRecord() to modify the row. For example, the + following code will increase every employee's salary by 10 per + cent: + + \snippet sqldatabase/sqldatabase.cpp 42 + + You can also use QSqlTableModel::data() and + QSqlTableModel::setData(), which are inherited from + QAbstractItemModel, to access the data. For example, here's how + to update a record using + \l{QSqlTableModel::setData()}{setData()}: + + \snippet sqldatabase/sqldatabase.cpp 43 + + Here's how to insert a row and populate it: + + \snippet sqldatabase/sqldatabase.cpp 44 + + Here's how to delete five consecutive rows: + + \snippet sqldatabase/sqldatabase.cpp 45 + \snippet sqldatabase/sqldatabase.cpp 46 + + The first argument to QSqlTableModel::removeRows() is the index + of the first row to delete. + + When you're finished changing a record, you should always call + QSqlTableModel::submitAll() to ensure that the changes are + written to the database. + + When and whether you actually \e need to call submitAll() depends + on the table's \l{QSqlTableModel::editStrategy()}{edit strategy}. + The default strategy is QSqlTableModel::OnRowChange, which + specifies that pending changes are applied to the database when + the user selects a different row. Other strategies are + QSqlTableModel::OnManualSubmit (where all changes are cached in + the model until you call submitAll()) and + QSqlTableModel::OnFieldChange (where no changes are cached). + These are mostly useful when QSqlTableModel is used with a view. + + QSqlTableModel::OnFieldChange seems to deliver the promise that + you never need to call submitAll() explicitly. There are two + pitfalls, though: + + \list + \li Without any caching, performance may drop significantly. + \li If you modify a primary key, the record might slip through + your fingers while you are trying to populate it. + \endlist + + \section2 The SQL Relational Table Model + + QSqlRelationalTableModel extends QSqlTableModel to provide + support for foreign keys. A foreign key is a 1-to-1 mapping + between a field in one table and the primary key field of another + table. For example, if a \c book table has a field called \c + authorid that refers to the author table's \c id field, we say + that \c authorid is a foreign key. + + \table + \row \li \inlineimage noforeignkeys.png + \li \inlineimage foreignkeys.png + \endtable + + The screenshot on the left shows a plain QSqlTableModel in a + QTableView. Foreign keys (\c city and \c country) aren't resolved + to human-readable values. The screenshot on the right shows a + QSqlRelationalTableModel, with foreign keys resolved into + human-readable text strings. + + The following code snippet shows how the QSqlRelationalTableModel + was set up: + + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 0 + \codeline + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 1 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 2 + + See the QSqlRelationalTableModel documentation for details. +*/ + +/*! + \page sql-presenting.html + \title Presenting Data in a Table View + \ingroup qt-sql + + \previouspage Using the SQL Model Classes + \contentspage SQL Programming + \nextpage Creating Data-Aware Forms + + The QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel + classes can be used as a data source for Qt's view classes such + as QListView, QTableView, and QTreeView. In practice, QTableView + is by far the most common choice, because an SQL result set is + essentially a two-dimensional data structure. + + \image relationaltable.png A table view displaying a QSqlTableModel + + The following example creates a view based on an SQL data model: + + \snippet sqldatabase/sqldatabase.cpp 17 + \snippet sqldatabase/sqldatabase.cpp 18 + \snippet sqldatabase/sqldatabase.cpp 19 + + If the model is a read-write model (e.g., QSqlTableModel), the + view lets the user edit the fields. You can disable this by + calling + + \snippet sqldatabase/sqldatabase.cpp 20 + + You can use the same model as a data source for multiple views. + If the user edits the model through one of the views, the other + views will reflect the changes immediately. The + \l{sql/tablemodel}{Table Model} example shows how it works. + + View classes display a header at the top to label the columns. To + change the header texts, call + \l{QAbstractItemModel::setHeaderData()}{setHeaderData()} on the + model. The header's labels default to the table's field names. + For example: + + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 3 + + QTableView also has a vertical header on the left with numbers + identifying the rows. If you insert rows programmatically using + QSqlTableModel::insertRows(), the new rows will be marked with an + asterisk (*) until they are submitted using + \l{QSqlTableModel::submitAll()}{submitAll()} or automatically + when the user moves to another record (assuming the + \l{QSqlTableModel::EditStrategy}{edit strategy} is + QSqlTableModel::OnRowChange). + + \image insertrowinmodelview.png Inserting a row in a model + + Likewise, if you remove rows using + \l{QSqlTableModel::removeRows()}{removeRows()}, the rows will be + marked with an exclamation mark (!) until the change is + submitted. + + The items in the view are rendered using a delegate. The default + delegate, QItemDelegate, handles the most common data types (\c + int, QString, QImage, etc.). The delegate is also responsible for + providing editor widgets (e.g., a combobox) when the user starts + editing an item in the view. You can create your own delegates by + subclassing QAbstractItemDelegate or QItemDelegate. See + \l{Model/View Programming} for more information. + + QSqlTableModel is optimized to operate on a single table at a + time. If you need a read-write model that operates on an + arbitrary result set, you can subclass QSqlQueryModel and + reimplement \l{QAbstractItemModel::flags()}{flags()} and + \l{QAbstractItemModel::setData()}{setData()} to make it + read-write. The following two functions make fields 1 and 2 of a + query model editable: + + \snippet sql/querymodel/editablesqlmodel.cpp 0 + \codeline + \snippet sql/querymodel/editablesqlmodel.cpp 1 + + The setFirstName() helper function is defined as follows: + + \snippet sql/querymodel/editablesqlmodel.cpp 2 + + The setLastName() function is similar. See the + \l{sql/querymodel}{Query Model} example for the complete source code. + + Subclassing a model makes it possible to customize it in many + ways: You can provide tooltips for the items, change the + background color, provide calculated values, provide different + values for viewing and editing, handle null values specially, and + more. See \l{Model/View Programming} as well as the \l + QAbstractItemView reference documentation for details. + + If all you need is to resolve a foreign key to a more + human-friendly string, you can use QSqlRelationalTableModel. For + best results, you should also use QSqlRelationalDelegate, a + delegate that provides combobox editors for editing foreign keys. + + \image relationaltable.png Editing a foreign key in a relational table + + The \l{sql/relationaltablemodel}{Relational Table Model} example + illustrates how to use QSqlRelationalTableModel in conjunction with + QSqlRelationalDelegate to provide tables with foreign key + support. +*/ + +/*! + \page sql-forms.html + \title Creating Data-Aware Forms + \ingroup qt-sql + + \previouspage Presenting Data in a Table View + \contentspage SQL Programming + + Using the SQL models described above, the contents of a database can + be presented to other model/view components. For some applications, + it is sufficient to present this data using a standard item view, + such as QTableView. However, users of record-based applications often + require a form-based user interface in which data from a specific + row or column in a database table is used to populate editor widgets + on a form. + + Such data-aware forms can be created with the QDataWidgetMapper class, + a generic model/view component that is used to map data from a model + to specific widgets in a user interface. + + QDataWidgetMapper operates on a specific database table, mapping items + in the table on a row-by-row or column-by-column basis. As a result, + using QDataWidgetMapper with a SQL model is as simple as using it with + any other table model. + + \image qdatawidgetmapper-simple.png + + The \l{sql/books}{Books} example shows how information can + be presented for easy access by using QDataWidgetMapper and a set of + simple input widgets. +*/ diff --git a/src/sql/kernel/qsql.qdoc b/src/sql/kernel/qsql.qdoc index 394c255b35..6fbfc0415d 100644 --- a/src/sql/kernel/qsql.qdoc +++ b/src/sql/kernel/qsql.qdoc @@ -35,7 +35,7 @@ \ingroup database - \sa {QtSql Module} + \sa {Qt SQL Module} */ /*! diff --git a/src/sql/kernel/qsqldatabase.cpp b/src/sql/kernel/qsqldatabase.cpp index d4633cea57..f44f475d6c 100644 --- a/src/sql/kernel/qsqldatabase.cpp +++ b/src/sql/kernel/qsqldatabase.cpp @@ -390,7 +390,7 @@ void QSqlDatabasePrivate::disable() snippet shows how to create and open a default connection to a PostgreSQL database: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 0 + \snippet sqldatabase/sqldatabase.cpp 0 Once the QSqlDatabase object has been created, set the connection parameters with setDatabaseName(), setUserName(), setPassword(), @@ -403,7 +403,7 @@ void QSqlDatabasePrivate::disable() {addDatabase()}. Subsequently, you can get the default connection by calling database() without the connection name argument: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 1 + \snippet sqldatabase/sqldatabase.cpp 1 QSqlDatabase is a value class. Changes made to a database connection via one instance of QSqlDatabase will affect other @@ -440,7 +440,7 @@ void QSqlDatabasePrivate::disable() If you have created your own custom driver, you must register it with registerSqlDriver(). - \sa QSqlDriver, QSqlQuery, {QtSql Module}, {Threads and the SQL Module} + \sa QSqlDriver, QSqlQuery, {Qt SQL Module}, {Threads and the SQL Module} */ /*! \fn QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName) @@ -472,7 +472,7 @@ void QSqlDatabasePrivate::disable() setHostName(), setPort(), and setConnectOptions(), and, finally, open(). - \sa database() removeDatabase() {Threads and the SQL Module} + \sa database(), removeDatabase(), {Threads and the SQL Module} */ QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName) { @@ -492,7 +492,7 @@ QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &conne connectionName does not exist in the list of databases, an invalid connection is returned. - \sa isOpen() {Threads and the SQL Module} + \sa isOpen(), {Threads and the SQL Module} */ QSqlDatabase QSqlDatabase::database(const QString& connectionName, bool open) @@ -512,11 +512,11 @@ QSqlDatabase QSqlDatabase::database(const QString& connectionName, bool open) Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 0 + \snippet code/src_sql_kernel_qsqldatabase.cpp 0 The correct way to do it: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 1 + \snippet code/src_sql_kernel_qsqldatabase.cpp 1 To remove the default connection, which may have been created with a call to addDatabase() not specifying a connection name, you can @@ -524,7 +524,7 @@ QSqlDatabase QSqlDatabase::database(const QString& connectionName, bool open) the database returned by database(). Note that if a default database hasn't been created an invalid database will be returned. - \sa database() connectionName() {Threads and the SQL Module} + \sa database(), connectionName(), {Threads and the SQL Module} */ void QSqlDatabase::removeDatabase(const QString& connectionName) @@ -600,7 +600,7 @@ QStringList QSqlDatabase::drivers() and don't want to compile it as a plugin. Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 2 + \snippet code/src_sql_kernel_qsqldatabase.cpp 2 QSqlDatabase takes ownership of the \a creator pointer, so you mustn't delete it yourself. @@ -831,8 +831,8 @@ QSqlQuery QSqlDatabase::exec(const QString & query) const values. Returns true on success; otherwise returns false. Error information can be retrieved using lastError(). - \sa lastError() setDatabaseName() setUserName() setPassword() - \sa setHostName() setPort() setConnectOptions() + \sa lastError(), setDatabaseName(), setUserName(), setPassword(), + setHostName(), setPort(), setConnectOptions() */ bool QSqlDatabase::open() @@ -924,7 +924,7 @@ bool QSqlDatabase::transaction() Call lastError() to get information about errors. - \sa QSqlQuery::isActive() QSqlDriver::hasFeature() rollback() + \sa QSqlQuery::isActive(), QSqlDriver::hasFeature(), rollback() */ bool QSqlDatabase::commit() { @@ -945,7 +945,7 @@ bool QSqlDatabase::commit() Call lastError() to get information about errors. - \sa QSqlQuery::isActive() QSqlDriver::hasFeature() commit() + \sa QSqlQuery::isActive(), QSqlDriver::hasFeature(), commit() */ bool QSqlDatabase::rollback() { @@ -974,12 +974,12 @@ bool QSqlDatabase::rollback() connection string to open an \c .mdb file directly, instead of having to create a DSN entry in the ODBC manager: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 3 + \snippet code/src_sql_kernel_qsqldatabase.cpp 3 There is no default value. - \sa databaseName() setUserName() setPassword() setHostName() - \sa setPort() setConnectOptions() open() + \sa databaseName(), setUserName(), setPassword(), setHostName(), + setPort(), setConnectOptions(), open() */ void QSqlDatabase::setDatabaseName(const QString& name) @@ -996,8 +996,8 @@ void QSqlDatabase::setDatabaseName(const QString& name) There is no default value. - \sa userName() setDatabaseName() setPassword() setHostName() - \sa setPort() setConnectOptions() open() + \sa userName(), setDatabaseName(), setPassword(), setHostName(), + setPort(), setConnectOptions(), open() */ void QSqlDatabase::setUserName(const QString& name) @@ -1018,8 +1018,8 @@ void QSqlDatabase::setUserName(const QString& name) Qt. Use the open() call that takes a password as parameter to avoid this behavior. - \sa password() setUserName() setDatabaseName() setHostName() - \sa setPort() setConnectOptions() open() + \sa password(), setUserName(), setDatabaseName(), setHostName(), + setPort(), setConnectOptions(), open() */ void QSqlDatabase::setPassword(const QString& password) @@ -1036,8 +1036,8 @@ void QSqlDatabase::setPassword(const QString& password) There is no default value. - \sa hostName() setUserName() setPassword() setDatabaseName() - \sa setPort() setConnectOptions() open() + \sa hostName(), setUserName(), setPassword(), setDatabaseName(), + setPort(), setConnectOptions(), open() */ void QSqlDatabase::setHostName(const QString& host) @@ -1054,8 +1054,8 @@ void QSqlDatabase::setHostName(const QString& host) There is no default value. - \sa port() setUserName() setPassword() setHostName() - \sa setDatabaseName() setConnectOptions() open() + \sa port(), setUserName(), setPassword(), setHostName(), + setDatabaseName(), setConnectOptions(), open() */ void QSqlDatabase::setPort(int port) @@ -1130,7 +1130,7 @@ int QSqlDatabase::port() const Returns the database driver used to access the database connection. - \sa addDatabase() drivers() + \sa addDatabase(), drivers() */ QSqlDriver* QSqlDatabase::driver() const @@ -1278,7 +1278,7 @@ QSqlRecord QSqlDatabase::record(const QString& tablename) const \endtable Examples: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 4 + \snippet code/src_sql_kernel_qsqldatabase.cpp 4 Refer to the client library documentation for more information about the different options. @@ -1325,9 +1325,9 @@ bool QSqlDatabase::isDriverAvailable(const QString& name) application. For example, you can create a PostgreSQL connection with your own QPSQL driver like this: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 5 + \snippet code/src_sql_kernel_qsqldatabase.cpp 5 \codeline - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 6 + \snippet code/src_sql_kernel_qsqldatabase.cpp 6 The above code sets up a PostgreSQL connection and instantiates a QPSQLDriver object. Next, addDatabase() is called to add the @@ -1346,7 +1346,7 @@ bool QSqlDatabase::isDriverAvailable(const QString& name) client library. Make sure the client library is in your linker's search path, and add lines like these to your \c{.pro} file: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 7 + \snippet code/src_sql_kernel_qsqldatabase.cpp 7 The method described works for all the supplied drivers. The only difference will be in the driver constructor arguments. Here is a @@ -1423,7 +1423,7 @@ QSqlDatabase QSqlDatabase::addDatabase(QSqlDriver* driver, const QString& connec Returns true if the QSqlDatabase has a valid driver. Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 8 + \snippet code/src_sql_kernel_qsqldatabase.cpp 8 */ bool QSqlDatabase::isValid() const { diff --git a/src/sql/kernel/qsqldriver.cpp b/src/sql/kernel/qsqldriver.cpp index f48673f28f..284ef84f2d 100644 --- a/src/sql/kernel/qsqldriver.cpp +++ b/src/sql/kernel/qsqldriver.cpp @@ -133,7 +133,7 @@ QSqlDriver::~QSqlDriver() /*! \since 5.0 - \fn QSqlDriver::notification(const QString &name, NotificationSource source, const QString & payload) + \fn QSqlDriver::notification(const QString &name, QSqlDriver::NotificationSource source, const QVariant & payload) This signal is emitted when the database posts an event notification that the driver subscribes to. \a name identifies the event notification, \a source indicates the signal source, @@ -682,11 +682,11 @@ QString QSqlDriver::formatValue(const QSqlField &field, bool trimStrings) const This example retrieves the handle for a connection to sqlite: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldriver.cpp 0 + \snippet code/src_sql_kernel_qsqldriver.cpp 0 This snippet returns the handle for PostgreSQL or MySQL: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldriver.cpp 1 + \snippet code/src_sql_kernel_qsqldriver.cpp 1 \sa QSqlResult::handle() */ @@ -695,36 +695,6 @@ QVariant QSqlDriver::handle() const return QVariant(); } -/*! - \fn QSqlRecord QSqlDriver::record(const QSqlQuery& query) const - - Use query.record() instead. -*/ - -/*! - \fn QSqlRecord QSqlDriver::recordInfo(const QString& tablename) const - - Use record() instead. -*/ - -/*! - \fn QSqlRecord QSqlDriver::recordInfo(const QSqlQuery& query) const - - Use query.record() instead. -*/ - -/*! - \fn QString QSqlDriver::nullText() const - - sqlStatement() is now used to generate SQL. Use tr("NULL") for example, instead. -*/ - -/*! - \fn QString QSqlDriver::formatValue(const QSqlField *field, bool trimStrings) const - - Use the other formatValue() overload instead. -*/ - /*! This function is called to subscribe to event notifications from the database. \a name identifies the event notification. @@ -743,7 +713,7 @@ QVariant QSqlDriver::handle() const own QSqlDriver subclass, \since 4.4 - \sa unsubscribeFromNotification() subscribedToNotifications() QSqlDriver::hasFeature() + \sa unsubscribeFromNotification(), subscribedToNotifications(), QSqlDriver::hasFeature() */ bool QSqlDriver::subscribeToNotification(const QString &name) { @@ -767,7 +737,7 @@ bool QSqlDriver::subscribeToNotification(const QString &name) own QSqlDriver subclass, \since 4.4 - \sa subscribeToNotification() subscribedToNotifications() + \sa subscribeToNotification(), subscribedToNotifications() */ bool QSqlDriver::unsubscribeFromNotification(const QString &name) { @@ -782,7 +752,7 @@ bool QSqlDriver::unsubscribeFromNotification(const QString &name) own QSqlDriver subclass, \since 4.4 - \sa subscribeToNotification() unsubscribeFromNotification() + \sa subscribeToNotification(), unsubscribeFromNotification() */ QStringList QSqlDriver::subscribedToNotifications() const { diff --git a/src/sql/kernel/qsqlerror.cpp b/src/sql/kernel/qsqlerror.cpp index 79c7ee02c2..c1314a15a5 100644 --- a/src/sql/kernel/qsqlerror.cpp +++ b/src/sql/kernel/qsqlerror.cpp @@ -155,7 +155,7 @@ QSqlError::~QSqlError() Returns the text of the error as reported by the driver. This may contain database-specific descriptions. It may also be empty. - \sa setDriverText() databaseText() text() + \sa setDriverText(), databaseText(), text() */ QString QSqlError::driverText() const { @@ -165,7 +165,7 @@ QString QSqlError::driverText() const /*! Sets the driver error text to the value of \a driverText. - \sa driverText() setDatabaseText() text() + \sa driverText(), setDatabaseText(), text() */ void QSqlError::setDriverText(const QString& driverText) @@ -177,7 +177,7 @@ void QSqlError::setDriverText(const QString& driverText) Returns the text of the error as reported by the database. This may contain database-specific descriptions; it may be empty. - \sa setDatabaseText() driverText() text() + \sa setDatabaseText(), driverText(), text() */ QString QSqlError::databaseText() const @@ -188,7 +188,7 @@ QString QSqlError::databaseText() const /*! Sets the database error text to the value of \a databaseText. - \sa databaseText() setDriverText() text() + \sa databaseText(), setDriverText(), text() */ void QSqlError::setDatabaseText(const QString& databaseText) @@ -245,7 +245,7 @@ void QSqlError::setNumber(int number) This is a convenience function that returns databaseText() and driverText() concatenated into a single string. - \sa driverText() databaseText() + \sa driverText(), databaseText() */ QString QSqlError::text() const @@ -261,7 +261,7 @@ QString QSqlError::text() const Returns true if an error is set, otherwise false. Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlerror.cpp 0 + \snippet code/src_sql_kernel_qsqlerror.cpp 0 \sa type() */ diff --git a/src/sql/kernel/qsqlfield.cpp b/src/sql/kernel/qsqlfield.cpp index 3160d25ef5..47162afb47 100644 --- a/src/sql/kernel/qsqlfield.cpp +++ b/src/sql/kernel/qsqlfield.cpp @@ -113,21 +113,21 @@ public: Field data values are stored as QVariants. Using an incompatible type is not permitted. For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 2 + \snippet sqldatabase/sqldatabase.cpp 2 However, the field will attempt to cast certain data types to the field data type where possible: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 3 + \snippet sqldatabase/sqldatabase.cpp 3 QSqlField objects are rarely created explicitly in application code. They are usually accessed indirectly through \l{QSqlRecord}s that already contain a list of fields. For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 4 + \snippet sqldatabase/sqldatabase.cpp 4 \dots - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 5 - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 6 + \snippet sqldatabase/sqldatabase.cpp 5 + \snippet sqldatabase/sqldatabase.cpp 6 A QSqlField object can provide some meta-data about the field, for example, its name(), variant type(), length(), precision(), @@ -157,7 +157,8 @@ public: Constructs an empty field called \a fieldName of variant type \a type. - \sa setRequiredStatus() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly() + \sa setRequiredStatus(), setLength(), setPrecision(), setDefaultValue(), + setGenerated(), setReadOnly() */ QSqlField::QSqlField(const QString& fieldName, QVariant::Type type) { @@ -216,7 +217,8 @@ QSqlField::~QSqlField() /*! Sets the required status of this field to \a required. - \sa requiredStatus() setType() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly() + \sa requiredStatus(), setType(), setLength(), setPrecision(), + setDefaultValue(), setGenerated(), setReadOnly() */ void QSqlField::setRequiredStatus(RequiredStatus required) { @@ -237,7 +239,8 @@ void QSqlField::setRequiredStatus(RequiredStatus required) maximum number of characters the string can hold; the meaning varies for other types. - \sa length() setType() setRequiredStatus() setPrecision() setDefaultValue() setGenerated() setReadOnly() + \sa length(), setType(), setRequiredStatus(), setPrecision(), + setDefaultValue(), setGenerated(), setReadOnly() */ void QSqlField::setLength(int fieldLength) { @@ -248,7 +251,8 @@ void QSqlField::setLength(int fieldLength) /*! Sets the field's \a precision. This only affects numeric fields. - \sa precision() setType() setRequiredStatus() setLength() setDefaultValue() setGenerated() setReadOnly() + \sa precision(), setType(), setRequiredStatus(), setLength(), + setDefaultValue(), setGenerated(), setReadOnly() */ void QSqlField::setPrecision(int precision) { @@ -259,7 +263,8 @@ void QSqlField::setPrecision(int precision) /*! Sets the default value used for this field to \a value. - \sa defaultValue() value() setType() setRequiredStatus() setLength() setPrecision() setGenerated() setReadOnly() + \sa defaultValue(), value(), setType(), setRequiredStatus(), + setLength(), setPrecision(), setGenerated(), setReadOnly() */ void QSqlField::setDefaultValue(const QVariant &value) { @@ -282,7 +287,8 @@ void QSqlField::setSqlType(int type) QSqlQueryModel and QSqlTableModel will generate SQL for this field. - \sa isGenerated() setType() setRequiredStatus() setLength() setPrecision() setDefaultValue() setReadOnly() + \sa isGenerated(), setType(), setRequiredStatus(), setLength(), + setPrecision(), setDefaultValue(), setReadOnly() */ void QSqlField::setGenerated(bool gen) { @@ -302,7 +308,7 @@ void QSqlField::setGenerated(bool gen) To set the value to NULL, use clear(). - \sa value() isReadOnly() defaultValue() + \sa value(), isReadOnly(), defaultValue() */ void QSqlField::setValue(const QVariant& value) @@ -316,7 +322,7 @@ void QSqlField::setValue(const QVariant& value) Clears the value of the field and sets it to NULL. If the field is read-only, nothing happens. - \sa setValue() isReadOnly() requiredStatus() + \sa setValue(), isReadOnly(), requiredStatus() */ void QSqlField::clear() @@ -384,7 +390,8 @@ QVariant::Type QSqlField::type() const /*! Set's the field's variant type to \a type. - \sa type() setRequiredStatus() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly() + \sa type(), setRequiredStatus(), setLength(), setPrecision(), + setDefaultValue(), setGenerated(), setReadOnly() */ void QSqlField::setType(QVariant::Type type) { @@ -399,7 +406,8 @@ void QSqlField::setType(QVariant::Type type) Returns true if the field's value is read-only; otherwise returns false. - \sa setReadOnly() type() requiredStatus() length() precision() defaultValue() isGenerated() + \sa setReadOnly(), type(), requiredStatus(), length(), precision(), + defaultValue(), isGenerated() */ bool QSqlField::isReadOnly() const { return d->ro; } @@ -424,7 +432,8 @@ void QSqlField::detach() Returns true if this is a required field; otherwise returns false. An \c INSERT will fail if a required field does not have a value. - \sa setRequiredStatus() type() length() precision() defaultValue() isGenerated() + \sa setRequiredStatus(), type(), length(), precision(), defaultValue(), + isGenerated() */ QSqlField::RequiredStatus QSqlField::requiredStatus() const { @@ -437,7 +446,8 @@ QSqlField::RequiredStatus QSqlField::requiredStatus() const If the returned value is negative, it means that the information is not available from the database. - \sa setLength() type() requiredStatus() precision() defaultValue() isGenerated() + \sa setLength(), type(), requiredStatus(), precision(), defaultValue(), + isGenerated() */ int QSqlField::length() const { @@ -451,7 +461,8 @@ int QSqlField::length() const If the returned value is negative, it means that the information is not available from the database. - \sa setPrecision() type() requiredStatus() length() defaultValue() isGenerated() + \sa setPrecision(), type(), requiredStatus(), length(), defaultValue(), + isGenerated() */ int QSqlField::precision() const { @@ -461,7 +472,8 @@ int QSqlField::precision() const /*! Returns the field's default value (which may be NULL). - \sa setDefaultValue() type() requiredStatus() length() precision() isGenerated() + \sa setDefaultValue(), type(), requiredStatus(), length(), precision(), + isGenerated() */ QVariant QSqlField::defaultValue() const { @@ -485,7 +497,8 @@ int QSqlField::typeID() const Returns true if the field is generated; otherwise returns false. - \sa setGenerated() type() requiredStatus() length() precision() defaultValue() + \sa setGenerated(), type(), requiredStatus(), length(), precision(), + defaultValue() */ bool QSqlField::isGenerated() const { @@ -522,12 +535,6 @@ QDebug operator<<(QDebug dbg, const QSqlField &f) } #endif -/*! - \fn void QSqlField::setNull() - - Use clear() instead. -*/ - /*! Returns true if the value is auto-generated by the database, for example auto-increment primary key values. diff --git a/src/sql/kernel/qsqlquery.cpp b/src/sql/kernel/qsqlquery.cpp index e21a8f4956..78631b5e5f 100644 --- a/src/sql/kernel/qsqlquery.cpp +++ b/src/sql/kernel/qsqlquery.cpp @@ -148,7 +148,7 @@ QSqlQueryPrivate::~QSqlQueryPrivate() For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 7 + \snippet sqldatabase/sqldatabase.cpp 7 To access the data returned by a query, use value(int). Each field in the data returned by a \c SELECT statement is accessed @@ -161,7 +161,7 @@ QSqlQueryPrivate::~QSqlQueryPrivate() explained below). To convert a field name into an index, use record().\l{QSqlRecord::indexOf()}{indexOf()}, for example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 8 + \snippet sqldatabase/sqldatabase.cpp 8 QSqlQuery supports prepared query execution and the binding of parameter values to placeholders. Some databases don't support @@ -190,19 +190,19 @@ QSqlQueryPrivate::~QSqlQueryPrivate() \b{Named binding using named placeholders:} - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 9 + \snippet sqldatabase/sqldatabase.cpp 9 \b{Positional binding using named placeholders:} - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 10 + \snippet sqldatabase/sqldatabase.cpp 10 \b{Binding values using positional placeholders (version 1):} - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 11 + \snippet sqldatabase/sqldatabase.cpp 11 \b{Binding values using positional placeholders (version 2):} - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 12 + \snippet sqldatabase/sqldatabase.cpp 12 \b{Binding values to a stored procedure:} @@ -210,7 +210,7 @@ QSqlQueryPrivate::~QSqlQueryPrivate() it a character through its in parameter, and taking its result in the out parameter. - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 13 + \snippet sqldatabase/sqldatabase.cpp 13 Note that unbound parameters will retain their values. @@ -343,7 +343,7 @@ bool QSqlQuery::isNull(int field) const Example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 34 + \snippet sqldatabase/sqldatabase.cpp 34 \sa isActive(), isValid(), next(), previous(), first(), last(), seek() @@ -384,7 +384,7 @@ bool QSqlQuery::exec(const QString& query) The fields are numbered from left to right using the text of the \c SELECT statement, e.g. in - \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 0 + \snippet code/src_sql_kernel_qsqlquery.cpp 0 field 0 is \c forename and field 1 is \c surname. Using \c{SELECT *} is not recommended because the order @@ -394,7 +394,7 @@ bool QSqlQuery::exec(const QString& query) exist, if the query is inactive, or if the query is positioned on an invalid record. - \sa previous() next() first() last() seek() isActive() isValid() + \sa previous(), next(), first(), last(), seek(), isActive(), isValid() */ QVariant QSqlQuery::value(int index) const @@ -411,7 +411,7 @@ QVariant QSqlQuery::value(int index) const function returns QSql::BeforeFirstRow or QSql::AfterLastRow, which are special negative values. - \sa previous() next() first() last() seek() isActive() isValid() + \sa previous(), next(), first(), last(), seek(), isActive(), isValid() */ int QSqlQuery::at() const @@ -495,7 +495,7 @@ const QSqlResult* QSqlQuery::result() const \endlist - \sa next() previous() first() last() at() isActive() isValid() + \sa next(), previous(), first(), last(), at(), isActive(), isValid() */ bool QSqlQuery::seek(int index, bool relative) { @@ -587,7 +587,7 @@ bool QSqlQuery::seek(int index, bool relative) the last record and false is returned. If the record is successfully retrieved, true is returned. - \sa previous() first() last() seek() at() isActive() isValid() + \sa previous(), first(), last(), seek(), at(), isActive(), isValid() */ bool QSqlQuery::next() { @@ -636,7 +636,7 @@ bool QSqlQuery::next() before the first record and false is returned. If the record is successfully retrieved, true is returned. - \sa next() first() last() seek() at() isActive() isValid() + \sa next(), first(), last(), seek(), at(), isActive(), isValid() */ bool QSqlQuery::previous() { @@ -671,7 +671,7 @@ bool QSqlQuery::previous() return false. Returns true if successful. If unsuccessful the query position is set to an invalid position and false is returned. - \sa next() previous() last() seek() at() isActive() isValid() + \sa next(), previous(), last(), seek(), at(), isActive(), isValid() */ bool QSqlQuery::first() { @@ -695,7 +695,7 @@ bool QSqlQuery::first() Returns true if successful. If unsuccessful the query position is set to an invalid position and false is returned. - \sa next() previous() first() seek() at() isActive() isValid() + \sa next(), previous(), first(), seek(), at(), isActive(), isValid() */ bool QSqlQuery::last() @@ -717,7 +717,7 @@ bool QSqlQuery::last() To determine the number of rows affected by a non-\c SELECT statement, use numRowsAffected(). - \sa isActive() numRowsAffected() QSqlDriver::hasFeature() + \sa isActive(), numRowsAffected(), QSqlDriver::hasFeature() */ int QSqlQuery::size() const { @@ -732,7 +732,7 @@ int QSqlQuery::size() const statements, the value is undefined; use size() instead. If the query is not \l{isActive()}{active}, -1 is returned. - \sa size() QSqlDriver::hasFeature() + \sa size(), QSqlDriver::hasFeature() */ int QSqlQuery::numRowsAffected() const @@ -850,7 +850,7 @@ void QSqlQuery::setForwardOnly(bool forward) Since the order of the columns is not defined, QSqlRecord::indexOf() is used to obtain the index of a column. - \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 1 + \snippet code/src_sql_kernel_qsqlquery.cpp 1 \sa value() */ @@ -895,7 +895,7 @@ void QSqlQuery::clear() Example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 9 + \snippet sqldatabase/sqldatabase.cpp 9 \sa exec(), bindValue(), addBindValue() */ @@ -937,7 +937,7 @@ bool QSqlQuery::prepare(const QString& query) Note that the last error for this query is reset when exec() is called. - \sa prepare() bindValue() addBindValue() boundValue() boundValues() + \sa prepare(), bindValue(), addBindValue(), boundValue(), boundValues() */ bool QSqlQuery::exec() { @@ -968,11 +968,11 @@ bool QSqlQuery::exec() Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 2 + \snippet code/src_sql_kernel_qsqlquery.cpp 2 The example above inserts four new rows into \c myTable: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 3 + \snippet code/src_sql_kernel_qsqlquery.cpp 3 To bind NULL values, a null QVariant of the relevant type has to be added to the bound QVariantList; for example, \c @@ -1021,7 +1021,7 @@ bool QSqlQuery::execBatch(BatchExecutionMode mode) \endcode Binding to name will bind to the first :name, but not the second. - \sa addBindValue(), prepare(), exec(), boundValue() boundValues() + \sa addBindValue(), prepare(), exec(), boundValue(), boundValues() */ void QSqlQuery::bindValue(const QString& placeholder, const QVariant& val, QSql::ParamType paramType @@ -1051,7 +1051,7 @@ void QSqlQuery::bindValue(int pos, const QVariant& val, QSql::ParamType paramTyp To bind a NULL value, use a null QVariant; for example, use \c {QVariant(QVariant::String)} if you are binding a string. - \sa bindValue(), prepare(), exec(), boundValue() boundValues() + \sa bindValue(), prepare(), exec(), boundValue(), boundValues() */ void QSqlQuery::addBindValue(const QVariant& val, QSql::ParamType paramType) { @@ -1061,7 +1061,7 @@ void QSqlQuery::addBindValue(const QVariant& val, QSql::ParamType paramType) /*! Returns the value for the \a placeholder. - \sa boundValues() bindValue() addBindValue() + \sa boundValues(), bindValue(), addBindValue() */ QVariant QSqlQuery::boundValue(const QString& placeholder) const { @@ -1082,13 +1082,13 @@ QVariant QSqlQuery::boundValue(int pos) const With named binding, the bound values can be examined in the following ways: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 14 + \snippet sqldatabase/sqldatabase.cpp 14 With positional binding, the code becomes: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 15 + \snippet sqldatabase/sqldatabase.cpp 15 - \sa boundValue() bindValue() addBindValue() + \sa boundValue(), bindValue(), addBindValue() */ QMap QSqlQuery::boundValues() const { @@ -1117,12 +1117,6 @@ QString QSqlQuery::executedQuery() const return d->sqlResult->executedQuery(); } -/*! - \fn bool QSqlQuery::prev() - - Use previous() instead. -*/ - /*! Returns the object ID of the most recent inserted row if the database supports it. An invalid QVariant will be returned if the @@ -1190,7 +1184,7 @@ QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const Sets the query to inactive. Bound values retain their values. - \sa prepare() exec() isActive() + \sa prepare(), exec(), isActive() */ void QSqlQuery::finish() { @@ -1230,7 +1224,8 @@ void QSqlQuery::finish() databases may have restrictions on which statements are allowed to be used in a SQL batch. - \sa QSqlDriver::hasFeature() setForwardOnly() next() isSelect() numRowsAffected() isActive() lastError() + \sa QSqlDriver::hasFeature(), setForwardOnly(), next(), isSelect(), + numRowsAffected(), isActive(), lastError() */ bool QSqlQuery::nextResult() { diff --git a/src/sql/kernel/qsqlrecord.cpp b/src/sql/kernel/qsqlrecord.cpp index 93ef58914b..4349661835 100644 --- a/src/sql/kernel/qsqlrecord.cpp +++ b/src/sql/kernel/qsqlrecord.cpp @@ -189,7 +189,7 @@ bool QSqlRecord::operator==(const QSqlRecord &other) const the record. If \a index is out of bounds, an invalid QVariant is returned. - \sa fieldName() isNull() + \sa fieldName(), isNull() */ QVariant QSqlRecord::value(int index) const @@ -264,7 +264,7 @@ QSqlField QSqlRecord::field(const QString &name) const /*! Append a copy of field \a field to the end of the record. - \sa insert() replace() remove() + \sa insert(), replace(), remove() */ void QSqlRecord::append(const QSqlField& field) @@ -276,7 +276,7 @@ void QSqlRecord::append(const QSqlField& field) /*! Inserts the field \a field at position \a pos in the record. - \sa append() replace() remove() + \sa append(), replace(), remove() */ void QSqlRecord::insert(int pos, const QSqlField& field) { @@ -288,7 +288,7 @@ void QSqlRecord::insert(int pos, const QSqlField& field) Replaces the field at position \a pos with the given \a field. If \a pos is out of range, nothing happens. - \sa append() insert() remove() + \sa append(), insert(), remove() */ void QSqlRecord::replace(int pos, const QSqlField& field) @@ -304,7 +304,7 @@ void QSqlRecord::replace(int pos, const QSqlField& field) Removes the field at position \a pos. If \a pos is out of range, nothing happens. - \sa append() insert() replace() + \sa append(), insert(), replace() */ void QSqlRecord::remove(int pos) @@ -319,7 +319,7 @@ void QSqlRecord::remove(int pos) /*! Removes all the record's fields. - \sa clearValues() isEmpty() + \sa clearValues(), isEmpty() */ void QSqlRecord::clear() @@ -332,7 +332,7 @@ void QSqlRecord::clear() Returns true if there are no fields in the record; otherwise returns false. - \sa append() insert() clear() + \sa append(), insert(), clear() */ bool QSqlRecord::isEmpty() const @@ -524,10 +524,4 @@ QDebug operator<<(QDebug dbg, const QSqlRecord &r) } #endif -/*! - \fn int QSqlRecord::position(const QString& name) const - - Use indexOf() instead. -*/ - QT_END_NAMESPACE diff --git a/src/sql/kernel/qsqlresult.cpp b/src/sql/kernel/qsqlresult.cpp index f9dbae306b..03e227bffc 100644 --- a/src/sql/kernel/qsqlresult.cpp +++ b/src/sql/kernel/qsqlresult.cpp @@ -953,7 +953,7 @@ void QSqlResult::virtual_hook(int, void *) Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp 0 + \snippet code/src_sql_kernel_qsqlresult.cpp 0 Here, we insert two rows into a SQL table, with each row containing three values. @@ -1032,11 +1032,11 @@ bool QSqlResult::nextResult() This example retrieves the handle for a sqlite result: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp 1 + \snippet code/src_sql_kernel_qsqlresult.cpp 1 This snippet returns the handle for PostgreSQL or MySQL: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp 2 + \snippet code/src_sql_kernel_qsqlresult.cpp 2 \sa QSqlDriver::handle() */ diff --git a/src/sql/models/qsqlquerymodel.cpp b/src/sql/models/qsqlquerymodel.cpp index 85869e41ac..723767344c 100644 --- a/src/sql/models/qsqlquerymodel.cpp +++ b/src/sql/models/qsqlquerymodel.cpp @@ -111,7 +111,7 @@ void QSqlQueryModelPrivate::initColOffsets(int size) the lower-level QSqlQuery and can be used to provide data to view classes such as QTableView. For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 16 + \snippet sqldatabase/sqldatabase.cpp 16 We set the model's query, then we set up the labels displayed in the view header. @@ -119,13 +119,13 @@ void QSqlQueryModelPrivate::initColOffsets(int size) QSqlQueryModel can also be used to access a database programmatically, without binding it to a view: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 21 + \snippet sqldatabase/sqldatabase.cpp 21 The code snippet above extracts the \c salary field from record 4 in the result set of the query \c{SELECT * from employee}. Assuming that \c salary is column 2, we can rewrite the last line as follows: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 22 + \snippet sqldatabase/sqldatabase.cpp 22 The model is read-only by default. To make it read-write, you must subclass it and reimplement setData() and flags(). Another @@ -179,7 +179,7 @@ QSqlQueryModel::~QSqlQueryModel() To force fetching of the entire result set, you can use the following: - \snippet doc/src/snippets/code/src_sql_models_qsqlquerymodel.cpp 0 + \snippet code/src_sql_models_qsqlquerymodel.cpp 0 \a parent should always be an invalid QModelIndex. @@ -394,7 +394,7 @@ void QSqlQueryModel::setQuery(const QSqlQuery &query) was an error setting the query. Example: - \snippet doc/src/snippets/code/src_sql_models_qsqlquerymodel.cpp 1 + \snippet code/src_sql_models_qsqlquerymodel.cpp 1 \sa query(), queryChange(), lastError() */ @@ -529,7 +529,7 @@ QSqlRecord QSqlQueryModel::record() const By default, inserted columns are empty. To fill them with data, reimplement data() and handle any inserted column separately: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 23 + \snippet sqldatabase/sqldatabase.cpp 23 \sa removeColumns() */ diff --git a/src/sql/models/qsqlrelationaldelegate.cpp b/src/sql/models/qsqlrelationaldelegate.cpp index 79e026fe57..e58c68f139 100644 --- a/src/sql/models/qsqlrelationaldelegate.cpp +++ b/src/sql/models/qsqlrelationaldelegate.cpp @@ -53,7 +53,7 @@ QT_BEGIN_NAMESPACE use the class, simply call QAbstractItemView::setItemDelegate() on the view with an instance of QSqlRelationalDelegate: - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 4 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 4 The \l{sql/relationaltablemodel}{Relational Table Model} example (shown below) illustrates how to use QSqlRelationalDelegate in diff --git a/src/sql/models/qsqlrelationaltablemodel.cpp b/src/sql/models/qsqlrelationaltablemodel.cpp index a3d45576ae..6d0304e165 100644 --- a/src/sql/models/qsqlrelationaltablemodel.cpp +++ b/src/sql/models/qsqlrelationaltablemodel.cpp @@ -340,10 +340,10 @@ void QSqlRelationalTableModelPrivate::clearCache() The following code snippet shows how the QSqlRelationalTableModel was set up: - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 0 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 0 \codeline - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 1 - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 2 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 1 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 2 The setRelation() function calls establish a relationship between two tables. The first call specifies that column 2 in table \c @@ -359,7 +359,7 @@ void QSqlRelationalTableModelPrivate::clearCache() call QAbstractItemView::setItemDelegate() on the view with an instance of QSqlRelationalDelegate: - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 4 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 4 The \l{sql/relationaltablemodel} example illustrates how to use QSqlRelationalTableModel in conjunction with @@ -486,9 +486,9 @@ bool QSqlRelationalTableModel::setData(const QModelIndex &index, const QVariant Example: - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 0 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 0 \codeline - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 1 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 1 The setRelation() call specifies that column 2 in table \c employee is a foreign key that maps with field \c id of table \c diff --git a/src/sql/models/qsqltablemodel.cpp b/src/sql/models/qsqltablemodel.cpp index 40315da204..30c3f032e0 100644 --- a/src/sql/models/qsqltablemodel.cpp +++ b/src/sql/models/qsqltablemodel.cpp @@ -213,7 +213,7 @@ QSqlRecord QSqlTableModelPrivate::primaryValues(int row) const lower-level QSqlQuery and can be used to provide data to view classes such as QTableView. For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 24 + \snippet sqldatabase/sqldatabase.cpp 24 We set the SQL table's name and the edit strategy, then we set up the labels displayed in the view header. The edit strategy @@ -224,7 +224,7 @@ QSqlRecord QSqlTableModelPrivate::primaryValues(int row) const QSqlTableModel can also be used to access a database programmatically, without binding it to a view: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 21 + \snippet sqldatabase/sqldatabase.cpp 21 The code snippet above extracts the \c salary field from record 4 in the result set of the query \c{SELECT * from employee}. diff --git a/src/sql/sql.pro b/src/sql/sql.pro index dbeed14386..e3f81f3498 100644 --- a/src/sql/sql.pro +++ b/src/sql/sql.pro @@ -21,6 +21,7 @@ DEFINES += QT_NO_CAST_FROM_ASCII PRECOMPILED_HEADER = ../corelib/global/qt_pch.h SQL_P = sql +include(doc/doc.pri) include(kernel/kernel.pri) include(drivers/drivers.pri) include(models/models.pri) -- cgit v1.2.3