1QSqlCursor(3qt)                                                QSqlCursor(3qt)
2
3
4

NAME

6       QSqlCursor - Browsing and editing of SQL tables and views
7

SYNOPSIS

9       #include <qsqlcursor.h>
10
11       Inherits QSqlRecord and QSqlQuery.
12
13       Inherited by QSqlSelectCursor.
14
15   Public Members
16       QSqlCursor ( const QString & name = QString::null, bool autopopulate =
17           TRUE, QSqlDatabase * db = 0 )
18       QSqlCursor ( const QSqlCursor & other )
19       QSqlCursor & operator= ( const QSqlCursor & other )
20       ~QSqlCursor ()
21       enum Mode { ReadOnly = 0, Insert = 1, Update = 2, Delete = 4, Writable
22           = 7 }
23       virtual QSqlIndex primaryIndex ( bool setFromCursor = TRUE ) const
24       virtual QSqlIndex index ( const QStringList & fieldNames ) const
25       QSqlIndex index ( const QString & fieldName ) const
26       QSqlIndex index ( const char * fieldName ) const
27       virtual void setPrimaryIndex ( const QSqlIndex & idx )
28       virtual void append ( const QSqlFieldInfo & fieldInfo )
29       virtual void insert ( int pos, const QSqlFieldInfo & fieldInfo )
30       virtual void remove ( int pos )
31       virtual void clear ()
32       virtual void setGenerated ( const QString & name, bool generated )
33       virtual void setGenerated ( int i, bool generated )
34       virtual QSqlRecord * editBuffer ( bool copy = FALSE )
35       virtual QSqlRecord * primeInsert ()
36       virtual QSqlRecord * primeUpdate ()
37       virtual QSqlRecord * primeDelete ()
38       virtual int insert ( bool invalidate = TRUE )
39       virtual int update ( bool invalidate = TRUE )
40       virtual int del ( bool invalidate = TRUE )
41       virtual void setMode ( int mode )
42       int mode () const
43       virtual void setCalculated ( const QString & name, bool calculated )
44       bool isCalculated ( const QString & name ) const
45       virtual void setTrimmed ( const QString & name, bool trim )
46       bool isTrimmed ( const QString & name ) const
47       bool isReadOnly () const
48       bool canInsert () const
49       bool canUpdate () const
50       bool canDelete () const
51       bool select ()
52       bool select ( const QSqlIndex & sort )
53       bool select ( const QSqlIndex & filter, const QSqlIndex & sort )
54       virtual bool select ( const QString & filter, const QSqlIndex & sort =
55           QSqlIndex ( ) )
56       virtual void setSort ( const QSqlIndex & sort )
57       QSqlIndex sort () const
58       virtual void setFilter ( const QString & filter )
59       QString filter () const
60       virtual void setName ( const QString & name, bool autopopulate = TRUE )
61       QString name () const
62       bool isNull ( int i ) const
63       bool isNull ( const QString & name ) const
64
65   Protected Members
66       virtual QVariant calculateField ( const QString & name )
67       virtual int update ( const QString & filter, bool invalidate = TRUE )
68       virtual int del ( const QString & filter, bool invalidate = TRUE )
69       virtual QString toString ( const QString & prefix, QSqlField * field,
70           const QString & fieldSep ) const
71       virtual QString toString ( QSqlRecord * rec, const QString & prefix,
72           const QString & fieldSep, const QString & sep ) const
73       virtual QString toString ( const QSqlIndex & i, QSqlRecord * rec, const
74           QString & prefix, const QString & fieldSep, const QString & sep )
75           const
76

DESCRIPTION

