use wxChar correctly in wxString docs; mark wx1 compatibility functions

[wxWidgets.git] / docs / latex / wx / recrdset.tex

\section{\class{wxRecordSet}}\label{wxrecordset}

Each wxRecordSet represents an ODBC database query. You can make multiple queries
at a time by using multiple wxRecordSets with a wxDatabase or you can make
your queries in sequential order using the same wxRecordSet.

Note: this class is considered obsolete, replaced by the Remstar 
wxDB/wxDbTable classes

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/odbc.h>

\wxheading{See also}

\helpref{wxRecordSet overview}{wxrecordsetoverview}, \helpref{wxDatabase overview}{wxdatabaseoverview}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxRecordSet::wxRecordSet}

\func{}{wxRecordSet}{\param{wxDatabase *}{db}, \param{int}{ type = wxOPEN\_TYPE\_DYNASET},
 \param{int}{ opt = wxOPTION\_DEFAULT}}

Constructor. {\it db} is a pointer to the wxDatabase instance you wish to use the
wxRecordSet with. Currently there are two possible values of {\it type}:

\begin{itemize}\itemsep=0pt
\item wxOPEN\_TYPE\_DYNASET: Loads only one record at a time into memory. The other
data of the result set will be loaded dynamically when
moving the cursor. This is the default type.
\item wxOPEN\_TYPE\_SNAPSHOT: Loads all records of a result set at once. This will
need much more memory, but will result in
faster access to the ODBC data.
\end{itemize}

The {\it option} parameter is not used yet.

The constructor appends the wxRecordSet object to the parent database's list of
wxRecordSet objects, for later destruction when the wxDatabase is destroyed.

\membersection{wxRecordSet::\destruct{wxRecordSet}}

\func{}{\destruct{wxRecordSet}}{\void}

Destructor. All data except that stored in user-defined variables will be lost.
It also unlinks the wxRecordSet object from the parent database's list of
wxRecordSet objects.
 
\membersection{wxRecordSet::AddNew}

\func{void}{AddNew}{\void}

Not implemented.

\membersection{wxRecordSet::BeginQuery}

\func{bool}{BeginQuery}{\param{int}{ openType}, \param{const wxString\& }{sql = NULL}, \param{int}{ options = wxOPTION\_DEFAULT}}

Not implemented.

\membersection{wxRecordSet::BindVar}

\func{void *}{BindVar}{\param{int}{ col}, \param{void *}{buf}, \param{long}{ size}}

Binds a user-defined variable to the column col. Whenever the current field's
data changes, it will be copied into buf (maximum {\it size} bytes).

\func{void *}{BindVar}{\param{const wxString\& }{col}, \param{void *}{buf}, \param{long}{ size}}

The same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::CanAppend}

\func{bool}{CanAppend}{\void}

Not implemented.

\membersection{wxRecordSet::Cancel}

\func{void}{Cancel}{\void}

Not implemented.

\membersection{wxRecordSet::CanRestart}

\func{bool}{CanRestart}{\void}

Not implemented.

\membersection{wxRecordSet::CanScroll}

\func{bool}{CanScroll}{\void}

Not implemented.

\membersection{wxRecordSet::CanTransact}

\func{bool}{CanTransact}{\void}

Not implemented.

\membersection{wxRecordSet::CanUpdate}

\func{bool}{CanUpdate}{\void}

Not implemented.

\membersection{wxRecordSet::ConstructDefaultSQL}

\func{bool}{ConstructDefaultSQL}{\void}

Not implemented.

\membersection{wxRecordSet::Delete}

\func{bool}{Delete}{\void}

Deletes the current record. Not implemented.

\membersection{wxRecordSet::Edit}

\func{void}{Edit}{\void}

Not implemented.

\membersection{wxRecordSet::EndQuery}

\func{bool}{EndQuery}{\void}

Not implemented.

\membersection{wxRecordSet::ExecuteSQL}\label{wxrecordsetexecutesql}

\func{bool}{ExecuteSQL}{\param{const wxString\& }{sql}}

