From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/ntqsqlcursor.html | 761 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 761 insertions(+) create mode 100644 doc/html/ntqsqlcursor.html (limited to 'doc/html/ntqsqlcursor.html') diff --git a/doc/html/ntqsqlcursor.html b/doc/html/ntqsqlcursor.html new file mode 100644 index 000000000..aaa3ad329 --- /dev/null +++ b/doc/html/ntqsqlcursor.html @@ -0,0 +1,761 @@ + + + + + +TQSqlCursor Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQSqlCursor Class Reference
[sql module]

+ +

The TQSqlCursor class provides browsing and editing of SQL +tables and views. +More... +

#include <ntqsqlcursor.h> +

Inherits TQSqlRecord and TQSqlQuery. +

Inherited by TQSqlSelectCursor. +

List of all member functions. +

Public Members

+ +

Protected Members

+ +

Detailed Description

+ + +The TQSqlCursor class provides browsing and editing of SQL +tables and views. +

+ +

A TQSqlCursor is a database record (see TQSqlRecord) that +corresponds to a table or view within an SQL database (see TQSqlDatabase). There are two buffers in a cursor, one used for +browsing and one used for editing records. Each buffer contains a +list of fields which correspond to the fields in the table or +view. +

When positioned on a valid record, the browse buffer contains the +values of the current record's fields from the database. The edit +buffer is separate, and is used for editing existing records and +inserting new records. +

For browsing data, a cursor must first select() data from the +database. After a successful select() the cursor is active +(isActive() returns TRUE), but is initially not positioned on a +valid record (isValid() returns FALSE). To position the cursor on +a valid record, use one of the navigation functions, next(), +prev(), first(), last(), or seek(). Once positioned on a valid +record, data can be retrieved from the browse buffer using +value(). If a navigation function is not successful, it returns +FALSE, the cursor will no longer be positioned on a valid record +and the values returned by value() are undefined. +

For example: +

+ +

            TQSqlCursor cur( "staff" ); // Specify the table/view name
+            cur.select(); // We'll retrieve every record
+            while ( cur.next() ) {
+                qDebug( cur.value( "id" ).toString() + ": " +
+                        cur.value( "surname" ).toString() + " " +
+                        cur.value( "salary" ).toString() );
+            }
+
+

In the above example, a cursor is created specifying a table or +view name in the database. Then, select() is called, which can be +optionally parameterised to filter and order the records +retrieved. Each record in the cursor is retrieved using next(). +When next() returns FALSE, there are no more records to process, +and the loop terminates. +

For editing records (rows of data), a cursor contains a separate +edit buffer which is independent of the fields used when browsing. +The functions insert(), update() and del() operate on the edit +buffer. This allows the cursor to be repositioned to other +records while simultaneously maintaining a separate buffer for +edits. You can get a pointer to the edit buffer using +editBuffer(). The primeInsert(), primeUpdate() and primeDelete() +functions also return a pointer to the edit buffer and prepare it +for insert, update and delete respectively. Edit operations only +affect a single row at a time. Note that update() and del() +require that the table or view contain a primaryIndex() to ensure +that edit operations affect a unique record within the database. +

For example: +

+ +

            TQSqlCursor cur( "prices" );
+            cur.select( "id=202" );
+            if ( cur.next() ) {
+                TQSqlRecord *buffer = cur.primeUpdate();
+                double price = buffer->value( "price" ).toDouble();
+                double newprice = price * 1.05;
+                buffer->setValue( "price", newprice );
+                cur.update();
+            }
+
+

To edit an existing database record, first move to the record you +wish to update. Call primeUpdate() to get the pointer to the +cursor's edit buffer. Then use this pointer to modify the values +in the edit buffer. Finally, call update() to save the changes to +the database. The values in the edit buffer will be used to +locate the appropriate record when updating the database (see +primaryIndex()). +

Similarly, when deleting an existing database record, first move +to the record you wish to delete. Then, call primeDelete() to get +the pointer to the edit buffer. Finally, call del() to delete the +record from the database. Again, the values in the edit buffer +will be used to locate and delete the appropriate record. +

To insert a new record, call primeInsert() to get the pointer to +the edit buffer. Use this pointer to populate the edit buffer +with new values and then insert() the record into the database. +

