docs/latex/wx/database.tex

   1 \section{\class{wxDatabase}}\label{wxdatabase}
   2
   3 Every database object represents an ODBC connection.
   4 The connection may be closed and reopened.
   5
   6 \wxheading{Derived from}
   7
   8 \helpref{wxObject}{wxobject}
   9
  10 \wxheading{Include files}
  11
  12 <wx/odbc.h>
  13
  14 \wxheading{See also}
  15
  16 \overview{wxDatabase overview}{wxdatabaseoverview}, \helpref{wxRecordSet}{wxrecordset}
  17
  18 A much more robust and feature-rich set of ODBC classes is now
  19 available and recommended for use in place of the wxDatabase class.
  20
  21 See details of these classes in:
  22 \helpref{wxDB}{wxdb}, \helpref{wxTable}{wxtable}
  23
  24 \latexignore{\rtfignore{\wxheading{Members}}}
  25
  26 \membersection{wxDatabase::wxDatabase}
  27
  28 \func{}{wxDatabase}{\void}
  29
  30 Constructor. The constructor of the first wxDatabase instance of an
  31 application initializes the ODBC manager.
  32
  33 \membersection{wxDatabase::\destruct{wxDatabase}}
  34
  35 \func{}{\destruct{wxDatabase}}{\void}
  36
  37 Destructor. Resets and destroys any associated wxRecordSet instances.
  38
  39 The destructor of the last wxDatabase instance will deinitialize
  40 the ODBC manager.
  41
  42 \membersection{wxDatabase::BeginTrans}
  43
  44 \func{bool}{BeginTrans}{\void}
  45
  46 Not implemented.
  47
  48 \membersection{wxDatabase::Cancel}
  49
  50 \func{void}{Cancel}{\void}
  51
  52 Not implemented.
  53
  54 \membersection{wxDatabase::CanTransact}
  55
  56 \func{bool}{CanTransact}{\void}
  57
  58 Not implemented.
  59
  60
  61 \membersection{wxDatabase::CanUpdate}
  62
  63 \func{bool}{CanUpdate}{\void}
  64
  65 Not implemented.
  66
  67 \membersection{wxDatabase::Close}
  68
  69 \func{bool}{Close}{\void}
  70
  71 Resets the statement handles of any associated wxRecordSet objects,
  72 and disconnects from the current data source.
  73
  74 \membersection{wxDatabase::CommitTrans}
  75
  76 \func{bool}{CommitTrans}{\void}
  77
  78 Commits previous transactions. Not implemented.
  79
  80 \membersection{wxDatabase::ErrorOccured}
  81
  82 \func{bool}{ErrorOccured}{\void}
  83
  84 Returns TRUE if the last action caused an error.
  85
  86 \membersection{wxDatabase::ErrorSnapshot}
  87
  88 \func{void}{ErrorSnapshot}{\param{HSTMT}{ statement = SQL\_NULL\_HSTMT}}
  89
  90 This function will be called whenever an ODBC error occured. It stores the
  91 error related information returned by ODBC. If a statement handle of the
  92 concerning ODBC action is available it should be passed to the function.
  93
  94 \membersection{wxDatabase::GetDatabaseName}
  95
  96 \func{wxString}{GetDatabaseName}{\void}
  97
  98 Returns the name of the database associated with the current connection.
  99
 100 \membersection{wxDatabase::GetDataSource}
 101
 102 \func{wxString}{GetDataSource}{\void}
 103
 104 Returns the name of the connected data source.
 105
 106 \membersection{wxDatabase::GetErrorClass}
 107
 108 \func{wxString}{GetErrorClass}{\void}
 109
 110 Returns the error class of the last error. The error class consists of
 111 five characters where the first two characters contain the class
 112 and the other three characters contain the subclass of the ODBC error.
 113 See ODBC documentation for further details.
 114
 115 \membersection{wxDatabase::GetErrorCode}
 116
 117 \func{wxRETCODE}{GetErrorCode}{\void}
 118
 119 Returns the error code of the last ODBC function call. This will be one of:
 120
 121 \begin{twocollist}\itemsep=0pt
 122 \twocolitem{SQL\_ERROR}{General error.}
 123 \twocolitem{SQL\_INVALID\_HANDLE}{An invalid handle was passed to an ODBC function.}
 124 \twocolitem{SQL\_NEED\_DATA}{ODBC expected some data.}
 125 \twocolitem{SQL\_NO\_DATA\_FOUND}{No data was found by this ODBC call.}
 126 \twocolitem{SQL\_SUCCESS}{The call was successful.}
 127 \twocolitem{SQL\_SUCCESS\_WITH\_INFO}{The call was successful, but further information can be
 128 obtained from the ODBC manager.}
 129 \end{twocollist}
 130
 131 \membersection{wxDatabase::GetErrorMessage}
 132
 133 \func{wxString}{GetErrorMessage}{\void}
 134
 135 Returns the last error message returned by the ODBC manager.
 136
 137 \membersection{wxDatabase::GetErrorNumber}
 138
 139 \func{long}{GetErrorNumber}{\void}
 140
 141 Returns the last native error. A native error is an ODBC driver dependent
 142 error number.
 143
 144 \membersection{wxDatabase::GetHDBC}
 145
 146 \func{HDBC}{GetHDBC}{\void}
 147
 148 Returns the current ODBC database handle.
 149
 150 \membersection{wxDatabase::GetHENV}
 151
 152 \func{HENV}{GetHENV}{\void}
 153
 154 Returns the ODBC environment handle.
 155
 156 \membersection{wxDatabase::GetInfo}
 157
 158 \func{bool}{GetInfo}{\param{long}{ infoType}, \param{long *}{buf}}
 159
 160 \func{bool}{GetInfo}{\param{long}{ infoType}, \param{const wxString\& }{buf}, \param{int}{ bufSize=-1}}
 161
 162 Returns requested information. The return value is TRUE if successful, FALSE otherwise.
 163
 164 {\it infoType} is an ODBC identifier specifying the type of information to be returned.
 165
 166 {\it buf} is a character or long integer pointer to storage which must be allocated by the
 167 application, and which will contain the information if the function is successful.
 168
 169 {\it bufSize} is the size of the character buffer. A value of -1 indicates that the size
 170 should be computed by the GetInfo function.
 171
 172 \membersection{wxDatabase::GetPassword}
 173
 174 \func{wxString}{GetPassword}{\void}
 175
 176 Returns the password of the current user.
 177
 178 \membersection{wxDatabase::GetUsername}
 179
 180 \func{wxString}{GetUsername}{\void}
 181
 182 Returns the current username.
 183
 184 \membersection{wxDatabase::GetODBCVersionFloat}
 185
 186 \func{float}{GetODBCVersionFloat}{\param{bool}{ implementation=TRUE}}
 187
 188 Returns the version of ODBC in floating point format, e.g. 2.50.
 189
 190 {\it implementation} should be TRUE to get the DLL version, or FALSE to get the
 191 version defined in the {\tt sql.h} header file.
 192
 193 This function can return the value 0.0 if the header version number is not defined (for early
 194 versions of ODBC).
 195
 196 \membersection{wxDatabase::GetODBCVersionString}
 197
 198 \func{wxString}{GetODBCVersionString}{\param{bool}{ implementation=TRUE}}
 199
 200 Returns the version of ODBC in string format, e.g. ``02.50".
 201
 202 {\it implementation} should be TRUE to get the DLL version, or FALSE to get the
 203 version defined in the {\tt sql.h} header file.
 204
 205 This function can return the value ``00.00" if the header version number is not defined (for early
 206 versions of ODBC).
 207
 208 \membersection{wxDatabase::InWaitForDataSource}
 209
 210 \func{bool}{InWaitForDataSource}{\void}
 211
 212 Not implemented.
 213
 214 \membersection{wxDatabase::IsOpen}
 215
 216 \func{bool}{IsOpen}{\void}
 217
 218 Returns TRUE if a connection is open.
 219
 220 \membersection{wxDatabase::Open}\label{wxdatabaseopen}
 221
 222 \func{bool}{Open}{\param{const wxString\& }{datasource}, \param{bool}{ exclusive = FALSE}, \param{bool }{readOnly = TRUE},
 223  \param{const wxString\& }{username = ``ODBC"}, \param{const wxString\& }{password = ``"}}
 224
 225 Connect to a data source. {\it datasource} contains the name of the ODBC data
 226 source. The parameters exclusive and readOnly are not used.
 227
 228 \membersection{wxDatabase::OnSetOptions}
 229
 230 \func{void}{OnSetOptions}{\param{wxRecordSet *}{recordSet}}
 231
 232 Not implemented.
 233
 234 \membersection{wxDatabase::OnWaitForDataSource}
 235
 236 \func{void}{OnWaitForDataSource}{\param{bool}{ stillExecuting}}
 237
 238 Not implemented.
 239
 240 \membersection{wxDatabase::RollbackTrans}
 241
 242 \func{bool}{RollbackTrans}{\void}
 243
 244 Sends a rollback to the ODBC driver. Not implemented.
 245
 246 \membersection{wxDatabase::SetDataSource}
 247
 248 \func{void}{SetDataSource}{\param{const wxString\& }{s}}
 249
 250 Sets the name of the data source. Not implemented.
 251
 252 \membersection{wxDatabase::SetLoginTimeout}
 253
 254 \func{void}{SetLoginTimeout}{\param{long}{ seconds}}
 255
 256 Sets the time to wait for an user login. Not implemented.
 257
 258 \membersection{wxDatabase::SetPassword}
 259
 260 \func{void}{SetPassword}{\param{const wxString\& }{s}}
 261
 262 Sets the password of the current user. Not implemented.
 263
 264 \membersection{wxDatabase::SetSynchronousMode}
 265
 266 \func{void}{SetSynchronousMode}{\param{bool }{synchronous}}
 267
 268 Toggles between synchronous and asynchronous mode. Currently only synchronous
 269 mode is supported, so this function has no effect.
 270
 271 \membersection{wxDatabase::SetQueryTimeout}
 272
 273 \func{void}{SetQueryTimeout}{\param{long}{ seconds}}
 274
 275 Sets the time to wait for a response to a query. Not implemented.
 276
 277 \membersection{wxDatabase::SetUsername}
 278
 279 \func{void}{SetUsername}{\param{const wxString\& }{s}}
 280
 281 Sets the name of the current user. Not implemented.
 282
 283