78       The QSqlCursor class provides browsing and editing of SQL tables and
79       views.
80
81       A QSqlCursor is a database record (see QSqlRecord) that corresponds to
82       a table or view within an SQL database (see QSqlDatabase). There are
83       two buffers in a cursor, one used for browsing and one used for editing
84       records. Each buffer contains a list of fields which correspond to the
85       fields in the table or view.
86
87       When positioned on a valid record, the browse buffer contains the
88       values of the current record's fields from the database. The edit
89       buffer is separate, and is used for editing existing records and
90       inserting new records.
91
92       For browsing data, a cursor must first select() data from the database.
93       After a successful select() the cursor is active (isActive() returns
94       TRUE), but is initially not positioned on a valid record (isValid()
95       returns FALSE). To position the cursor on a valid record, use one of
96       the navigation functions, next(), prev(), first(), last(), or seek().
97       Once positioned on a valid record, data can be retrieved from the
98       browse buffer using value(). If a navigation function is not
99       successful, it returns FALSE, the cursor will no longer be positioned
100       on a valid record and the values returned by value() are undefined.
101
102       For example:
103
104                   QSqlCursor cur( "staff" ); // Specify the table/view name
105                   cur.select(); // We'll retrieve every record
106                   while ( cur.next() ) {
107                       qDebug( cur.value( "id" ).toString() + ": " +
108                               cur.value( "surname" ).toString() + " " +
109                               cur.value( "salary" ).toString() );
110                   }
111
112       In the above example, a cursor is created specifying a table or view
113       name in the database. Then, select() is called, which can be optionally
114       parameterised to filter and order the records retrieved. Each record in
115       the cursor is retrieved using next(). When next() returns FALSE, there
116       are no more records to process, and the loop terminates.
117
118       For editing records (rows of data), a cursor contains a separate edit
119       buffer which is independent of the fields used when browsing. The
120       functions insert(), update() and del() operate on the edit buffer. This
121       allows the cursor to be repositioned to other records while
122       simultaneously maintaining a separate buffer for edits. You can get a
123       pointer to the edit buffer using editBuffer(). The primeInsert(),
124       primeUpdate() and primeDelete() functions also return a pointer to the
125       edit buffer and prepare it for insert, update and delete respectively.
126       Edit operations only affect a single row at a time. Note that update()
127       and del() require that the table or view contain a primaryIndex() to
128       ensure that edit operations affect a unique record within the database.
129
130       For example:
131
132                   QSqlCursor cur( "prices" );
133                   cur.select( "id=202" );
134                   if ( cur.next() ) {
135                       QSqlRecord *buffer = cur.primeUpdate();
136                       double price = buffer->value( "price" ).toDouble();
137                       double newprice = price * 1.05;
138                       buffer->setValue( "price", newprice );
139                       cur.update();
140                   }
141
142       To edit an existing database record, first move to the record you wish
143       to update. Call primeUpdate() to get the pointer to the cursor's edit
144       buffer. Then use this pointer to modify the values in the edit buffer.
145       Finally, call update() to save the changes to the database. The values
146       in the edit buffer will be used to locate the appropriate record when
147       updating the database (see primaryIndex()).
148
149       Similarly, when deleting an existing database record, first move to the
150       record you wish to delete. Then, call primeDelete() to get the pointer
151       to the edit buffer. Finally, call del() to delete the record from the
152       database. Again, the values in the edit buffer will be used to locate
153       and delete the appropriate record.
154
155       To insert a new record, call primeInsert() to get the pointer to the
156       edit buffer. Use this pointer to populate the edit buffer with new
157       values and then insert() the record into the database.
158
159       After calling insert(), update() or del(), the cursor is no longer
160       positioned on a valid record and can no longer be navigated (isValid()
161       return FALSE). The reason for this is that any changes made to the
162       database will not be visible until select() is called to refresh the
163       cursor. You can change this behavior by passing FALSE to insert(),
164       update() or del() which will prevent the cursor from becoming invalid.
165       The edits will still not be visible when navigating the cursor until
166       select() is called.
167
168       QSqlCursor contains virtual methods which allow editing behavior to be
169       customized by subclasses. This allows custom cursors to be created that
170       encapsulate the editing behavior of a database table for an entire
171       application. For example, a cursor can be customized to always auto-
172       number primary index fields, or provide fields with suitable default
173       values, when inserting new records. QSqlCursor generates SQL statements
174       which are sent to the database engine; you can control which fields are
175       included in these statements using setGenerated().
176
177       Note that QSqlCursor does not inherit from QObject. This means that you
178       are responsible for destroying instances of this class yourself.
179       However if you create a QSqlCursor and use it in a QDataTable,
180       QDataBrowser or a QDataView these classes will usually take ownership
181       of the cursor and destroy it when they don't need it anymore. The
182       documentation for QDataTable, QDataBrowser and QDataView explicitly
183       states which calls take ownership of the cursor.
184
185       See also Database Classes.
186
187   Member Type Documentation