After calling insert(), update() or del(), the cursor is no longer +positioned on a valid record and can no longer be navigated +(isValid() return FALSE). The reason for this is that any changes +made to the database will not be visible until select() is called +to refresh the cursor. You can change this behavior by passing +FALSE to insert(), update() or del() which will prevent the cursor +from becoming invalid. The edits will still not be visible when +navigating the cursor until select() is called. +

TQSqlCursor contains virtual methods which allow editing behavior +to be customized by subclasses. This allows custom cursors to be +created that encapsulate the editing behavior of a database table +for an entire application. For example, a cursor can be customized +to always auto-number primary index fields, or provide fields with +suitable default values, when inserting new records. TQSqlCursor +generates SQL statements which are sent to the database engine; +you can control which fields are included in these statements +using setGenerated(). +

Note that TQSqlCursor does not inherit from TQObject. This means +that you are responsible for destroying instances of this class +yourself. However if you create a TQSqlCursor and use it in a +TQDataTable, TQDataBrowser or a TQDataView these classes will +usually take ownership of the cursor and destroy it when they +don't need it anymore. The documentation for TQDataTable, +TQDataBrowser and TQDataView explicitly states which calls take +ownership of the cursor. +

See also Database Classes. + +

Member Type Documentation

+

TQSqlCursor::Mode

+ +

This enum type describes how TQSqlCursor operates on records in the +database. +

+

Member Function Documentation

+

TQSqlCursor::TQSqlCursor ( const TQString & name = TQString::null, bool autopopulate = TRUE, TQSqlDatabase * db = 0 ) +

+Constructs a cursor on database db using table or view name. +

If autopopulate is TRUE (the default), the name of the +cursor must correspond to an existing table or view name in the +database so that field information can be automatically created. +If the table or view does not exist, the cursor will not be +functional. +

The cursor is created with an initial mode of TQSqlCursor::Writable +(meaning that records can be inserted, updated or deleted using +the cursor). If the cursor does not have a unique primary index, +update and deletes cannot be performed. +

Note that autopopulate refers to populating the cursor with +meta-data, e.g. the names of the table's fields, not with +retrieving data. The select() function is used to populate the +cursor with data. +

See also setName() and setMode(). + +

TQSqlCursor::TQSqlCursor ( const TQSqlCursor & other ) +

+Constructs a copy of other. + +

TQSqlCursor::~TQSqlCursor () +

+Destroys the object and frees any allocated resources. + +

void TQSqlCursor::append ( const TQSqlFieldInfo & fieldInfo ) [virtual] +

+Append a copy of field fieldInfo to the end of the cursor. Note +that all references to the cursor edit buffer become invalidated. + +

TQVariant TQSqlCursor::calculateField ( const TQString & name ) [virtual protected] +

+Protected virtual function which is called whenever a field needs +to be calculated. If calculated fields are being used, derived +classes must reimplement this function and return the appropriate +value for field name. The default implementation returns an +invalid TQVariant. +

See also setCalculated(). + +

Examples: sql/overview/subclass3/main.cpp and sql/overview/subclass4/main.cpp. +

bool TQSqlCursor::canDelete () const +

+Returns TRUE if the cursor will perform deletes; otherwise returns +FALSE. +

See also setMode(). + +

bool TQSqlCursor::canInsert () const +

+Returns TRUE if the cursor will perform inserts; otherwise returns +FALSE. +

See also setMode(). + +

bool TQSqlCursor::canUpdate () const +

+Returns TRUE if the cursor will perform updates; otherwise returns +FALSE. +

See also setMode(). + +

void TQSqlCursor::clear () [virtual] +

+Removes all fields from the cursor. Note that all references to +the cursor edit buffer become invalidated. + +

Reimplemented from TQSqlRecord. +

int TQSqlCursor::del ( bool invalidate = TRUE ) [virtual] +

+Deletes a record from the database using the cursor's primary +index and the contents of the cursor edit buffer. Returns the +number of records which were deleted. +For error information, use lastError(). +

Only records which meet the filter criteria specified by the +cursor's primary index are deleted. If the cursor does not contain +a primary index, no delete is performed and 0 is returned. If invalidate is TRUE (the default), the current cursor can no longer +be navigated. A new select() call must be made before you can move +to a valid record. For example: +

+ +

            TQSqlCursor cur( "prices" );
+            cur.select( "id=999" );
+            if ( cur.next() ) {
+                cur.primeDelete();
+                cur.del();
+            }
+
+

