docs/latex/wx/recrdset.tex

   1 \section{\class{wxRecordSet}}\label{wxrecordset}
   2
   3 Each wxRecordSet represents an ODBC database query. You can make multiple queries
   4 at a time by using multiple wxRecordSets with a wxDatabase or you can make
   5 your queries in sequential order using the same wxRecordSet.
   6
   7 \wxheading{Derivation}
   8
   9 \helpref{wxObject}{wxobject}
  10
  11 \wxheading{See also}
  12
  13 \helpref{wxRecordSet overview}{wxrecordsetoverview}, \helpref{wxDatabase overview}{wxdatabaseoverview}
  14
  15 \latexignore{\rtfignore{\wxheading{Members}}}
  16
  17 \membersection{wxRecordSet::wxRecordSet}
  18
  19 \func{}{wxRecordSet}{\param{wxDatabase *}{db}, \param{int}{ type = wxOPEN\_TYPE\_DYNASET},
  20  \param{int}{ opt = wxOPTION\_DEFAULT}}
  21
  22 Constructor. {\it db} is a pointer to the wxDatabase instance you wish to use the
  23 wxRecordSet with. Currently there are two possible values of {\it type}:
  24
  25 \begin{itemize}\itemsep=0pt
  26 \item wxOPEN\_TYPE\_DYNASET: Loads only one record at a time into memory. The other
  27 data of the result set will be loaded dynamically when
  28 moving the cursor. This is the default type.
  29 \item wxOPEN\_TYPE\_SNAPSHOT: Loads all records of a result set at once. This will
  30 need much more memory, but will result in
  31 faster access to the ODBC data.
  32 \end{itemize}
  33
  34 The {\it option} parameter is not used yet.
  35
  36 The constructor appends the wxRecordSet object to the parent database's list of
  37 wxRecordSet objects, for later destruction when the wxDatabase is destroyed.
  38
  39 \membersection{wxRecordSet::\destruct{wxRecordSet}}
  40
  41 \func{}{\destruct{wxRecordSet}}{\void}
  42
  43 Destructor. All data except that stored in user-defined variables will be lost.
  44 It also unlinks the wxRecordSet object from the parent database's list of
  45 wxRecordSet objects.
  46
  47 \membersection{wxRecordSet::AddNew}
  48
  49 \func{void}{AddNew}{\void}
  50
  51 Not implemented.
  52
  53 \membersection{wxRecordSet::BeginQuery}
  54
  55 \func{bool}{BeginQuery}{\param{int}{ openType}, \param{const wxString\& }{sql = NULL}, \param{int}{ options = wxOPTION\_DEFAULT}}
  56
  57 Not implemented.
  58
  59 \membersection{wxRecordSet::BindVar}
  60
  61 \func{void *}{BindVar}{\param{int}{ col}, \param{void *}{buf}, \param{long}{ size}}
  62
  63 Binds a user-defined variable to the column col. Whenever the current field's
  64 data changes, it will be copied into buf (maximum {\it size} bytes).
  65
  66 \func{void *}{BindVar}{\param{const wxString\& }{col}, \param{void *}{buf}, \param{long}{ size}}
  67
  68 The same as above, but uses the column name as the identifier.
  69
  70 \membersection{wxRecordSet::CanAppend}
  71
  72 \func{bool}{CanAppend}{\void}
  73
  74 Not implemented.
  75
  76 \membersection{wxRecordSet::Cancel}
  77
  78 \func{void}{Cancel}{\void}
  79
  80 Not implemented.
  81
  82 \membersection{wxRecordSet::CanRestart}
  83
  84 \func{bool}{CanRestart}{\void}
  85
  86 Not implemented.
  87
  88 \membersection{wxRecordSet::CanScroll}
  89
  90 \func{bool}{CanScroll}{\void}
  91
  92 Not implemented.
  93
  94 \membersection{wxRecordSet::CanTransact}
  95
  96 \func{bool}{CanTransact}{\void}
  97
  98 Not implemented.
  99
 100 \membersection{wxRecordSet::CanUpdate}
 101
 102 \func{bool}{CanUpdate}{\void}
 103
 104 Not implemented.
 105
 106 \membersection{wxRecordSet::ConstructDefaultSQL}
 107
 108 \func{bool}{ConstructDefaultSQL}{\void}
 109
 110 Not implemented.
 111
 112 \membersection{wxRecordSet::Delete}
 113
 114 \func{bool}{Delete}{\void}
 115
 116 Deletes the current record. Not implemented.
 117
 118 \membersection{wxRecordSet::Edit}
 119
 120 \func{void}{Edit}{\void}
 121
 122 Not implemented.
 123
 124 \membersection{wxRecordSet::EndQuery}
 125
 126 \func{bool}{EndQuery}{\void}
 127
 128 Not implemented.
 129
 130 \membersection{wxRecordSet::ExecuteSQL}\label{wxrecordsetexecutesql}
 131
 132 \func{bool}{ExecuteSQL}{\param{const wxString\& }{sql}}
 133
 134 Directly executes a SQL statement. The data will be presented as a normal
 135 result set. Note that the recordset must have been created as a snapshot, not
 136 dynaset. Dynasets will be implemented in the near future.
 137
 138 Examples of common SQL statements are given in \helpref{A selection of SQL commands}{sqlcommands}.
 139
 140 \membersection{wxRecordSet::FillVars}
 141
 142 \func{void}{FillVars}{\param{int}{ recnum}}
 143
 144 Fills in the user-defined variables of the columns. You can set these
 145 variables with wxQueryCol::BindVar. This function will be automatically
 146 called after every successful database operation.
 147
 148 \membersection{wxRecordSet::GetColName}
 149
 150 \func{wxString}{GetColName}{\param{int}{ col}}
 151
 152 Returns the name of the column at position {\it col}. Returns NULL if {\it col} does not
 153 exist.
 154
 155 \membersection{wxRecordSet::GetColType}
 156
 157 \func{short}{GetColType}{\param{int}{ col}}
 158
 159 Returns the data type of the column at position {\it col}. Returns SQL\_TYPE\_NULL
 160 if {\it col} does not exist.
 161
 162 \func{short}{GetColType}{\param{const wxString\& }{ name}}
 163
 164 The same as above, but uses the column name as the identifier.
 165
 166 See \helpref{ODBC SQL data types}{sqltypes} for a list
 167 of possible data types.
 168
 169 \membersection{wxRecordSet::GetColumns}
 170
 171 \func{bool}{GetColumns}{\param{const wxString\& }{table = NULL}}
 172
 173 Returns the columns of the table with the specified name. If no name is
 174 given the class member {\it tablename} will be used. If both names are NULL
 175 nothing will happen. The data will be presented as a normal result set, organized
 176 as follows:
 177
 178 \begin{twocollist}\itemsep=0pt
 179 \twocolitem{0 (VARCHAR)}{TABLE\_QUALIFIER}
 180 \twocolitem{1 (VARCHAR)}{TABLE\_OWNER}
 181 \twocolitem{2 (VARCHAR)}{TABLE\_NAME}
 182 \twocolitem{3 (VARCHAR)}{COLUMN\_NAME}
 183 \twocolitem{4 (SMALLINT)}{DATA\_TYPE}
 184 \twocolitem{5 (VARCHAR)}{TYPE\_NAME}
 185 \twocolitem{6 (INTEGER)}{PRECISION}
 186 \twocolitem{7 (INTEGER)}{LENGTH}
 187 \twocolitem{8 (SMALLINT)}{SCALE}
 188 \twocolitem{9 (SMALLINT)}{RADIX}
 189 \twocolitem{10 (SMALLINT)}{NULLABLE}
 190 \twocolitem{11 (VARCHAR)}{REMARKS}
 191 \end{twocollist}
 192
 193 \membersection{wxRecordSet::GetCurrentRecord}
 194
 195 \func{long}{GetCurrentRecord}{\void}
 196
 197 Not implemented.
 198
 199 \membersection{wxRecordSet::GetDatabase}
 200
 201 \func{wxDatabase *}{GetDatabase}{\void}
 202
 203 Returns the wxDatabase object bound to a wxRecordSet.
 204
 205 \membersection{wxRecordSet::GetDataSources}\label{wxrecordsetgetdatasources}
 206
 207 \func{bool}{GetDataSources}{\void}
 208
 209 Gets the currently-defined data sources via the ODBC manager. The data will be presented
 210 as a normal result set. See the documentation for the ODBC function SQLDataSources for how the data
 211 is organized.
 212
 213 Example:
 214
 215 \begin{verbatim}
 216   wxDatabase Database;
 217
 218   wxRecordSet *Record = new wxRecordSet(&Database);
 219
 220   if (!Record->GetDataSources()) {
 221     char buf[300];
 222     sprintf(buf, "%s %s\n", Database.GetErrorClass(), Database.GetErrorMessage());
 223     frame->output->SetValue(buf);
 224   }
 225   else {
 226     do {
 227       frame->DataSource->Append((char*)Record->GetFieldDataPtr(0, SQL_CHAR));
 228     } while (Record->MoveNext());
 229   }
 230 \end{verbatim}
 231
 232 \membersection{wxRecordSet::GetDefaultConnect}
 233
 234 \func{wxString}{GetDefaultConnect}{\void}
 235
 236 Not implemented.
 237
 238 \membersection{wxRecordSet::GetDefaultSQL}
 239
 240 \func{wxString}{GetDefaultSQL}{\void}
 241
 242 Not implemented.
 243
 244 \membersection{wxRecordSet::GetErrorCode}
 245
 246 \func{wxRETCODE}{GetErrorCode}{\void}
 247
 248 Returns the error code of the last ODBC action. This will be one of:
 249
 250 \begin{twocollist}\itemsep=0pt
 251 \twocolitem{SQL\_ERROR}{General error.}
 252 \twocolitem{SQL\_INVALID\_HANDLE}{An invalid handle was passed to an ODBC function.}
 253 \twocolitem{SQL\_NEED\_DATA}{ODBC expected some data.}
 254 \twocolitem{SQL\_NO\_DATA\_FOUND}{No data was found by this ODBC call.}
 255 \twocolitem{SQL\_SUCCESS}{The call was successful.}
 256 \twocolitem{SQL\_SUCCESS\_WITH\_INFO}{The call was successful, but further information can be
 257 obtained from the ODBC manager.}
 258 \end{twocollist}
 259
 260 \membersection{wxRecordSet::GetFieldData}\label{wxrecordsetgetfielddata}
 261
 262 \func{bool}{GetFieldData}{\param{int}{ col}, \param{int}{ dataType}, \param{void *}{dataPtr}}
 263
 264 Copies the current data of the column at position {\it col} into the buffer
 265 \rtfsp{\it dataPtr}. To be sure to get the right type of data, the user has to pass the
 266 correct data type. The function returns FALSE if {\it col} does not
 267 exist or the wrong data type was given.
 268
 269 \func{bool}{GetFieldData}{\param{const wxString\& }{name}, \param{int}{ dataType}, \param{void *}{dataPtr}}
 270
 271 The same as above, but uses the column name as the identifier.
 272
 273 See \helpref{ODBC SQL data types}{sqltypes} for a list
 274 of possible data types.
 275
 276 \membersection{wxRecordSet::GetFieldDataPtr}\label{wxrecordsetgetfielddataptr}
 277
 278 \func{void *}{GetFieldDataPtr}{\param{int}{ col}, \param{int}{ dataType}}
 279
 280 Returns the current data pointer of the column at position {\it col}.
 281 To be sure to get the right type of data, the user has to pass the
 282 data type. Returns NULL if {\it col} does not exist or if {\it dataType} is
 283 incorrect.
 284
 285 \func{void *}{GetFieldDataPtr}{\param{const wxString\& }{name}, \param{int}{ dataType}}
 286
 287 The same as above, but uses the column name as the identifier.
 288
 289 See \helpref{ODBC SQL data types}{sqltypes} for a list
 290 of possible data types.
 291
 292 \membersection{wxRecordSet::GetFilter}
 293
 294 \func{wxString}{GetFilter}{\void}
 295
 296 Returns the current filter.
 297
 298 \membersection{wxRecordSet::GetForeignKeys}
 299
 300 \func{bool}{GetPrimaryKeys}{\param{const wxString\& }{ptable = NULL}, \param{const wxString\& }{ftable
 301 = NULL}}
 302
 303 Returns a list of foreign keys in the specified table (columns in the
 304 specified table that refer to primary keys in other tables), or
 305 a list of foreign keys in other tables that refer to the primary key in
 306 the specified table.
 307
 308 If {\it ptable} contains a table name, this function returns a result
 309 set containing the primary key of the specified table.
 310
 311 If {\it ftable} contains a table name, this functions returns a result set
 312 of containing all of the foreign keys in the specified table and the
 313 primary keys (in other tables) to which they refer.
 314
 315 If both {\it ptable} and {\it ftable} contain table names, this
 316 function returns the foreign keys in the table specified in {\it
 317 ftable} that refer to the primary key of the table specified in {\it
 318 ptable}. This should be one key at most.
 319
 320 GetForeignKeys returns results as a standard result set. If the foreign
 321 keys associated with a primary key are requested, the result set is
 322 ordered by FKTABLE\_QUALIFIER, FKTABLE\_OWNER, FKTABLE\_NAME, and KEY\_SEQ.
 323 If the primary keys associated with a foreign key are requested, the
 324 result set is ordered by PKTABLE\_QUALIFIER, PKTABLE\_OWNER, PKTABLE\_NAME,
 325 and KEY\_SEQ. The following table lists the columns in the result set.
 326
 327 \begin{twocollist}\itemsep=0pt
 328 \twocolitem{0 (VARCHAR)}{PKTABLE\_QUALIFIER}
 329 \twocolitem{1 (VARCHAR)}{PKTABLE\_OWNER}
 330 \twocolitem{2 (VARCHAR)}{PKTABLE\_NAME}
 331 \twocolitem{3 (VARCHAR)}{PKCOLUMN\_NAME}
 332 \twocolitem{4 (VARCHAR)}{FKTABLE\_QUALIFIER}
 333 \twocolitem{5 (VARCHAR)}{FKTABLE\_OWNER}
 334 \twocolitem{6 (VARCHAR)}{FKTABLE\_NAME}
 335 \twocolitem{7 (VARCHAR)}{FKCOLUMN\_NAME}
 336 \twocolitem{8 (SMALLINT)}{KEY\_SEQ}
 337 \twocolitem{9 (SMALLINT)}{UPDATE\_RULE}
 338 \twocolitem{10 (SMALLINT)}{DELETE\_RULE}
 339 \twocolitem{11 (VARCHAR)}{FK\_NAME}
 340 \twocolitem{12 (VARCHAR)}{PK\_NAME}
 341 \end{twocollist}
 342
 343 \membersection{wxRecordSet::GetNumberCols}
 344
 345 \func{long}{GetNumberCols}{\void}
 346
 347 Returns the number of columns in the result set.
 348
 349 \membersection{wxRecordSet::GetNumberFields}
 350
 351 \func{int}{GetNumberFields}{\void}
 352
 353 Not implemented.
 354
 355 \membersection{wxRecordSet::GetNumberParams}
 356
 357 \func{int}{GetNumberParams}{\void}
 358
 359 Not implemented.
 360
 361 \membersection{wxRecordSet::GetNumberRecords}
 362
 363 \func{long}{GetNumberRecords}{\void}
 364
 365 Returns the number of records in the result set.
 366
 367 \membersection{wxRecordSet::GetPrimaryKeys}
 368
 369 \func{bool}{GetPrimaryKeys}{\param{const wxString\& }{table = NULL}}
 370
 371 Returns the column names that comprise the primary key of the table with the specified name. If no name is
 372 given the class member {\it tablename} will be used. If both names are NULL
 373 nothing will happen. The data will be presented as a normal result set, organized
 374 as follows:
 375
 376 \begin{twocollist}\itemsep=0pt
 377 \twocolitem{0 (VARCHAR)}{TABLE\_QUALIFIER}
 378 \twocolitem{1 (VARCHAR)}{TABLE\_OWNER}
 379 \twocolitem{2 (VARCHAR)}{TABLE\_NAME}
 380 \twocolitem{3 (VARCHAR)}{COLUMN\_NAME}
 381 \twocolitem{4 (SMALLINT)}{KEY\_SEQ}
 382 \twocolitem{5 (VARCHAR)}{PK\_NAME}
 383 \end{twocollist}
 384
 385 \membersection{wxRecordSet::GetOptions}
 386
 387 \func{int}{GetOptions}{\void}
 388
 389 Returns the options of the wxRecordSet. Options are not supported yet.
 390
 391 \membersection{wxRecordSet::GetResultSet}
 392
 393 \func{bool}{GetResultSet}{\void}
 394
 395 Copies the data presented by ODBC into wxRecordSet. Depending on the
 396 wxRecordSet type all or only one record(s) will be copied.
 397 Usually this function will be called automatically after each successful
 398 database operation.
 399
 400 \membersection{wxRecordSet::GetSortString}
 401
 402 \func{wxString}{GetSortString}{\void}
 403
 404 Not implemented.
 405
 406 \membersection{wxRecordSet::GetSQL}
 407
 408 \func{wxString}{GetSQL}{\void}
 409
 410 Not implemented.
 411
 412 \membersection{wxRecordSet::GetTableName}
 413
 414 \func{wxString}{GetTableName}{\void}
 415
 416 Returns the name of the current table.
 417
 418 \membersection{wxRecordSet::GetTables}
 419
 420 \func{bool}{GetTables}{\void}
 421
 422 Gets the tables of a database. The data will be presented as a normal result
 423 set, organized as follows:
 424
 425 \begin{twocollist}\itemsep=0pt
 426 \twocolitem{0 (VARCHAR)}{TABLE\_QUALIFIER}
 427 \twocolitem{1 (VARCHAR)}{TABLE\_OWNER}
 428 \twocolitem{2 (VARCHAR)}{TABLE\_NAME}
 429 \twocolitem{3 (VARCHAR)}{TABLE\_TYPE (TABLE, VIEW, SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY,
 430 ALIAS, SYNONYM, or database-specific type)}
 431 \twocolitem{4 (VARCHAR)}{REMARKS}
 432 \end{twocollist}
 433
 434 \membersection{wxRecordSet::GetType}
 435
 436 \func{int}{GetType}{\void}
 437
 438 Returns the type of the wxRecordSet: wxOPEN\_TYPE\_DYNASET or
 439 wxOPEN\_TYPE\_SNAPSHOT. See the wxRecordSet description for details.
 440
 441 \membersection{wxRecordSet::GoTo}
 442
 443 \func{bool}{GoTo}{\param{long}{ n}}
 444
 445 Moves the cursor to the record with the number n, where  the first record
 446 has the number 0.
 447
 448 \membersection{wxRecordSet::IsBOF}
 449
 450 \func{bool}{IsBOF}{\void}
 451
 452 Returns TRUE if the user tried to move the cursor before the first record
 453 in the set.
 454
 455 \membersection{wxRecordSet::IsFieldDirty}
 456
 457 \func{bool}{IsFieldDirty}{\param{int}{ field}}
 458
 459 Returns TRUE if the given field has been changed but not saved yet.
 460
 461 \func{bool}{IsFieldDirty}{\param{const wxString\& }{name}}
 462
 463 Same as above, but uses the column name as the identifier.
 464
 465 \membersection{wxRecordSet::IsFieldNull}
 466
 467 \func{bool}{IsFieldNull}{\param{int}{ field}}
 468
 469 Returns TRUE if the given field has no data.
 470
 471 \func{bool}{IsFieldNull}{\param{const wxString\& }{ name}}
 472
 473 Same as above, but uses the column name as the identifier.
 474
 475 \membersection{wxRecordSet::IsColNullable}
 476
 477 \func{bool}{IsColNullable}{\param{int}{ col}}
 478
 479 Returns TRUE if the given column may contain no data.
 480
 481 \func{bool}{IsColNullable}{\param{const wxString\& }{name}}
 482
 483 Same as above, but uses the column name as the identifier.
 484
 485 \membersection{wxRecordSet::IsEOF}
 486
 487 \func{bool}{IsEOF}{\void}
 488
 489 Returns TRUE if the user tried to move the cursor behind the last record
 490 in the set.
 491
 492 \membersection{wxRecordSet::IsDeleted}
 493
 494 \func{bool}{IsDeleted}{\void}
 495
 496 Not implemented.
 497
 498 \membersection{wxRecordSet::IsOpen}
 499
 500 \func{bool}{IsOpen}{\void}
 501
 502 Returns TRUE if the parent database is open.
 503
 504 \membersection{wxRecordSet::Move}
 505
 506 \func{bool}{Move}{\param{long}{ rows}}
 507
 508 Moves the cursor a given number of rows. Negative values are allowed.
 509
 510 \membersection{wxRecordSet::MoveFirst}
 511
 512 \func{bool}{MoveFirst}{\void}
 513
 514 Moves the cursor to the first record.
 515
 516 \membersection{wxRecordSet::MoveLast}
 517
 518 \func{bool}{MoveLast}{\void}
 519
 520 Moves the cursor to the last record.
 521
 522 \membersection{wxRecordSet::MoveNext}\label{wxrecordsetmovenext}
 523
 524 \func{bool}{MoveNext}{\void}
 525
 526 Moves the cursor to the next record.
 527
 528 \membersection{wxRecordSet::MovePrev}\label{wxrecordsetmoveprev}
 529
 530 \func{bool}{MovePrev}{\void}
 531
 532 Moves the cursor to the previous record.
 533
 534 \membersection{wxRecordSet::Query}
 535
 536 \func{bool}{Query}{\param{const wxString\& }{columns}, \param{const wxString\& }{table}, \param{const wxString\& }{filter = NULL}}
 537
 538 Start a query. An SQL string of the following type will automatically be
 539 generated and executed: ``SELECT columns FROM table WHERE filter".
 540
 541 \membersection{wxRecordSet::RecordCountFinal}
 542
 543 \func{bool}{RecordCountFinal}{\void}
 544
 545 Not implemented.
 546
 547 \membersection{wxRecordSet::Requery}
 548
 549 \func{bool}{Requery}{\void}
 550
 551 Re-executes the last query. Not implemented.
 552
 553 \membersection{wxRecordSet::SetFieldDirty}
 554
 555 \func{void}{SetFieldDirty}{\param{int}{ field}, \param{bool}{ dirty = TRUE}}
 556
 557 Sets the dirty tag of the field field. Not implemented.
 558
 559 \func{void}{SetFieldDirty}{\param{const wxString\& }{name}, \param{bool}{ dirty = TRUE}}
 560
 561 Same as above, but uses the column name as the identifier.
 562
 563 \membersection{wxRecordSet::SetDefaultSQL}
 564
 565 \func{void}{SetDefaultSQL}{\param{const wxString\& }{s}}
 566
 567 Not implemented.
 568
 569 \membersection{wxRecordSet::SetFieldNull}
 570
 571 \func{void}{SetFieldNull}{\param{void *}{p}, \param{bool }{isNull = TRUE}}
 572
 573 Not implemented.
 574
 575 \membersection{wxRecordSet::SetOptions}
 576
 577 \func{void}{SetOptions}{\param{int}{ opt}}
 578
 579 Sets the options of the wxRecordSet. Not implemented.
 580
 581 \membersection{wxRecordSet::SetTableName}
 582
 583 \func{void}{SetTableName}{\param{const wxString\& }{tablename}}
 584
 585 Specify the name of the table you want to use.
 586
 587 \membersection{wxRecordSet::SetType}
 588
 589 \func{void}{SetType}{\param{int}{ type}}
 590
 591 Sets the type of the wxRecordSet. See the wxRecordSet class description for details.
 592
 593 \membersection{wxRecordSet::Update}
 594
 595 \func{bool}{Update}{\void}
 596
 597 Writes back the current record. Not implemented.
 598
 599