QSqlCursor::Mode

189       This enum type describes how QSqlCursor operates on records in the
190       database.
191
192       QSqlCursor::ReadOnly - the cursor can only SELECT records from the
193       database.
194
195       QSqlCursor::Insert - the cursor can INSERT records into the database.
196
197       QSqlCursor::Update - the cursor can UPDATE records in the database.
198
199       QSqlCursor::Delete - the cursor can DELETE records from the database.
200
201       QSqlCursor::Writable - the cursor can INSERT, UPDATE and DELETE records
202       in the database.
203

MEMBER FUNCTION DOCUMENTATION

QSqlCursor::QSqlCursor ( const QString & name = QString::null, bool

206       autopopulate = TRUE, QSqlDatabase * db = 0 )
207       Constructs a cursor on database db using table or view name.
208
209       If autopopulate is TRUE (the default), the name of the cursor must
210       correspond to an existing table or view name in the database so that
211       field information can be automatically created. If the table or view
212       does not exist, the cursor will not be functional.
213
214       The cursor is created with an initial mode of QSqlCursor::Writable
215       (meaning that records can be inserted, updated or deleted using the
216       cursor). If the cursor does not have a unique primary index, update and
217       deletes cannot be performed.
218
219       Note that autopopulate refers to populating the cursor with meta-data,
220       e.g. the names of the table's fields, not with retrieving data. The
221       select() function is used to populate the cursor with data.
222
223       See also setName() and setMode().
224

QSqlCursor::QSqlCursor ( const QSqlCursor & other )

226       Constructs a copy of other.
227

QSqlCursor::~QSqlCursor ()

229       Destroys the object and frees any allocated resources.
230

void QSqlCursor::append ( const QSqlFieldInfo & fieldInfo ) [virtual]

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

QVariant QSqlCursor::calculateField ( const QString & name ) [virtual

236       protected]
237       Protected virtual function which is called whenever a field needs to be
238       calculated. If calculated fields are being used, derived classes must
239       reimplement this function and return the appropriate value for field
240       name. The default implementation returns an invalid QVariant.
241
242       See also setCalculated().
243
244       Examples:
245

bool QSqlCursor::canDelete () const

247       Returns TRUE if the cursor will perform deletes; otherwise returns
248       FALSE.
249
250       See also setMode().
251

bool QSqlCursor::canInsert () const

253       Returns TRUE if the cursor will perform inserts; otherwise returns
254       FALSE.
255
256       See also setMode().
257

bool QSqlCursor::canUpdate () const

259       Returns TRUE if the cursor will perform updates; otherwise returns
260       FALSE.
261
262       See also setMode().
263

void QSqlCursor::clear () [virtual]

265       Removes all fields from the cursor. Note that all references to the
266       cursor edit buffer become invalidated.
267
268       Reimplemented from QSqlRecord.
269

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