In the above example, a cursor is created on the 'prices' table +and positioned to the record to be deleted. First primeDelete() is +called to populate the edit buffer with the current cursor values, +e.g. with an id of 999, and then del() is called to actually +delete the record from the database. Remember: all edit operations +(insert(), update() and delete()) operate on the contents of the +cursor edit buffer and not on the contents of the cursor itself. +

See also primeDelete(), setMode(), and lastError(). + +

Example: sql/overview/delete/main.cpp. +

int TQSqlCursor::del ( const TQString & filter, bool invalidate = TRUE ) [virtual protected] +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Deletes the current cursor record from the database using the +filter filter. Only records which meet the filter criteria are +deleted. Returns the number of records which were deleted. If invalidate is TRUE (the default), the current cursor can no longer +be navigated. A new select() call must be made before you can move +to a valid record. For error information, use lastError(). +

The filter is an SQL WHERE clause, e.g. id=500. +

See also setMode() and lastError(). + +

TQSqlRecord * TQSqlCursor::editBuffer ( bool copy = FALSE ) [virtual] +

+Returns the current internal edit buffer. If copy is TRUE (the +default is FALSE), the current cursor field values are first +copied into the edit buffer. The edit buffer is valid as long as +the cursor remains valid. The cursor retains ownership of the +returned pointer, so it must not be deleted or modified. +

See also primeInsert(), primeUpdate(), and primeDelete(). + +

TQString TQSqlCursor::filter () const +

+Returns the current filter, or an empty string if there is no +current filter. + +

TQSqlIndex TQSqlCursor::index ( const TQStringList & fieldNames ) const [virtual] +

+Returns an index composed of fieldNames, all in ASCending +order. Note that all field names must exist in the cursor, +otherwise an empty index is returned. +

See also TQSqlIndex. + +

Examples: sql/overview/extract/main.cpp, sql/overview/order1/main.cpp, sql/overview/order2/main.cpp, and sql/overview/table3/main.cpp. +

TQSqlIndex TQSqlCursor::index ( const TQString & fieldName ) const +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns an index based on fieldName. + +

TQSqlIndex TQSqlCursor::index ( const char * fieldName ) const +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns an index based on fieldName. + +

void TQSqlCursor::insert ( int pos, const TQSqlFieldInfo & fieldInfo ) [virtual] +

+Insert a copy of fieldInfo at position pos. If a field +already exists at pos, it is removed. Note that all references +to the cursor edit buffer become invalidated. + +

Examples: sql/overview/insert/main.cpp and sql/overview/insert2/main.cpp. +

int TQSqlCursor::insert ( bool invalidate = TRUE ) [virtual] +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Inserts the current contents of the cursor's edit record buffer +into the database, if the cursor allows inserts. Returns the +number of rows affected by the insert. For error information, use +lastError(). +

If invalidate is TRUE (the default), the cursor will no longer +be positioned on a valid record and can no longer be navigated. A +new select() call must be made before navigating to a valid +record. +

+ +

            TQSqlCursor cur( "prices" );
+            TQSqlRecord *buffer = cur.primeInsert();
+            buffer->setValue( "id",    53981 );
+            buffer->setValue( "name",  "Thingy" );
+            buffer->setValue( "price", 105.75 );
+            cur.insert();
+
+

In the above example, a cursor is created on the 'prices' table +and a pointer to the insert buffer is atquired using primeInsert(). +Each field's value is set to the desired value and then insert() +is called to insert the data into the database. Remember: all edit +operations (insert(), update() and delete()) operate on the +contents of the cursor edit buffer and not on the contents of the +cursor itself. +

See also setMode() and lastError(). + +

bool TQSqlCursor::isCalculated ( const TQString & name ) const +

+Returns TRUE if the field name exists and is calculated; +otherwise returns FALSE. +

See also setCalculated(). + +

bool TQSqlCursor::isNull ( int i ) const +

+Returns TRUE if the field i is NULL or if there is no field at +position i; otherwise returns FALSE. +

This is the same as calling TQSqlRecord::isNull( i ) + +

bool TQSqlCursor::isNull ( const TQString & name ) const +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns TRUE if the field called name is NULL or if there is no +field called name; otherwise returns FALSE. +

This is the same as calling TQSqlRecord::isNull( name ) + +

bool TQSqlCursor::isReadOnly () const +

+Returns TRUE if the cursor is read-only; otherwise returns FALSE. +The default is FALSE. Read-only cursors cannot be edited using +insert(), update() or del(). +

