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