Directly executes a SQL statement. The data will be presented as a normal
result set. Note that the recordset must have been created as a snapshot, not
dynaset. Dynasets will be implemented in the near future.

Examples of common SQL statements are given in \helpref{A selection of SQL commands}{sqlcommands}.

\membersection{wxRecordSet::FillVars}

\func{void}{FillVars}{\param{int}{ recnum}}

Fills in the user-defined variables of the columns. You can set these
variables with wxQueryCol::BindVar. This function will be automatically
called after every successful database operation.

\membersection{wxRecordSet::GetColName}

\func{wxString}{GetColName}{\param{int}{ col}}

Returns the name of the column at position {\it col}. Returns NULL if {\it col} does not
exist.

\membersection{wxRecordSet::GetColType}

\func{short}{GetColType}{\param{int}{ col}}

Returns the data type of the column at position {\it col}. Returns SQL\_TYPE\_NULL
if {\it col} does not exist.

\func{short}{GetColType}{\param{const wxString\& }{ name}}

The same as above, but uses the column name as the identifier.

See \helpref{ODBC SQL data types}{sqltypes} for a list
of possible data types.

\membersection{wxRecordSet::GetColumns}

\func{bool}{GetColumns}{\param{const wxString\& }{table = NULL}}

Returns the columns of the table with the specified name. If no name is
given the class member {\it tablename} will be used. If both names are NULL
nothing will happen. The data will be presented as a normal result set, organized
as follows:

\begin{twocollist}\itemsep=0pt
\twocolitem{0 (VARCHAR)}{TABLE\_QUALIFIER}
\twocolitem{1 (VARCHAR)}{TABLE\_OWNER}
\twocolitem{2 (VARCHAR)}{TABLE\_NAME}
\twocolitem{3 (VARCHAR)}{COLUMN\_NAME}
\twocolitem{4 (SMALLINT)}{DATA\_TYPE}
\twocolitem{5 (VARCHAR)}{TYPE\_NAME}
\twocolitem{6 (INTEGER)}{PRECISION}
\twocolitem{7 (INTEGER)}{LENGTH}
\twocolitem{8 (SMALLINT)}{SCALE}
\twocolitem{9 (SMALLINT)}{RADIX}
\twocolitem{10 (SMALLINT)}{NULLABLE}
\twocolitem{11 (VARCHAR)}{REMARKS}
\end{twocollist}

\membersection{wxRecordSet::GetCurrentRecord}

\func{long}{GetCurrentRecord}{\void}

Not implemented.

\membersection{wxRecordSet::GetDatabase}

\func{wxDatabase *}{GetDatabase}{\void}

Returns the wxDatabase object bound to a wxRecordSet.

\membersection{wxRecordSet::GetDataSources}\label{wxrecordsetgetdatasources}

\func{bool}{GetDataSources}{\void}

Gets the currently-defined data sources via the ODBC manager. The data will be presented
as a normal result set. See the documentation for the ODBC function SQLDataSources for how the data
is organized.

Example:
  
\begin{verbatim}
  wxDatabase Database;

  wxRecordSet *Record = new wxRecordSet(&Database);

  if (!Record->GetDataSources()) {
    char buf[300];
    sprintf(buf, "%s %s\n", Database.GetErrorClass(), Database.GetErrorMessage());
    frame->output->SetValue(buf);
  }
  else {
    do {
      frame->DataSource->Append((char*)Record->GetFieldDataPtr(0, SQL_CHAR));
    } while (Record->MoveNext());
  }
\end{verbatim}

\membersection{wxRecordSet::GetDefaultConnect}

\func{wxString}{GetDefaultConnect}{\void}

Not implemented.

\membersection{wxRecordSet::GetDefaultSQL}

\func{wxString}{GetDefaultSQL}{\void}

Not implemented.

\membersection{wxRecordSet::GetErrorCode}

\func{wxRETCODE}{GetErrorCode}{\void}

Returns the error code of the last ODBC action. This will be one of:

\begin{twocollist}\itemsep=0pt
\twocolitem{SQL\_ERROR}{General error.}
\twocolitem{SQL\_INVALID\_HANDLE}{An invalid handle was passed to an ODBC function.}
\twocolitem{SQL\_NEED\_DATA}{ODBC expected some data.}
\twocolitem{SQL\_NO\_DATA\_FOUND}{No data was found by this ODBC call.}
\twocolitem{SQL\_SUCCESS}{The call was successful.}
\twocolitem{SQL\_SUCCESS\_WITH\_INFO}{The call was successful, but further information can be
obtained from the ODBC manager.}
\end{twocollist}

\membersection{wxRecordSet::GetFieldData}\label{wxrecordsetgetfielddata}

\func{bool}{GetFieldData}{\param{int}{ col}, \param{int}{ dataType}, \param{void *}{dataPtr}}

Copies the current data of the column at position {\it col} into the buffer
\rtfsp{\it dataPtr}. To be sure to get the right type of data, the user has to pass the
correct data type. The function returns false if {\it col} does not
exist or the wrong data type was given.

\func{bool}{GetFieldData}{\param{const wxString\& }{name}, \param{int}{ dataType}, \param{void *}{dataPtr}}

The same as above, but uses the column name as the identifier.

See \helpref{ODBC SQL data types}{sqltypes} for a list
of possible data types.

\membersection{wxRecordSet::GetFieldDataPtr}\label{wxrecordsetgetfielddataptr}

\func{void *}{GetFieldDataPtr}{\param{int}{ col}, \param{int}{ dataType}}

Returns the current data pointer of the column at position {\it col}.
To be sure to get the right type of data, the user has to pass the
data type. Returns NULL if {\it col} does not exist or if {\it dataType} is
incorrect.

\func{void *}{GetFieldDataPtr}{\param{const wxString\& }{name}, \param{int}{ dataType}}

The same as above, but uses the column name as the identifier.

See \helpref{ODBC SQL data types}{sqltypes} for a list
of possible data types.

\membersection{wxRecordSet::GetFilter}

\func{wxString}{GetFilter}{\void}

Returns the current filter.

\membersection{wxRecordSet::GetForeignKeys}

\func{bool}{GetPrimaryKeys}{\param{const wxString\& }{ptable = NULL}, \param{const wxString\& }{ftable
= NULL}}

Returns a list of foreign keys in the specified table (columns in the
specified table that refer to primary keys in other tables), or
a list of foreign keys in other tables that refer to the primary key in
the specified table.

If {\it ptable} contains a table name, this function returns a result
set containing the primary key of the specified table.

If {\it ftable} contains a table name, this functions returns a result set
of containing all of the foreign keys in the specified table and the
primary keys (in other tables) to which they refer.

If both {\it ptable} and {\it ftable} contain table names, this
function returns the foreign keys in the table specified in {\it
ftable} that refer to the primary key of the table specified in {\it
ptable}. This should be one key at most.

GetForeignKeys returns results as a standard result set. If the foreign
keys associated with a primary key are requested, the result set is
ordered by FKTABLE\_QUALIFIER, FKTABLE\_OWNER, FKTABLE\_NAME, and KEY\_SEQ.
If the primary keys associated with a foreign key are requested, the
result set is ordered by PKTABLE\_QUALIFIER, PKTABLE\_OWNER, PKTABLE\_NAME,
and KEY\_SEQ. The following table lists the columns in the result set. 