271       Deletes a record from the database using the cursor's primary index and
272       the contents of the cursor edit buffer. Returns the number of records
273       which were deleted. For error information, use lastError().
274
275       Only records which meet the filter criteria specified by the cursor's
276       primary index are deleted. If the cursor does not contain a primary
277       index, no delete is performed and 0 is returned. If invalidate is TRUE
278       (the default), the current cursor can no longer be navigated. A new
279       select() call must be made before you can move to a valid record. For
280       example:
281
282                   QSqlCursor cur( "prices" );
283                   cur.select( "id=999" );
284                   if ( cur.next() ) {
285                       cur.primeDelete();
286                       cur.del();
287                   }
288
289       In the above example, a cursor is created on the 'prices' table and
290       positioned to the record to be deleted. First primeDelete() is called
291       to populate the edit buffer with the current cursor values, e.g. with
292       an id of 999, and then del() is called to actually delete the record
293       from the database. Remember: all edit operations (insert(), update()
294       and delete()) operate on the contents of the cursor edit buffer and not
295       on the contents of the cursor itself.
296
297       See also primeDelete(), setMode(), and lastError().
298
299       Example: sql/overview/delete/main.cpp.
300

int QSqlCursor::del ( const QString & filter, bool invalidate = TRUE )

302       [virtual protected]
303       This is an overloaded member function, provided for convenience. It
304       behaves essentially like the above function.
305
306       Deletes the current cursor record from the database using the filter
307       filter. Only records which meet the filter criteria are deleted.
308       Returns the number of records which were deleted. If invalidate is TRUE
309       (the default), the current cursor can no longer be navigated. A new
310       select() call must be made before you can move to a valid record. For
311       error information, use lastError().
312
313       The filter is an SQL WHERE clause, e.g. id=500.
314
315       See also setMode() and lastError().
316

QSqlRecord * QSqlCursor::editBuffer ( bool copy = FALSE ) [virtual]

318       Returns the current internal edit buffer. If copy is TRUE (the default
319       is FALSE), the current cursor field values are first copied into the
320       edit buffer. The edit buffer is valid as long as the cursor remains
321       valid. The cursor retains ownership of the returned pointer, so it must
322       not be deleted or modified.
323
324       See also primeInsert(), primeUpdate(), and primeDelete().
325

QString QSqlCursor::filter () const

327       Returns the current filter, or an empty string if there is no current
328       filter.
329

QSqlIndex QSqlCursor::index ( const QStringList & fieldNames ) const [virtual]

331
332       Returns an index composed of fieldNames, all in ASCending order. Note
333       that all field names must exist in the cursor, otherwise an empty index
334       is returned.
335
336       See also QSqlIndex.
337
338       Examples:
339

QSqlIndex QSqlCursor::index ( const QString & fieldName ) const

341       This is an overloaded member function, provided for convenience. It
342       behaves essentially like the above function.
343
344       Returns an index based on fieldName.
345

QSqlIndex QSqlCursor::index ( const char * fieldName ) const

347       This is an overloaded member function, provided for convenience. It
348       behaves essentially like the above function.
349
350       Returns an index based on fieldName.
351

void QSqlCursor::insert ( int pos, const QSqlFieldInfo & fieldInfo ) [virtual]

353
354       Insert a copy of fieldInfo at position pos. If a field already exists
355       at pos, it is removed. Note that all references to the cursor edit
356       buffer become invalidated.
357
358       Examples:
359

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

361       This is an overloaded member function, provided for convenience. It
362       behaves essentially like the above function.
363
364       Inserts the current contents of the cursor's edit record buffer into
365       the database, if the cursor allows inserts. Returns the number of rows
366       affected by the insert. For error information, use lastError().
367
368       If invalidate is TRUE (the default), the cursor will no longer be
369       positioned on a valid record and can no longer be navigated. A new
370       select() call must be made before navigating to a valid record.
371
372                   QSqlCursor cur( "prices" );
373                   QSqlRecord *buffer = cur.primeInsert();
374                   buffer->setValue( "id",    53981 );
375                   buffer->setValue( "name",  "Thingy" );
376                   buffer->setValue( "price", 105.75 );
377                   cur.insert();
378
379       In the above example, a cursor is created on the 'prices' table and a
380       pointer to the insert buffer is aquired using primeInsert(). Each
381       field's value is set to the desired value and then insert() is called
382       to insert the data into the database. Remember: all edit operations
383       (insert(), update() and delete()) operate on the contents of the cursor
384       edit buffer and not on the contents of the cursor itself.
385
386       See also setMode() and lastError().
387

