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