See also setMode(). + +

bool TQSqlCursor::isTrimmed ( const TQString & name ) const +

+Returns TRUE if the field name exists and is trimmed; otherwise +returns FALSE. +

When a trimmed field of type string or cstring is read from the +database any trailing (right-most) spaces are removed. +

See also setTrimmed(). + +

int TQSqlCursor::mode () const +

+Returns the current cursor mode. +

See also setMode(). + +

TQString TQSqlCursor::name () const +

+Returns the name of the cursor. + +

TQSqlCursor & TQSqlCursor::operator= ( const TQSqlCursor & other ) +

+Sets the cursor equal to other. + +

TQSqlIndex TQSqlCursor::primaryIndex ( bool setFromCursor = TRUE ) const [virtual] +

+Returns the primary index associated with the cursor as defined in +the database, or an empty index if there is no primary index. If +setFromCursor is TRUE (the default), the index fields are +populated with the corresponding values in the cursor's current +record. + +

TQSqlRecord * TQSqlCursor::primeDelete () [virtual] +

+This function primes the edit buffer's field values for delete and +returns the edit buffer. The default implementation copies the +field values from the current cursor record into the edit buffer +(therefore, this function is equivalent to calling editBuffer( +TRUE ) ). The cursor retains ownership of the returned pointer, so +it must not be deleted or modified. +

See also editBuffer() and del(). + +

Example: sql/overview/delete/main.cpp. +

TQSqlRecord * TQSqlCursor::primeInsert () [virtual] +

+This function primes the edit buffer's field values for insert and +returns the edit buffer. The default implementation clears all +field values in the edit buffer. The cursor retains ownership of +the returned pointer, so it must not be deleted or modified. +

See also editBuffer() and insert(). + +

Examples: sql/overview/insert/main.cpp, sql/overview/insert2/main.cpp, sql/overview/subclass5/main.cpp, and sql/sqltable/main.cpp. +

TQSqlRecord * TQSqlCursor::primeUpdate () [virtual] +

+This function primes the edit buffer's field values for update and +returns the edit buffer. The default implementation copies the +field values from the current cursor record into the edit buffer +(therefore, this function is equivalent to calling editBuffer( +TRUE ) ). The cursor retains ownership of the returned pointer, so +it must not be deleted or modified. +

See also editBuffer() and update(). + +

Examples: sql/overview/custom1/main.cpp, sql/overview/form1/main.cpp, and sql/overview/update/main.cpp. +

void TQSqlCursor::remove ( int pos ) [virtual] +

+Removes the field at pos. If pos does not exist, nothing +happens. Note that all references to the cursor edit buffer become +invalidated. + +

Reimplemented from TQSqlRecord. +

bool TQSqlCursor::select ( const TQString & filter, const TQSqlIndex & sort = TQSqlIndex ( ) ) [virtual] +

+Selects all fields in the cursor from the database matching the +filter criteria filter. The data is returned in the order +specified by the index sort. Returns TRUE if the data was +successfully selected; otherwise returns FALSE. +

The filter is a string containing a SQL WHERE clause but +without the 'WHERE' keyword. The cursor is initially positioned at +an invalid row after this function is called. To move to a valid +row, use seek(), first(), last(), prev() or next(). +

Example: +

+    TQSqlCursor cur( "Employee" ); // Use the Employee table or view
+    cur.select( "deptno=10" ); // select all records in department 10
+    while( cur.next() ) {
+        ... // process data
+    }
+    ...
+    // select records in other departments, ordered by department number
+    cur.select( "deptno>10", cur.index( "deptno" ) );
+    ...
+
+ +

The filter will apply to any subsequent select() calls that do not +explicitly specify another filter. Similarly the sort will apply +to any subsequent select() calls that do not explicitly specify +another sort. +

+    TQSqlCursor cur( "Employee" );
+    cur.select( "deptno=10" ); // select all records in department 10
+    while( cur.next() ) {
+        ... // process data
+    }
+    ...
+    cur.select(); // re-selects all records in department 10
+    ...
+
+ +

+

Examples: sql/overview/delete/main.cpp, sql/overview/extract/main.cpp, sql/overview/order1/main.cpp, sql/overview/order2/main.cpp, sql/overview/retrieve2/main.cpp, sql/overview/table3/main.cpp, and sql/overview/update/main.cpp. +