bool QSqlCursor::isCalculated ( const QString & name ) const

389       Returns TRUE if the field name exists and is calculated; otherwise
390       returns FALSE.
391
392       See also setCalculated().
393

bool QSqlCursor::isNull ( int i ) const

395       Returns TRUE if the field i is NULL or if there is no field at position
396       i; otherwise returns FALSE.
397
398       This is the same as calling QSqlRecord::isNull( i )
399

bool QSqlCursor::isNull ( const QString & name ) const

401       This is an overloaded member function, provided for convenience. It
402       behaves essentially like the above function.
403
404       Returns TRUE if the field called name is NULL or if there is no field
405       called name; otherwise returns FALSE.
406
407       This is the same as calling QSqlRecord::isNull( name )
408

bool QSqlCursor::isReadOnly () const

410       Returns TRUE if the cursor is read-only; otherwise returns FALSE. The
411       default is FALSE. Read-only cursors cannot be edited using insert(),
412       update() or del().
413
414       See also setMode().
415

bool QSqlCursor::isTrimmed ( const QString & name ) const

417       Returns TRUE if the field name exists and is trimmed; otherwise returns
418       FALSE.
419
420       When a trimmed field of type string or cstring is read from the
421       database any trailing (right-most) spaces are removed.
422
423       See also setTrimmed().
424

int QSqlCursor::mode () const

426       Returns the current cursor mode.
427
428       See also setMode().
429

QString QSqlCursor::name () const

431       Returns the name of the cursor.
432

QSqlCursor & QSqlCursor::operator= ( const QSqlCursor & other )

434       Sets the cursor equal to other.
435

QSqlIndex QSqlCursor::primaryIndex ( bool setFromCursor = TRUE ) const

437       [virtual]
438       Returns the primary index associated with the cursor as defined in the
439       database, or an empty index if there is no primary index. If
440       setFromCursor is TRUE (the default), the index fields are populated
441       with the corresponding values in the cursor's current record.
442

QSqlRecord * QSqlCursor::primeDelete () [virtual]

444       This function primes the edit buffer's field values for delete and
445       returns the edit buffer. The default implementation copies the field
446       values from the current cursor record into the edit buffer (therefore,
447       this function is equivalent to calling editBuffer( TRUE ) ). The cursor
448       retains ownership of the returned pointer, so it must not be deleted or
449       modified.
450
451       See also editBuffer() and del().
452
453       Example: sql/overview/delete/main.cpp.
454

QSqlRecord * QSqlCursor::primeInsert () [virtual]

456       This function primes the edit buffer's field values for insert and
457       returns the edit buffer. The default implementation clears all field
458       values in the edit buffer. The cursor retains ownership of the returned
459       pointer, so it must not be deleted or modified.
460
461       See also editBuffer() and insert().
462
463       Examples:
464

QSqlRecord * QSqlCursor::primeUpdate () [virtual]

466       This function primes the edit buffer's field values for update and
467       returns the edit buffer. The default implementation copies the field
468       values from the current cursor record into the edit buffer (therefore,
469       this function is equivalent to calling editBuffer( TRUE ) ). The cursor
470       retains ownership of the returned pointer, so it must not be deleted or
471       modified.
472
473       See also editBuffer() and update().
474
475       Examples:
476

void QSqlCursor::remove ( int pos ) [virtual]

478       Removes the field at pos. If pos does not exist, nothing happens. Note
479       that all references to the cursor edit buffer become invalidated.
480
481       Reimplemented from QSqlRecord.
482

