]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/recrdset.tex
Corrected some problems I introduced, added tabevent.tex.
[wxWidgets.git] / docs / latex / wx / recrdset.tex
... / ...
CommitLineData
1\section{\class{wxRecordSet}}\label{wxrecordset}
2
3Each wxRecordSet represents an ODBC database query. You can make multiple queries
4at a time by using multiple wxRecordSets with a wxDatabase or you can make
5your 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
22Constructor. {\it db} is a pointer to the wxDatabase instance you wish to use the
23wxRecordSet 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
27data of the result set will be loaded dynamically when
28moving the cursor. This is the default type.
29\item wxOPEN\_TYPE\_SNAPSHOT: Loads all records of a result set at once. This will
30need much more memory, but will result in
31faster access to the ODBC data.
32\end{itemize}
33
34The {\it option} parameter is not used yet.
35
36The constructor appends the wxRecordSet object to the parent database's list of
37wxRecordSet objects, for later destruction when the wxDatabase is destroyed.
38
39\membersection{wxRecordSet::\destruct{wxRecordSet}}
40
41\func{}{\destruct{wxRecordSet}}{\void}
42
43Destructor. All data except that stored in user-defined variables will be lost.
44It also unlinks the wxRecordSet object from the parent database's list of
45wxRecordSet objects.
46
47\membersection{wxRecordSet::AddNew}
48
49\func{void}{AddNew}{\void}
50
51Not 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
57Not implemented.
58
59\membersection{wxRecordSet::BindVar}
60
61\func{void *}{BindVar}{\param{int}{ col}, \param{void *}{buf}, \param{long}{ size}}
62
63Binds a user-defined variable to the column col. Whenever the current field's
64data 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
68The same as above, but uses the column name as the identifier.
69
70\membersection{wxRecordSet::CanAppend}
71
72\func{bool}{CanAppend}{\void}
73
74Not implemented.
75
76\membersection{wxRecordSet::Cancel}
77
78\func{void}{Cancel}{\void}
79
80Not implemented.
81
82\membersection{wxRecordSet::CanRestart}
83
84\func{bool}{CanRestart}{\void}
85
86Not implemented.
87
88\membersection{wxRecordSet::CanScroll}
89
90\func{bool}{CanScroll}{\void}
91
92Not implemented.
93
94\membersection{wxRecordSet::CanTransact}
95
96\func{bool}{CanTransact}{\void}
97
98Not implemented.
99
100\membersection{wxRecordSet::CanUpdate}
101
102\func{bool}{CanUpdate}{\void}
103
104Not implemented.
105
106\membersection{wxRecordSet::ConstructDefaultSQL}
107
108\func{bool}{ConstructDefaultSQL}{\void}
109
110Not implemented.
111
112\membersection{wxRecordSet::Delete}
113
114\func{bool}{Delete}{\void}
115
116Deletes the current record. Not implemented.
117
118\membersection{wxRecordSet::Edit}
119
120\func{void}{Edit}{\void}
121
122Not implemented.
123
124\membersection{wxRecordSet::EndQuery}
125
126\func{bool}{EndQuery}{\void}
127
128Not implemented.
129
130\membersection{wxRecordSet::ExecuteSQL}\label{wxrecordsetexecutesql}
131
132\func{bool}{ExecuteSQL}{\param{const wxString\& }{sql}}
133
134Directly executes a SQL statement. The data will be presented as a normal
135result set. Note that the recordset must have been created as a snapshot, not
136dynaset. Dynasets will be implemented in the near future.
137
138Examples 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
144Fills in the user-defined variables of the columns. You can set these
145variables with wxQueryCol::BindVar. This function will be automatically
146called after every successful database operation.
147
148\membersection{wxRecordSet::GetColName}
149
150\func{wxString}{GetColName}{\param{int}{ col}}
151
152Returns the name of the column at position {\it col}. Returns NULL if {\it col} does not
153exist.
154
155\membersection{wxRecordSet::GetColType}
156
157\func{short}{GetColType}{\param{int}{ col}}
158
159Returns the data type of the column at position {\it col}. Returns SQL\_TYPE\_NULL
160if {\it col} does not exist.
161
162\func{short}{GetColType}{\param{const wxString\& }{ name}}
163
164The same as above, but uses the column name as the identifier.
165
166See \helpref{ODBC SQL data types}{sqltypes} for a list
167of possible data types.
168
169\membersection{wxRecordSet::GetColumns}
170
171\func{bool}{GetColumns}{\param{const wxString\& }{table = NULL}}
172
173Returns the columns of the table with the specified name. If no name is
174given the class member {\it tablename} will be used. If both names are NULL
175nothing will happen. The data will be presented as a normal result set, organized
176as 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
197Not implemented.
198
199\membersection{wxRecordSet::GetDatabase}
200
201\func{wxDatabase *}{GetDatabase}{\void}
202
203Returns the wxDatabase object bound to a wxRecordSet.
204
205\membersection{wxRecordSet::GetDataSources}\label{wxrecordsetgetdatasources}
206
207\func{bool}{GetDataSources}{\void}
208
209Gets the currently-defined data sources via the ODBC manager. The data will be presented
210as a normal result set. See the documentation for the ODBC function SQLDataSources for how the data
211is organized.
212
213Example:
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
236Not implemented.
237
238\membersection{wxRecordSet::GetDefaultSQL}
239
240\func{wxString}{GetDefaultSQL}{\void}
241
242Not implemented.
243
244\membersection{wxRecordSet::GetErrorCode}
245
246\func{wxRETCODE}{GetErrorCode}{\void}
247
248Returns 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
257obtained 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
264Copies 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
266correct data type. The function returns FALSE if {\it col} does not
267exist or the wrong data type was given.
268
269\func{bool}{GetFieldData}{\param{const wxString\& }{name}, \param{int}{ dataType}, \param{void *}{dataPtr}}
270
271The same as above, but uses the column name as the identifier.
272
273See \helpref{ODBC SQL data types}{sqltypes} for a list
274of possible data types.
275
276\membersection{wxRecordSet::GetFieldDataPtr}\label{wxrecordsetgetfielddataptr}
277
278\func{void *}{GetFieldDataPtr}{\param{int}{ col}, \param{int}{ dataType}}
279
280Returns the current data pointer of the column at position {\it col}.
281To be sure to get the right type of data, the user has to pass the
282data type. Returns NULL if {\it col} does not exist or if {\it dataType} is
283incorrect.
284
285\func{void *}{GetFieldDataPtr}{\param{const wxString\& }{name}, \param{int}{ dataType}}
286
287The same as above, but uses the column name as the identifier.
288
289See \helpref{ODBC SQL data types}{sqltypes} for a list
290of possible data types.
291
292\membersection{wxRecordSet::GetFilter}
293
294\func{wxString}{GetFilter}{\void}
295
296Returns 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
303Returns a list of foreign keys in the specified table (columns in the
304specified table that refer to primary keys in other tables), or
305a list of foreign keys in other tables that refer to the primary key in
306the specified table.
307
308If {\it ptable} contains a table name, this function returns a result
309set containing the primary key of the specified table.
310
311If {\it ftable} contains a table name, this functions returns a result set
312of containing all of the foreign keys in the specified table and the
313primary keys (in other tables) to which they refer.
314
315If both {\it ptable} and {\it ftable} contain table names, this
316function returns the foreign keys in the table specified in {\it
317ftable} that refer to the primary key of the table specified in {\it
318ptable}. This should be one key at most.
319
320GetForeignKeys returns results as a standard result set. If the foreign
321keys associated with a primary key are requested, the result set is
322ordered by FKTABLE\_QUALIFIER, FKTABLE\_OWNER, FKTABLE\_NAME, and KEY\_SEQ.
323If the primary keys associated with a foreign key are requested, the
324result set is ordered by PKTABLE\_QUALIFIER, PKTABLE\_OWNER, PKTABLE\_NAME,
325and 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
347Returns the number of columns in the result set.
348
349\membersection{wxRecordSet::GetNumberFields}
350
351\func{int}{GetNumberFields}{\void}
352
353Not implemented.
354
355\membersection{wxRecordSet::GetNumberParams}
356
357\func{int}{GetNumberParams}{\void}
358
359Not implemented.
360
361\membersection{wxRecordSet::GetNumberRecords}
362
363\func{long}{GetNumberRecords}{\void}
364
365Returns the number of records in the result set.
366
367\membersection{wxRecordSet::GetPrimaryKeys}
368
369\func{bool}{GetPrimaryKeys}{\param{const wxString\& }{table = NULL}}
370
371Returns the column names that comprise the primary key of the table with the specified name. If no name is
372given the class member {\it tablename} will be used. If both names are NULL
373nothing will happen. The data will be presented as a normal result set, organized
374as 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
389Returns the options of the wxRecordSet. Options are not supported yet.
390
391\membersection{wxRecordSet::GetResultSet}
392
393\func{bool}{GetResultSet}{\void}
394
395Copies the data presented by ODBC into wxRecordSet. Depending on the
396wxRecordSet type all or only one record(s) will be copied.
397Usually this function will be called automatically after each successful
398database operation.
399
400\membersection{wxRecordSet::GetSortString}
401
402\func{wxString}{GetSortString}{\void}
403
404Not implemented.
405
406\membersection{wxRecordSet::GetSQL}
407
408\func{wxString}{GetSQL}{\void}
409
410Not implemented.
411
412\membersection{wxRecordSet::GetTableName}
413
414\func{wxString}{GetTableName}{\void}
415
416Returns the name of the current table.
417
418\membersection{wxRecordSet::GetTables}
419
420\func{bool}{GetTables}{\void}
421
422Gets the tables of a database. The data will be presented as a normal result
423set, 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,
430ALIAS, 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
438Returns the type of the wxRecordSet: wxOPEN\_TYPE\_DYNASET or
439wxOPEN\_TYPE\_SNAPSHOT. See the wxRecordSet description for details.
440
441\membersection{wxRecordSet::GoTo}
442
443\func{bool}{GoTo}{\param{long}{ n}}
444
445Moves the cursor to the record with the number n, where the first record
446has the number 0.
447
448\membersection{wxRecordSet::IsBOF}
449
450\func{bool}{IsBOF}{\void}
451
452Returns TRUE if the user tried to move the cursor before the first record
453in the set.
454
455\membersection{wxRecordSet::IsFieldDirty}
456
457\func{bool}{IsFieldDirty}{\param{int}{ field}}
458
459Returns TRUE if the given field has been changed but not saved yet.
460
461\func{bool}{IsFieldDirty}{\param{const wxString\& }{name}}
462
463Same as above, but uses the column name as the identifier.
464
465\membersection{wxRecordSet::IsFieldNull}
466
467\func{bool}{IsFieldNull}{\param{int}{ field}}
468
469Returns TRUE if the given field has no data.
470
471\func{bool}{IsFieldNull}{\param{const wxString\& }{ name}}
472
473Same as above, but uses the column name as the identifier.
474
475\membersection{wxRecordSet::IsColNullable}
476
477\func{bool}{IsColNullable}{\param{int}{ col}}
478
479Returns TRUE if the given column may contain no data.
480
481\func{bool}{IsColNullable}{\param{const wxString\& }{name}}
482
483Same as above, but uses the column name as the identifier.
484
485\membersection{wxRecordSet::IsEOF}
486
487\func{bool}{IsEOF}{\void}
488
489Returns TRUE if the user tried to move the cursor behind the last record
490in the set.
491
492\membersection{wxRecordSet::IsDeleted}
493
494\func{bool}{IsDeleted}{\void}
495
496Not implemented.
497
498\membersection{wxRecordSet::IsOpen}
499
500\func{bool}{IsOpen}{\void}
501
502Returns TRUE if the parent database is open.
503
504\membersection{wxRecordSet::Move}
505
506\func{bool}{Move}{\param{long}{ rows}}
507
508Moves the cursor a given number of rows. Negative values are allowed.
509
510\membersection{wxRecordSet::MoveFirst}
511
512\func{bool}{MoveFirst}{\void}
513
514Moves the cursor to the first record.
515
516\membersection{wxRecordSet::MoveLast}
517
518\func{bool}{MoveLast}{\void}
519
520Moves the cursor to the last record.
521
522\membersection{wxRecordSet::MoveNext}\label{wxrecordsetmovenext}
523
524\func{bool}{MoveNext}{\void}
525
526Moves the cursor to the next record.
527
528\membersection{wxRecordSet::MovePrev}\label{wxrecordsetmoveprev}
529
530\func{bool}{MovePrev}{\void}
531
532Moves 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
538Start a query. An SQL string of the following type will automatically be
539generated and executed: ``SELECT columns FROM table WHERE filter".
540
541\membersection{wxRecordSet::RecordCountFinal}
542
543\func{bool}{RecordCountFinal}{\void}
544
545Not implemented.
546
547\membersection{wxRecordSet::Requery}
548
549\func{bool}{Requery}{\void}
550
551Re-executes the last query. Not implemented.
552
553\membersection{wxRecordSet::SetFieldDirty}
554
555\func{void}{SetFieldDirty}{\param{int}{ field}, \param{bool}{ dirty = TRUE}}
556
557Sets the dirty tag of the field field. Not implemented.
558
559\func{void}{SetFieldDirty}{\param{const wxString\& }{name}, \param{bool}{ dirty = TRUE}}
560
561Same 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
567Not implemented.
568
569\membersection{wxRecordSet::SetFieldNull}
570
571\func{void}{SetFieldNull}{\param{void *}{p}, \param{bool }{isNull = TRUE}}
572
573Not implemented.
574
575\membersection{wxRecordSet::SetOptions}
576
577\func{void}{SetOptions}{\param{int}{ opt}}
578
579Sets the options of the wxRecordSet. Not implemented.
580
581\membersection{wxRecordSet::SetTableName}
582
583\func{void}{SetTableName}{\param{const wxString\& }{tablename}}
584
585Specify the name of the table you want to use.
586
587\membersection{wxRecordSet::SetType}
588
589\func{void}{SetType}{\param{int}{ type}}
590
591Sets the type of the wxRecordSet. See the wxRecordSet class description for details.
592
593\membersection{wxRecordSet::Update}
594
595\func{bool}{Update}{\void}
596
597Writes back the current record. Not implemented.
598
599