bool TQSqlCursor::select () +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Selects all fields in the cursor from the database. The rows are +returned in the order specified by the last call to setSort() or +the last call to select() that specified a sort, whichever is the +most recent. If there is no current sort, the order in which the +rows are returned is undefined. The records are filtered according +to the filter specified by the last call to setFilter() or the +last call to select() that specified a filter, whichever is the +most recent. If there is no current filter, all records are +returned. The cursor is initially positioned at an invalid row. To +move to a valid row, use seek(), first(), last(), prev() or +next(). +

See also setSort() and setFilter(). + +

bool TQSqlCursor::select ( const TQSqlIndex & sort ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Selects all fields in the cursor from the database. The data is +returned in the order specified by the index sort. The records +are filtered according to the filter specified by the last call to +setFilter() or the last call to select() that specified a filter, +whichever is the most recent. The cursor is initially positioned +at an invalid row. To move to a valid row, use seek(), first(), +last(), prev() or next(). + +

bool TQSqlCursor::select ( const TQSqlIndex & filter, const TQSqlIndex & sort ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Selects all fields in the cursor matching the filter index filter. The data is returned in the order specified by the index +sort. The filter index works by constructing a WHERE clause +using the names of the fields from the filter and their values +from the current cursor record. The cursor is initially positioned +at an invalid row. To move to a valid row, use seek(), first(), +last(), prev() or next(). This function is useful, for example, +for retrieving data based upon a table's primary index: +

+    TQSqlCursor cur( "Employee" );
+    TQSqlIndex pk = cur.primaryIndex();
+    cur.setValue( "id", 10 );
+    cur.select( pk, pk ); // generates "SELECT ... FROM Employee WHERE id=10 ORDER BY id"
+    ...
+
+ +

In this example the TQSqlIndex, pk, is used for two different +purposes. When used as the filter (first) argument, the field +names it contains are used to construct the WHERE clause, each set +to the current cursor value, WHERE id=10, in this case. When +used as the sort (second) argument the field names it contains are +used for the ORDER BY clause, ORDER BY id in this example. + +

void TQSqlCursor::setCalculated ( const TQString & name, bool calculated ) [virtual] +

+Sets field name to calculated. If the field name does not +exist, nothing happens. The value of a calculated field is set by +the calculateField() virtual function which you must reimplement +(or the field value will be an invalid TQVariant). Calculated +fields do not appear in generated SQL statements sent to the +database. +

See also calculateField() and TQSqlRecord::setGenerated(). + +

void TQSqlCursor::setFilter ( const TQString & filter ) [virtual] +

+Sets the current filter to filter. Note that no new records are +selected. To select new records, use select(). The filter will +apply to any subsequent select() calls that do not explicitly +specify a filter. +

The filter is a SQL WHERE clause without the keyword 'WHERE', +e.g. name='Dave' which will be processed by the DBMS. + +

void TQSqlCursor::setGenerated ( const TQString & name, bool generated ) [virtual] +

+Sets the generated flag for the field name to generated. If +the field does not exist, nothing happens. Only fields that have +generated set to TRUE are included in the SQL that is +generated by insert(), update() or del(). +

See also isGenerated(). + +

Reimplemented from TQSqlRecord. +

void TQSqlCursor::setGenerated ( int i, bool generated ) [virtual] +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Sets the generated flag for the field i to generated. +

See also isGenerated(). + +

Reimplemented from TQSqlRecord. +

void TQSqlCursor::setMode ( int mode ) [virtual] +

+Sets the cursor mode to mode. This value can be an OR'ed +combination of TQSqlCursor::Mode values. The default mode for a +cursor is TQSqlCursor::Writable. +

+    TQSqlCursor cur( "Employee" );
+    cur.setMode( TQSqlCursor::Writable ); // allow insert/update/delete
+    ...
+    cur.setMode( TQSqlCursor::Insert | TQSqlCursor::Update ); // allow inserts and updates only
+    ...
+    cur.setMode( TQSqlCursor::ReadOnly ); // no inserts/updates/deletes allowed
+
+
+ + +

void TQSqlCursor::setName ( const TQString & name, bool autopopulate = TRUE ) [virtual] +

+Sets the name of the cursor to name. If autopopulate is TRUE +(the default), the name must correspond to a valid table or +view name in the database. Also, note that all references to the +cursor edit buffer become invalidated when fields are +auto-populated. See the TQSqlCursor constructor documentation for +more information. + +

void TQSqlCursor::setPrimaryIndex ( const TQSqlIndex & idx ) [virtual] +

+Sets the primary index associated with the cursor to the index idx. Note that this index must contain a field or set of fields +which identify a unique record within the underlying database +table or view so that update() and del() will execute as expected. +

See also update() and del(). + +

void TQSqlCursor::setSort ( const TQSqlIndex & sort ) [virtual] +

+Sets the current sort to sort. Note that no new records are +selected. To select new records, use select(). The sort will +apply to any subsequent select() calls that do not explicitly +specify a sort. + +

void TQSqlCursor::setTrimmed ( const TQString & name, bool trim ) [virtual] +

+Sets field name's trimmed status to trim. If the field name does not exist, nothing happens. +

When a trimmed field of type string or cstring is read from the +database any trailing (right-most) spaces are removed. +

See also isTrimmed() and TQVariant. + +

TQSqlIndex TQSqlCursor::sort () const +

+Returns the current sort, or an empty index if there is no current +sort. + +

TQString TQSqlCursor::toString ( TQSqlRecord * rec, const TQString & prefix, const TQString & fieldSep, const TQString & sep ) const [virtual protected] +

+Returns a formatted string composed of all the fields in rec. +Each field is composed of the prefix (e.g. table or view name), +".", the field name, the fieldSep and the field value. If the +prefix is empty then each field will begin with the field name. +The fields are then joined together separated by sep. Fields +where isGenerated() returns FALSE are not included. This function +is useful for generating SQL statements. + +

TQString TQSqlCursor::toString ( const TQString & prefix, TQSqlField * field, const TQString & fieldSep ) const [virtual protected] +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns a formatted string composed of the prefix (e.g. table +or view name), ".", the field name, the fieldSep and the +field value. If the prefix is empty then the string will begin +with the field name. This function is useful for generating SQL +statements. + +

TQString TQSqlCursor::toString ( const TQSqlIndex & i, TQSqlRecord * rec, const TQString & prefix, const TQString & fieldSep, const TQString & sep ) const [virtual protected] +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns a formatted string composed of all the fields in the index +i. Each field is composed of the prefix (e.g. table or view +name), ".", the field name, the fieldSep and the field value. +If the prefix is empty then each field will begin with the field +name. The field values are taken from rec. The fields are then +joined together separated by sep. Fields where isGenerated() +returns FALSE are ignored. This function is useful for generating +SQL statements. + +

int TQSqlCursor::update ( bool invalidate = TRUE ) [virtual] +

+Updates the database with the current contents of the edit buffer. +Returns the number of records which were updated. +For error information, use lastError(). +

Only records which meet the filter criteria specified by the +cursor's primary index are updated. If the cursor does not contain +a primary index, no update is performed and 0 is returned. +

If invalidate is TRUE (the default), the current cursor can no +longer be navigated. A new select() call must be made before you +can move to a valid record. For example: +

+ +

            TQSqlCursor cur( "prices" );
+            cur.select( "id=202" );
+            if ( cur.next() ) {
+                TQSqlRecord *buffer = cur.primeUpdate();
+                double price = buffer->value( "price" ).toDouble();
+                double newprice = price * 1.05;
+                buffer->setValue( "price", newprice );
+                cur.update();
+            }
+
+

In the above example, a cursor is created on the 'prices' table +and is positioned on the record to be updated. Then a pointer to +the cursor's edit buffer is actquired using primeUpdate(). A new +value is calculated and placed into the edit buffer with the +setValue() call. Finally, an update() call is made on the cursor +which uses the tables's primary index to update the record in the +database with the contents of the cursor's edit buffer. Remember: +all edit operations (insert(), update() and delete()) operate on +the contents of the cursor edit buffer and not on the contents of +the cursor itself. +

Note that if the primary index does not uniquely distinguish +records the database may be changed into an inconsistent state. +

See also setMode() and lastError(). + +

Example: sql/overview/update/main.cpp. +

int TQSqlCursor::update ( const TQString & filter, bool invalidate = TRUE ) [virtual protected] +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Updates the database with the current contents of the cursor edit +buffer using the specified filter. Returns the number of +records which were updated. +For error information, use lastError(). +

Only records which meet the filter criteria are updated, otherwise +all records in the table are updated. +

If invalidate is TRUE (the default), the cursor can no longer +be navigated. A new select() call must be made before you can move +to a valid record. +

See also primeUpdate(), setMode(), and lastError(). + + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.3