.\" This is a wxWidgets manpage page generated from the XML docs .TH wxDbTable 3wx 2005-02-15 "wxWidgets" "wxWidgets class documentation" .SH NAME wxDbTable \- Provides access to a database table .SH DESCRIPTION A wxDbTable instance provides re-usable access to rows of data in a table contained within the associated ODBC datasource See the database classes overview for an introduction to using the ODBC classes. .SH "PARENTS" .SH "INCLUDE FILES" wx/dbtable.hwx/db.h .SH MEMBERS .SS wxDbTable (wxDb *pwxDbconst wxString &tblNameconst UWORD numColumnsconst wxString &qryTblName = ""bool qryOnly = !wxDB_QUERY_ONLYconst wxString &tblPath = "") Default constructor. .SS virtual ~wxDbTable () Virtual default destructor. .SS void BuildDeleteStmt (wxString &pSqlStmtint typeOfDelconst wxString &pWhereClause = "") Constructs the full SQL statement that can be used to delete all rows matching the criteria in the pWhereClause. .SS void BuildSelectStmt (wxString &pSqlStmtint typeOfSelectbool distinct) Constructs the full SQL statement that can be used to select all rows matching the criteria in the pWhereClause. This function is called internally in the wxDbTable class whenever the function wxDbTable::Query is called. NOTE: Only the columns specified in wxDbTable::SetColDefs statements are included in the list of columns returned by the SQL statement created by a call to this function. .SS void BuildUpdateStmt (wxString &pSqlStmtint typeOfUpdconst wxString &pWhereClause = "") Constructs the full SQL statement that can be used to update all rows matching the criteria in the pWhereClause. If typeOfUpdate is DB_UPD_KEYFIELDS, then the current values in the bound columns are used to determine which row(s) in the table are to be updated. The exception to this is when a datasource supports ROW IDs (Oracle). The ROW ID column is used for efficiency purposes when available. NOTE: Only the columns specified in wxDbTable::SetColDefs statements are included in the list of columns updated by the SQL statement created by a call to this function. Any column definitions that were defined as being non-updateable will be excluded from the SQL UPDATE statement created by this function. .SS void BuildWhereClause (wxString &pWhereClauseint typeOfWhereconst wxString &qualTableName = ""bool useLikeComparison = false) Constructs the portion of a SQL statement which would follow the word 'WHERE' in a SQL statement to be passed to the datasource. The returned string does NOT include the word 'WHERE'. .SS bool CanSelectForUpdate () Use this function to determine if the datasource supports SELECT ... FOR UPDATE. When the keywords "FOR UPDATE" are included as part of your SQL SELECT statement, all records retrieved (not just queried, but actually retrieved using wxDbTable::GetNext , etc) from the result set are locked. .SS bool CanUpdateByROWID () CURRENTLY ONLY POSSIBLE IF USING ORACLE. --- CURRENTLY DISABLED FOR *ALL* DATASOURCES --- NOV 1 2000 - gt Every Oracle table has a hidden column named ROWID. This is a pointer to the physical location of the record in the datasource and allows for very fast updates and deletes. The key is to retrieve this ROWID during your query so it is available during an update or delete operation. Use of the ROWID feature is always handled by the class library except in the case of wxDbTable::QueryBySqlStmt . Since you are passing in the SQL SELECT statement, it is up to you to include the ROWID column in your query. If you do not, the application will still work, but may not be as optimized. The ROWID is always the last column in the column list in your SQL SELECT statement. The ROWID is not a column in the normal sense and should not be considered part of the column definitions for the wxDbTable object. .SS void ClearMemberVar (UWORD colNumberbool setToNull = false) Same as wxDbTable::ClearMemberVars except that this function clears only the specified column of its values, and optionally sets the column to be a NULL column. .SS void ClearMemberVars (bool setToNull = false) Initializes all bound columns of the wxDbTable instance to zero. In the case of a string, zero is copied to the first byte of the string. .SS bool CloseCursor (HSTMTcursor) Closes the specified cursor associated with the wxDbTable object. .SS ULONG Count (const wxString &args = "*") Returns the number of records which would be in the result set using the current query parameters specified in the WHERE and FROM clauses. .SS bool CreateIndex (const wxString &IndexNamebool uniqueUWORD numIndexColumnswxDbIdxDef *pIndexDefsbool attemptDrop = true) This member function allows you to create secondary (non primary) indexes on your tables. You first create your table, normally specifying a primary index, and then create any secondary indexes on the table. Indexes in relational model are not required. You do not need indexes to look up records in a table or to join two tables together. In the relational model, indexes, if available, provide a quicker means to look up data in a table. To enjoy the performance benefits of indexes, the indexes must be defined on the appropriate columns and your SQL code must be written in such a way as to take advantage of those indexes. .SS bool CreateTable (bool attemptDrop = true) Creates a table based on the definitions previously defined for this wxDbTable instance. .SS bool DB_STATUS () Accessor function that returns the wxDb private member variable DB_STATUS for the database connection used by this instance of wxDbTable. .SS bool Delete () Deletes the row from the table indicated by the current cursor. .SS bool DeleteCursor (HSTMT *hstmtDel) Allows a program to delete a cursor. .SS bool DeleteMatching () This member function allows you to delete records from your wxDbTable object by specifying the data in the columns to match on. .SS bool DeleteWhere (const wxString &pWhereClause) Deletes all rows from the table which match the criteria specified in the WHERE clause that is passed in. .SS bool DropIndex (const wxString &IndexName) Allows an index on the associated table to be dropped (deleted) if the user login has sufficient privileges to do so. .SS bool DropTable () Deletes the associated table if the user has sufficient privileges to do so. .SS const wxString & From () .SS void From (const wxString &From) Accessor function for the private class member wxDbTable::from. Can be used as a synonym for wxDbTable::GetFromClause (the first form of this function) or wxDbTable::SetFromClause (the second form of this function). .SS wxDbColDef * GetColDefs () Accessor function that returns a pointer to the array of column definitions that are bound to the columns that this wxDbTable instance is associated with. To determine the number of elements pointed to by the returned wxDbColDef pointer, use the wxDbTable::GetNumberOfColumns function. .SS HSTMT GetCursor () .SS wxDb * GetDb () Accessor function for the private member variable pDb which is a pointer to the datasource connection that this wxDbTable instance uses. .SS bool GetFirst () Retrieves the FIRST row in the record set as defined by the current query. Before retrieving records, a query must be performed using wxDbTable::Query , wxDbTable::QueryOnKeyFields , wxDbTable::QueryMatching or wxDbTable::QueryBySqlStmt . .SS const wxString & GetFromClause () Accessor function that returns the current FROM setting assigned with the wxDbTable::SetFromClause . .SS bool GetLast () Retrieves the LAST row in the record set as defined by the current query. Before retrieving records, a query must be performed using wxDbTable::Query , wxDbTable::QueryOnKeyFields , wxDbTable::QueryMatching or wxDbTable::QueryBySqlStmt . .SS HSTMT * GetNewCursor (bool setCursor = falsebool bindColumns = true) This function will create a new cursor that can be used to access the table being referenced by this wxDbTable instance, or to execute direct SQL commands on without affecting the cursors that are already defined and possibly positioned. .SS bool GetNext () Retrieves the NEXT row in the record set after the current cursor position as defined by the current query. Before retrieving records, a query must be performed using wxDbTable::Query , wxDbTable::QueryOnKeyFields , wxDbTable::QueryMatching or wxDbTable::QueryBySqlStmt . .SS UWORD GetNumberOfColumns () Accessor function that returns the number of columns that are statically bound for access by the wxDbTable instance. .SS const wxString & GetOrderByClause () Accessor function that returns the current ORDER BY setting assigned with the wxDbTable::SetOrderByClause . .SS bool GetPrev () Retrieves the PREVIOUS row in the record set before the current cursor position as defined by the current query. Before retrieving records, a query must be performed using wxDbTable::Query , wxDbTable::QueryOnKeyFields , wxDbTable::QueryMatching or wxDbTable::QueryBySqlStmt . .SS const wxString & GetQueryTableName () Accessor function that returns the name of the table/view that was indicated as being the table/view to query against when this wxDbTable instance was created. .SS UWORD GetRowNum () Returns the ODBC row number for performing positioned updates and deletes. .SS const wxString & GetTableName () Accessor function that returns the name of the table that was indicated as being the table that this wxDbTable instance was associated with. .SS const wxString & GetTablePath () Accessor function that returns the path to the data table that was indicated during creation of this wxDbTable instance. .SS const wxString & GetWhereClause () Accessor function that returns the current WHERE setting assigned with the wxDbTable::SetWhereClause .SS int Insert () Inserts a new record into the table being referenced by this wxDbTable instance. The values in the member variables of the wxDbTable instance are inserted into the columns of the new row in the database. .SS bool IsColNull (UWORD colNumber) const Used primarily in the ODBC class library to determine if a column value is set to "NULL". Works for all data types supported by the ODBC class library. .SS bool IsCursorClosedOnCommit () Accessor function to return information collected during the opening of the datasource connection that is used by this wxDbTable instance. The result returned by this function indicates whether an implicit closing of the cursor is done after a commit on the database connection. .SS bool IsQueryOnly () Accessor function that returns a value indicating if this wxDbTable instance was created to allow only queries to be performed on the bound columns. If this function returns true, then no actions may be performed using this wxDbTable instance that would modify (insert/delete/update) the table's data. .SS bool Open (bool checkPrivileges = falsebool checkTableExists = true) Every wxDbTable instance must be opened before it can be used. This function checks for the existence of the requested table, binds columns, creates required cursors, (insert/select and update if connection is not wxDB_QUERY_ONLY) and constructs the insert statement that is to be used for inserting data as a new row in the datasource. NOTE: To retrieve data into an opened table, the of the table must be bound to the variables in the program via call(s) to wxDbTable::SetColDefs before calling Open(). See the database classes overview for an introduction to using the ODBC classes. .SS const wxString & OrderBy () .SS void OrderBy (const wxString &OrderBy) Accessor function for the private class member wxDbTable::orderBy. Can be used as a synonym for wxDbTable::GetOrderByClause (the first form of this function) or wxDbTable::SetOrderByClause (the second form of this function). .SS virtual bool Query (bool forUpdate = falsebool distinct = false) .SS bool QueryBySqlStmt (const wxString &pSqlStmt) Performs a query against the datasource by accepting and passing verbatim the SQL SELECT statement passed to the function. .SS virtual bool QueryMatching (bool forUpdate = falsebool distinct = false) QueryMatching allows querying of records from the table associated with the wxDbTable object by matching "columns" to values. For example: To query the datasource for the row with a PART_NUMBER column value of "32", clear all column variables of the wxDbTable object, set the PartNumber variable that is bound to the PART_NUMBER column in the wxDbTable object to "32", and then call wxDbTable::QueryMatching(). .SS bool QueryOnKeyFields (bool forUpdate = falsebool distinct = false) QueryOnKeyFields provides an easy mechanism to query records in the table associated with the wxDbTable object by the primary index column(s). Simply assign the primary index column(s) values and then call this member function to retrieve the record. Note that since primary indexes are always unique, this function implicitly always returns a single record from the database. The base table name is prepended to the column names in the event that the wxDbTable's FROM clause is non-null. .SS bool Refresh () This function re-reads the bound columns into the memory variables, setting them to the current values stored on the disk. The cursor position and result set are unaffected by calls to this function. (The one exception is in the case where the record to be refreshed has been deleted by some other user or transaction since it was originally retrieved as part of the result set. For most datasources, the default behavior in this situation is to return the value that was originally queried for the result set, even though it has been deleted from the database. But this is datasource dependent, and should be tested before relying on this behavior.) .SS bool SetColDefs (UWORD indexconst wxString &fieldNameint dataTypevoid *pDataSWORD cTypeint sizebool keyField = falsebool updateable = truebool insertAllowed = truebool derivedColumn = false) .SS wxDbColDataPtr * SetColDefs (wxDbColInf *colInfsUWORD numCols) DB_DATA_TYPE_VARCHAR : strings DB_DATA_TYPE_INTEGER : non-floating point numbers DB_DATA_TYPE_FLOAT : floating point numbers DB_DATA_TYPE_DATE : dates SQL_C_CHAR // string - deprecated: use SQL_C_WXCHAR SQL_C_WXCHAR // string - Used transparently in unicode or non-unicode builds SQL_C_LONG SQL_C_ULONG SQL_C_SHORT SQL_C_USHORT SQL_C_FLOAT SQL_C_DOUBLE SQL_C_NUMERIC SQL_C_TIMESTAMP SQL_C_BOOLEAN // defined in db.h SQL_C_ENUM // defined in db.h .SS void SetCursor (HSTMT *hstmtActivate = (void) .SS void SetFromClause (const wxString &From) Accessor function for setting the private class member wxDbTable::from that indicates what other tables should be outer joined with the wxDbTable's base table for access to the columns in those other tables. Synonym to this function is one form of wxDbTable::From .SS bool SetColNull (UWORD colNumberbool set = true) .SS bool SetColNull (const wxString &colNamebool set = true) Both forms of this function allow a member variable representing a column in the table associated with this wxDbTable object to be set to NULL. The first form allows the column to be set by the index into the column definitions used to create the wxDbTable instance, while the second allows the actual column name to be specified. .SS void SetOrderByClause (const wxString &OrderBy) Accessor function for setting the private class member wxDbTable::orderBy which determines sequence/ordering of the rows returned in the result set of a query. A synonym to this function is one form of the function wxDbTable::OrderBy .SS bool SetQueryTimeout (UDWORD nSeconds) Allows a time period to be set as the timeout period for queries. .SS void SetWhereClause (const wxString &Where) Accessor function for setting the private class member wxDbTable::where that determines which rows are returned in the result set by the datasource. A synonym to this function is one form of the function wxDbTable::Where .SS bool Update () .SS bool Update (const wxString &pSqlStmt) The first form of this function will update the row that the current cursor is currently positioned at with the values in the memory variables that are bound to the columns. The actual SQL statement to perform the update is automatically created by the ODBC class, and then executed. The second form of the function allows full access through SQL statements for updating records in the database. Write any valid SQL UPDATE statement and submit it to this function for execution. Sophisticated updates can be performed using the full power of the SQL dialect. The full SQL statement must have the exact syntax required by the driver/datasource for performing the update. This usually is in the form of: UPDATE tablename SET col1=X, col2=Y, ... where ... .SS bool UpdateWhere (const wxString &pWhereClause) Performs updates to the base table of the wxDbTable object, updating only the rows which match the criteria specified in the pWhereClause . All columns that are bound to member variables for this wxDbTable instance that were defined with the "updateable" parameter set to true will be updated with the information currently held in the memory variable. .SS const wxString & Where () .SS void Where (const wxString& Where) Accessor function for the private class member wxDbTable::where. Can be used as a synonym for wxDbTable::GetWhereClause (the first form of this function) to return the current where clause or wxDbTable::SetWhereClause (the second form of this function) to set the where clause for this table instance. .SS bool operator ++ () Synonym for wxDbTable::GetNext .SS bool operator -- () Synonym for wxDbTable::GetPrev .SH "SEE ALSO" .SH "AUTHORS" Documentation content by Julian Smart, Robert Roebling, Vadim Zeitlin, Robin Dunn, et al Conversion to manpage format by Arnout Engelen (http://bzzt.net), bugreports welcome.