\begin{twocollist}\itemsep=0pt
\twocolitem{0 (VARCHAR)}{PKTABLE\_QUALIFIER}
\twocolitem{1 (VARCHAR)}{PKTABLE\_OWNER}
\twocolitem{2 (VARCHAR)}{PKTABLE\_NAME}
\twocolitem{3 (VARCHAR)}{PKCOLUMN\_NAME}
\twocolitem{4 (VARCHAR)}{FKTABLE\_QUALIFIER}
\twocolitem{5 (VARCHAR)}{FKTABLE\_OWNER}
\twocolitem{6 (VARCHAR)}{FKTABLE\_NAME}
\twocolitem{7 (VARCHAR)}{FKCOLUMN\_NAME}
\twocolitem{8 (SMALLINT)}{KEY\_SEQ}
\twocolitem{9 (SMALLINT)}{UPDATE\_RULE}
\twocolitem{10 (SMALLINT)}{DELETE\_RULE}
\twocolitem{11 (VARCHAR)}{FK\_NAME}
\twocolitem{12 (VARCHAR)}{PK\_NAME}
\end{twocollist}

\membersection{wxRecordSet::GetNumberCols}

\func{long}{GetNumberCols}{\void}

Returns the number of columns in the result set.
  
\membersection{wxRecordSet::GetNumberFields}

\func{int}{GetNumberFields}{\void}

Not implemented.

\membersection{wxRecordSet::GetNumberParams}

\func{int}{GetNumberParams}{\void}

Not implemented.

\membersection{wxRecordSet::GetNumberRecords}

\func{long}{GetNumberRecords}{\void}

Returns the number of records in the result set.
  
\membersection{wxRecordSet::GetPrimaryKeys}

\func{bool}{GetPrimaryKeys}{\param{const wxString\& }{table = NULL}}

Returns the column names that comprise the primary key of the table with the specified name. If no name is
given the class member {\it tablename} will be used. If both names are NULL
nothing will happen. The data will be presented as a normal result set, organized
as follows:

\begin{twocollist}\itemsep=0pt
\twocolitem{0 (VARCHAR)}{TABLE\_QUALIFIER}
\twocolitem{1 (VARCHAR)}{TABLE\_OWNER}
\twocolitem{2 (VARCHAR)}{TABLE\_NAME}
\twocolitem{3 (VARCHAR)}{COLUMN\_NAME}
\twocolitem{4 (SMALLINT)}{KEY\_SEQ}
\twocolitem{5 (VARCHAR)}{PK\_NAME}
\end{twocollist}

\membersection{wxRecordSet::GetOptions}

\func{int}{GetOptions}{\void}

Returns the options of the wxRecordSet. Options are not supported yet.

\membersection{wxRecordSet::GetResultSet}

\func{bool}{GetResultSet}{\void}

Copies the data presented by ODBC into wxRecordSet. Depending on the
wxRecordSet type all or only one record(s) will be copied.
Usually this function will be called automatically after each successful
database operation.
  
\membersection{wxRecordSet::GetSortString}

\func{wxString}{GetSortString}{\void}

Not implemented.
  
\membersection{wxRecordSet::GetSQL}

\func{wxString}{GetSQL}{\void}

Not implemented.

\membersection{wxRecordSet::GetTableName}

\func{wxString}{GetTableName}{\void}

Returns the name of the current table.
  
\membersection{wxRecordSet::GetTables}

\func{bool}{GetTables}{\void}

Gets the tables of a database. The data will be presented as a normal result
set, organized as follows:

\begin{twocollist}\itemsep=0pt
\twocolitem{0 (VARCHAR)}{TABLE\_QUALIFIER}
\twocolitem{1 (VARCHAR)}{TABLE\_OWNER}
\twocolitem{2 (VARCHAR)}{TABLE\_NAME}
\twocolitem{3 (VARCHAR)}{TABLE\_TYPE (TABLE, VIEW, SYSTEM TABLE, GLOBAL TEMPORARY, LOCAL TEMPORARY,
ALIAS, SYNONYM, or database-specific type)}
\twocolitem{4 (VARCHAR)}{REMARKS}
\end{twocollist}

\membersection{wxRecordSet::GetType}

\func{int}{GetType}{\void}

Returns the type of the wxRecordSet: wxOPEN\_TYPE\_DYNASET or
wxOPEN\_TYPE\_SNAPSHOT. See the wxRecordSet description for details.

\membersection{wxRecordSet::GoTo}

\func{bool}{GoTo}{\param{long}{ n}}