bool QSqlCursor::select ( const QString & filter, const QSqlIndex & sort =

484       QSqlIndex ( ) ) [virtual]
485       Selects all fields in the cursor from the database matching the filter
486       criteria filter. The data is returned in the order specified by the
487       index sort. Returns TRUE if the data was successfully selected;
488       otherwise returns FALSE.
489
490       The filter is a string containing a SQL WHERE clause but without the
491       'WHERE' keyword. The cursor is initially positioned at an invalid row
492       after this function is called. To move to a valid row, use seek(),
493       first(), last(), prev() or next().
494
495       Example:
496
497           QSqlCursor cur( "Employee" ); // Use the Employee table or view
498           cur.select( "deptno=10" ); // select all records in department 10
499           while( cur.next() ) {
500               ... // process data
501           }
502           ...
503           // select records in other departments, ordered by department number
504           cur.select( "deptno>10", cur.index( "deptno" ) );
505           ...
506
507       The filter will apply to any subsequent select() calls that do not
508       explicitly specify another filter. Similarly the sort will apply to any
509       subsequent select() calls that do not explicitly specify another sort.
510
511           QSqlCursor cur( "Employee" );
512           cur.select( "deptno=10" ); // select all records in department 10
513           while( cur.next() ) {
514               ... // process data
515           }
516           ...
517           cur.select(); // re-selects all records in department 10
518           ...
519
520       Examples:
521

bool QSqlCursor::select ()

523       This is an overloaded member function, provided for convenience. It
524       behaves essentially like the above function.
525
526       Selects all fields in the cursor from the database. The rows are
527       returned in the order specified by the last call to setSort() or the
528       last call to select() that specified a sort, whichever is the most
529       recent. If there is no current sort, the order in which the rows are
530       returned is undefined. The records are filtered according to the filter
531       specified by the last call to setFilter() or the last call to select()
532       that specified a filter, whichever is the most recent. If there is no
533       current filter, all records are returned. The cursor is initially
534       positioned at an invalid row. To move to a valid row, use seek(),
535       first(), last(), prev() or next().
536
537       See also setSort() and setFilter().
538

bool QSqlCursor::select ( const QSqlIndex & sort )

540       This is an overloaded member function, provided for convenience. It
541       behaves essentially like the above function.
542
543       Selects all fields in the cursor from the database. The data is
544       returned in the order specified by the index sort. The records are
545       filtered according to the filter specified by the last call to
546       setFilter() or the last call to select() that specified a filter,
547       whichever is the most recent. The cursor is initially positioned at an
548       invalid row. To move to a valid row, use seek(), first(), last(),
549       prev() or next().
550

bool QSqlCursor::select ( const QSqlIndex & filter, const QSqlIndex & sort )

552       This is an overloaded member function, provided for convenience. It
553       behaves essentially like the above function.
554
555       Selects all fields in the cursor matching the filter index filter. The
556       data is returned in the order specified by the index sort. The filter
557       index works by constructing a WHERE clause using the names of the
558       fields from the filter and their values from the current cursor record.
559       The cursor is initially positioned at an invalid row. To move to a
560       valid row, use seek(), first(), last(), prev() or next(). This function
561       is useful, for example, for retrieving data based upon a table's
562       primary index:
563
564           QSqlCursor cur( "Employee" );
565           QSqlIndex pk = cur.primaryIndex();
566           cur.setValue( "id", 10 );
567           cur.select( pk, pk ); // generates "SELECT ... FROM Employee WHERE id=10 ORDER BY id"
568           ...
569
570       In this example the QSqlIndex, pk, is used for two different purposes.
571       When used as the filter (first) argument, the field names it contains
572       are used to construct the WHERE clause, each set to the current cursor
573       value, WHERE id=10, in this case. When used as the sort (second)
574       argument the field names it contains are used for the ORDER BY clause,
575       ORDER BY id in this example.
576

void QSqlCursor::setCalculated ( const QString & name, bool calculated )

578       [virtual]
579       Sets field name to calculated. If the field name does not exist,
580       nothing happens. The value of a calculated field is set by the
581       calculateField() virtual function which you must reimplement (or the
582       field value will be an invalid QVariant). Calculated fields do not
583       appear in generated SQL statements sent to the database.
584
585       See also calculateField() and QSqlRecord::setGenerated().
586

void QSqlCursor::setFilter ( const QString & filter ) [virtual]

588       Sets the current filter to filter. Note that no new records are
589       selected. To select new records, use select(). The filter will apply to
590       any subsequent select() calls that do not explicitly specify a filter.
591
592       The filter is a SQL WHERE clause without the keyword 'WHERE', e.g.
593       name='Dave' which will be processed by the DBMS.
594

void QSqlCursor::setGenerated ( const QString & name, bool generated )

596       [virtual]
597       Sets the generated flag for the field name to generated. If the field
598       does not exist, nothing happens. Only fields that have generated set to
599       TRUE are included in the SQL that is generated by insert(), update() or
600       del().
601
602       See also isGenerated().
603
604       Reimplemented from QSqlRecord.
605

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

607       This is an overloaded member function, provided for convenience. It
608       behaves essentially like the above function.
609
610       Sets the generated flag for the field i to generated.
611
612       See also isGenerated().
613
614       Reimplemented from QSqlRecord.
615

void QSqlCursor::setMode ( int mode ) [virtual]

617       Sets the cursor mode to mode. This value can be an OR'ed combination of
618       QSqlCursor::Mode values. The default mode for a cursor is
619       QSqlCursor::Writable.
620
621           QSqlCursor cur( "Employee" );
622           cur.setMode( QSqlCursor::Writable ); // allow insert/update/delete
623           ...
624           cur.setMode( QSqlCursor::Insert | QSqlCursor::Update ); // allow inserts and updates only
625           ...
626           cur.setMode( QSqlCursor::ReadOnly ); // no inserts/updates/deletes allowed
627

void QSqlCursor::setName ( const QString & name, bool autopopulate = TRUE )

629       [virtual]
630       Sets the name of the cursor to name. If autopopulate is TRUE (the
631       default), the name must correspond to a valid table or view name in the
632       database. Also, note that all references to the cursor edit buffer
633       become invalidated when fields are auto-populated. See the QSqlCursor
634       constructor documentation for more information.
635

void QSqlCursor::setPrimaryIndex ( const QSqlIndex & idx ) [virtual]

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

void QSqlCursor::setSort ( const QSqlIndex & sort ) [virtual]

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

void QSqlCursor::setTrimmed ( const QString & name, bool trim ) [virtual]

650       Sets field name's trimmed status to trim. If the field name does not
651       exist, nothing happens.
652
653       When a trimmed field of type string or cstring is read from the
654       database any trailing (right-most) spaces are removed.
655
656       See also isTrimmed() and QVariant.
657

QSqlIndex QSqlCursor::sort () const

659       Returns the current sort, or an empty index if there is no current
660       sort.
661

QString QSqlCursor::toString ( QSqlRecord * rec, const QString & prefix, const

663       QString & fieldSep, const QString & sep ) const [virtual protected]
664       Returns a formatted string composed of all the fields in rec. Each
665       field is composed of the prefix (e.g. table or view name)," prefix is
666       empty then each field will begin with the field name. The fields are
667       then joined together separated by sep. Fields where isGenerated()
668       returns FALSE are not included. This function is useful for generating
669       SQL statements.
670

QString QSqlCursor::toString ( const QString & prefix, QSqlField * field,

672       const QString & fieldSep ) const [virtual protected]
673       This is an overloaded member function, provided for convenience. It
674       behaves essentially like the above function.
675
676       Returns a formatted string composed of the prefix (e.g. table or view
677       name), ".", the field name, the fieldSep and the field value. If the
678       prefix is empty then the string will begin with the field name. This
679       function is useful for generating SQL statements.
680