Moves the cursor to the record with the number n, where  the first record
has the number 0.
  
\membersection{wxRecordSet::IsBOF}

\func{bool}{IsBOF}{\void}

Returns true if the user tried to move the cursor before the first record
in the set.

\membersection{wxRecordSet::IsFieldDirty}

\func{bool}{IsFieldDirty}{\param{int}{ field}}

Returns true if the given field has been changed but not saved yet.

\func{bool}{IsFieldDirty}{\param{const wxString\& }{name}}

Same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::IsFieldNull}

\func{bool}{IsFieldNull}{\param{int}{ field}}

Returns true if the given field has no data.

\func{bool}{IsFieldNull}{\param{const wxString\& }{ name}}

Same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::IsColNullable}

\func{bool}{IsColNullable}{\param{int}{ col}}

Returns true if the given column may contain no data.

\func{bool}{IsColNullable}{\param{const wxString\& }{name}}

Same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::IsEOF}

\func{bool}{IsEOF}{\void}

Returns true if the user tried to move the cursor behind the last record
in the set.

\membersection{wxRecordSet::IsDeleted}

\func{bool}{IsDeleted}{\void}

Not implemented.
  
\membersection{wxRecordSet::IsOpen}

\func{bool}{IsOpen}{\void}

Returns true if the parent database is open.

\membersection{wxRecordSet::Move}

\func{bool}{Move}{\param{long}{ rows}}

Moves the cursor a given number of rows. Negative values are allowed.
  
\membersection{wxRecordSet::MoveFirst}

\func{bool}{MoveFirst}{\void}

Moves the cursor to the first record.
  
\membersection{wxRecordSet::MoveLast}

\func{bool}{MoveLast}{\void}

Moves the cursor to the last record.
  
\membersection{wxRecordSet::MoveNext}\label{wxrecordsetmovenext}

\func{bool}{MoveNext}{\void}

Moves the cursor to the next record.
  
\membersection{wxRecordSet::MovePrev}\label{wxrecordsetmoveprev}

\func{bool}{MovePrev}{\void}

Moves the cursor to the previous record.
  
\membersection{wxRecordSet::Query}

\func{bool}{Query}{\param{const wxString\& }{columns}, \param{const wxString\& }{table}, \param{const wxString\& }{filter = NULL}}

Start a query. An SQL string of the following type will automatically be
generated and executed: ``SELECT columns FROM table WHERE filter".

\membersection{wxRecordSet::RecordCountFinal}

\func{bool}{RecordCountFinal}{\void}

Not implemented.
  
\membersection{wxRecordSet::Requery}

\func{bool}{Requery}{\void}

Re-executes the last query. Not implemented.

\membersection{wxRecordSet::SetFieldDirty}

\func{void}{SetFieldDirty}{\param{int}{ field}, \param{bool}{ dirty = true}}

Sets the dirty tag of the field field. Not implemented.

\func{void}{SetFieldDirty}{\param{const wxString\& }{name}, \param{bool}{ dirty = true}}

Same as above, but uses the column name as the identifier.

\membersection{wxRecordSet::SetDefaultSQL}

\func{void}{SetDefaultSQL}{\param{const wxString\& }{s}}

Not implemented.

\membersection{wxRecordSet::SetFieldNull}

\func{void}{SetFieldNull}{\param{void *}{p}, \param{bool }{isNull = true}}

Not implemented.

\membersection{wxRecordSet::SetOptions}

\func{void}{SetOptions}{\param{int}{ opt}}

Sets the options of the wxRecordSet. Not implemented.
  
\membersection{wxRecordSet::SetTableName}

\func{void}{SetTableName}{\param{const wxString\& }{tablename}}

Specify the name of the table you want to use.
  
\membersection{wxRecordSet::SetType}

\func{void}{SetType}{\param{int}{ type}}

Sets the type of the wxRecordSet. See the wxRecordSet class description for details.

\membersection{wxRecordSet::Update}

\func{bool}{Update}{\void}

Writes back the current record. Not implemented.