QString QSqlCursor::toString ( const QSqlIndex & i, QSqlRecord * rec, const

682       QString & prefix, const QString & fieldSep, const QString & sep ) const
683       [virtual protected]
684       This is an overloaded member function, provided for convenience. It
685       behaves essentially like the above function.
686
687       Returns a formatted string composed of all the fields in the index i.
688       Each field is composed of the prefix (e.g. table or view name), ".",
689       the field name, the fieldSep and the field value. If the prefix is
690       empty then each field will begin with the field name. The field values
691       are taken from rec. The fields are then joined together separated by
692       sep. Fields where isGenerated() returns FALSE are ignored. This
693       function is useful for generating SQL statements.
694

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

696       Updates the database with the current contents of the edit buffer.
697       Returns the number of records which were updated. For error
698       information, use lastError().
699
700       Only records which meet the filter criteria specified by the cursor's
701       primary index are updated. If the cursor does not contain a primary
702       index, no update is performed and 0 is returned.
703
704       If invalidate is TRUE (the default), the current cursor can no longer
705       be navigated. A new select() call must be made before you can move to a
706       valid record. For example:
707
708                   QSqlCursor cur( "prices" );
709                   cur.select( "id=202" );
710                   if ( cur.next() ) {
711                       QSqlRecord *buffer = cur.primeUpdate();
712                       double price = buffer->value( "price" ).toDouble();
713                       double newprice = price * 1.05;
714                       buffer->setValue( "price", newprice );
715                       cur.update();
716                   }
717
718       In the above example, a cursor is created on the 'prices' table and is
719       positioned on the record to be updated. Then a pointer to the cursor's
720       edit buffer is acquired using primeUpdate(). A new value is calculated
721       and placed into the edit buffer with the setValue() call. Finally, an
722       update() call is made on the cursor which uses the tables's primary
723       index to update the record in the database with the contents of the
724       cursor's edit buffer. Remember: all edit operations (insert(), update()
725       and delete()) operate on the contents of the cursor edit buffer and not
726       on the contents of the cursor itself.
727
728       Note that if the primary index does not uniquely distinguish records
729       the database may be changed into an inconsistent state.
730
731       See also setMode() and lastError().
732
733       Example: sql/overview/update/main.cpp.
734

int QSqlCursor::update ( const QString & filter, bool invalidate = TRUE )

736       [virtual protected]
737       This is an overloaded member function, provided for convenience. It
738       behaves essentially like the above function.
739
740       Updates the database with the current contents of the cursor edit
741       buffer using the specified filter. Returns the number of records which
742       were updated. For error information, use lastError().
743
744       Only records which meet the filter criteria are updated, otherwise all
745       records in the table are updated.
746
747       If invalidate is TRUE (the default), the cursor can no longer be
748       navigated. A new select() call must be made before you can move to a
749       valid record.
750
751       See also primeUpdate(), setMode(), and lastError().
752
753

SEE ALSO

755       http://doc.trolltech.com/qsqlcursor.html
756       http://www.trolltech.com/faq/tech.html
757
759       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
760       license file included in the distribution for a complete license
761       statement.
762

AUTHOR

764       Generated automatically from the source code.
765

BUGS

767       If you find a bug in Qt, please report it as described in
768       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
769       help you. Thank you.
770
771       The definitive Qt documentation is provided in HTML format; it is
772       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
773       web browser. This man page is provided as a convenience for those users
774       who prefer man pages, although this format is not officially supported
775       by Trolltech.
776
777       If you find errors in this manual page, please report them to qt-
778       bugs@trolltech.com.  Please include the name of the manual page
779       (qsqlcursor.3qt) and the Qt version (3.3.8).
780
781
782
783Trolltech AS                    2 February 2007                QSqlCursor(3qt)
Impressum