wxJavaScript : db

back to db

wxDb

^{generated from ../src/mod_db/db.cpp}

A wxDb instance is a connection to an ODBC datasource which may be opened, closed, and re-opened an unlimited number of times. A database connection allows function to be performed directly on the datasource, as well as allowing access to any tables/views defined in the datasource to which the user has sufficient privileges.

See also: wxDbConnectInf, wxDbTable

Constants

DATA_TYPE

Name	Description
DATA_TYPE_VARCHAR
DATA_TYPE_INTEGER
DATA_TYPE_FLOAT
DATA_TYPE_DATE
DATA_TYPE_BLOB

GRANT_TYPE

Name	Description
GRANT_SELECT
GRANT_INSERT
GRANT_UPDATE
GRANT_DELETE
GRANT_ALL

Class Properties

Name	Type	Description
SQL_CATALOG_FILENAME	String	Gets the name of the catalogfile
SQL_LOG_FILENAME	String	Gets the name of the logfile
connectionsInUse	Integer	Gets the number of connections in the cache that are used.

Constructor

wxDb

wxDb(Connection)

Name	Type	Default	Description
Connection	wxDbConnectInf		This is used to get the HENV variable

Properties

Name	Type	Description
databaseName	String	Gets the name of the database engine
datasourceName	String	Gets the name of the datasource
errorList	String Array	Gets an array with the last occurred errors
isFwdOnlyCursors	boolean	This setting indicates whether this database connection was created as being capable of using only forward scrolling cursors. This property does NOT indicate if the ODBC driver or datasource supports backward scrolling cursors. There is no standard way of detecting if the driver or datasource can support backward scrolling cursors. If a wxDb instance was created as being capable of only forward scrolling cursors, then even if the datasource and ODBC driver support backward scrolling cursors, tables using this database connection would only be able to use forward scrolling cursors.
opened	boolean	Returns true when the connection is open.
password	String	The password used to establish this connection.
tableCount	Integer	Number of tables currently in use by this datasource connection.
username	String	The username used to establish this connection.

Methods

catalog

catalog(userId, 
        fileName = wxDb.SQL_CATALOG_FILENAME) : Boolean

Name	Type	Default	Description
userId	String		Database user name to use in accessing the database. All tables to which this user has rights will be evaluated in the catalog.
fileName	String	wxDb.SQL_CATALOG_FILENAME	Name of the textfile to create. When not set, the default is retrieved from wxDb.SQL_CATALOG_FILENAME.

close

close()

Closes the database. Make sure that all tables are closed before you call this. In normal circumstances you don't need to close a database. A database is closed automatically, but some databases doesn't update the data correctly without closing the database manually (FireFox for example).

commitTrans

commitTrans() : Boolean

Permanently "commits" changes (insertions/deletions/updates) to the database. Returns true if the commit was successful, or false if the commit failed.

Remarks: Transactions begin implicitly as soon as you make a change to the database with an insert/update/delete, or any other direct SQL command that performs one of these operations against the datasource. At any time thereafter, to save the changes to disk permanently, "commit" them by calling this function. Calling this member function commits ALL open transactions on this ODBC connection. For example, if three different wxDbTable instances used the same connection to the datasource, committing changes made on one of those wxDbTable instances commits any pending transactions on all three wxDbTable instances. Until a call to commitTrans() is made, no other user or cursor is able to see any changes made to the row(s) that have been inserted/modified/deleted.

createView

createView(Name, 
           Columns, 
           SqlStmt)

Name	Type	Description
Name	String	The name of the view
Columns	String	A comma delimited list of column names. Use this when you wish to explicitly name each columnin the result set. If not desired, pass in an empty string and the column names from the associated table(s) will be used.
SqlStmt	string	select statement portion of the CREATE VIEW statement. Must be a complete, valid SQL SELECT statement.

dropView

dropView(Name) : Boolean

Name	Type	Default	Description
Name	String		The name of the view

execSql

execSql(Stmt) : Boolean

Name	Type	Default	Description
Stmt	String		A valid SQL statement

getCatalog

getCatalog(userId = null) : wxDbInf

Name	Type	Default	Description
userId	String	null	Name of the user that owns the table(s) (also referred to as schema). Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. userID is evaluated in the following manner: userID == null (or not given) ... userID is ignored (DEFAULT) userID == "" ... userID set equal to username userID != "" ... userID set equal to 'userID'

getColumnCount

getColumnCount(TableName, 
               userId) : Integer

Name	Type	Default	Description
TableName	String		The table name you wish to obtain column information about.
userId	String		Name of the user that owns the table(s) (also referred to as schema). Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. userID is evaluated in the following manner: userID == null (or not given) ... userID is ignored (DEFAULT) userID == "" ... userID set equal to username userID != "" ... userID set equal to 'userID'

getColumns

getColumns(TableName, 
           userId = null) : wxDbColInf array

Name	Type	Default	Description
TableName	String		The table name you wish to obtain column information about.
userId	String	null	Name of the user that owns the table(s) (also referred to as schema). Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. userID is evaluated in the following manner : userID == null (or not given) ... userID is ignored (DEFAULT) userID == "" ... userID set equal to username userID != "" ... userID set equal to 'userID'

getColumns(TableNamesArray, 
           userId = null) : wxDbColInf array

Name	Type	Default	Description
TableNamesArray	String array		An array of tablenames
userId	String	null	Name of the user that owns the table(s) (also referred to as schema). Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. userID is evaluated in the following manner : userID == null (or not given) ... userID is ignored (DEFAULT) userID == "" ... userID set equal to username userID != "" ... userID set equal to 'userID'

Returns a wxDbColInf object. If an error occurs, count will be 0. The following example gets the column information of two tables:

getNext

getNext() : boolean

Called after executing a query, this function requests the next row in the result set after the current position of the cursor.

grant

grant(Privileges, 
      TableName, 
      Username) : Boolean

Name	Type	Description
Privileges	Integer	See GRANT_TYPE constants
TableName	String	Tablename
Username	String	A comma delimited list of users to grant the privileges to. When omitted, the privileges will be given to the general PUBLIC.

Use this to GRANT privileges to users for accessing tables in the datasource. The currently logged in user must have sufficient grantor privileges for this function to be able to successfully grant the indicated privileges.

modifyColumn

modifyColumn(TableName, 
             ColumnName, 
             Datatype, 
             Length = 0, 
             Optional = "")

Name	Type	Default	Description
TableName	String		Tablename
ColumnName	String		Name of the column to be modified
Datatype	Integer		See DATA_TYPE constants
Length	Integer	0	Column length. Valid only for wxDb.DATA_TYPE_VARCHAR dataType fields.
Optional	Integer		Optional parameters

Modify a column.

open

open(Dsn, 
     Uid, 
     Pwd) : Boolean

Name	Type	Description
Dsn	String	Datasource name
Uid	String	Username
Pwd	String	Password

open(Db) : Boolean

Name	Type	Default	Description
Db	wxDb		Database

open(ConnectionInf) : Boolean

Name	Type	Default	Description
ConnectionInf	wxDbConnectionInf

Opens a connection to the datasource. The second form of this function, which accepts a wxDb object as a parameter, can be used to avoid the overhead (execution time, database load, network traffic) which are needed to determine the data types and representations of data that are necessary for cross-datasource support by these classes.

If this function returns a value of false, it does not necessarily mean that the connection to the datasource was not opened. It may mean that some portion of the initialization of the connection failed (such as a datatype not being able to be determined how the datasource represents it). To determine if the connection to the database failed, use the opened function after receiving a false result back from this function to determine if the connection was opened or not. If this function returns false, but opened returns true, then direct SQL commands may be passed to the database connection and can be successfully executed, but use of the datatypes (such as by a wxDbTable instance) that are normally determined during open will not be possible.

rollbackTrans

rollbackTrans() : Boolean

Method to "undo" changes made to the database. After an insert/update/delete, the operation may be "undone" by issuing this command any time before a commitTrans is called on the database connection.

setSqlLogging

setSqlLogging(Switch, 
              Filename = SQL_LOG_FILENAME, 
              Append = false) : Boolean

Name	Type	Default	Description
Switch	Boolean		True to turn on logging, false to turn off logging.
Filename	String	SQL_LOG_FILENAME	Name of the file to which the log text is to be written.
Append	Boolean	false

When called with sqlLog ON, all commands sent to the datasource engine are logged to the file specified by filename. Logging is done by embedded writeSqlLog calls in the database member functions, or may be manually logged by adding calls to writeSqlLog in your own source code.

sqlColumnName

sqlColumnName(Column) : String

Name	Type	Default	Description
Column	String		Native name of the column

Returns the column name in a form ready for use in SQL statements. In most cases, the column name is returned verbatim. But some databases (e.g. MS Access, SQL Server, MSDE) allow for spaces in column names, which must be specially quoted. For example, if the datasource allows spaces in the column name, the returned string will have the correct enclosing marks around the name to allow it to be properly included in a SQL statement for the DBMS that is currently connected to with this connection.

sqlTableName

sqlTableName(Table) : String

Name	Type	Default	Description
Table	String		Native name of the table

Returns the table name in a form ready for use in SQL statements. In most cases, the table name is returned verbatim. But some databases (e.g. MS Access, SQL Server, MSDE) allow for spaces in table names, which must be specially quoted. For example, if the datasource allows spaces in the table name, the returned string will have the correct enclosing marks around the name to allow it to be properly included in a SQL statement for the data source that is currently connected to with this connection.

tableExists

tableExists(tableName, 
            userId = null, 
            Path = "") : Boolean

Name	Type	Default	Description
tableName	String		The table name you wish to obtain column information about.
userId	String	null	Name of the user that owns the table(s) (also referred to as schema). Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. userID is evaluated in the following manner: userID == null (or not given) ... userID is ignored (DEFAULT) userID == "" ... userID set equal to username userID != "" ... userID set equal to 'userID'
Path	String		Used for file based database systems

Checks the ODBC datasource for the existence of a table. If a userID is specified, then the table must be accessible by that user (user must have at least minimal privileges to the table).

tablePrivileges

tablePrivileges(TableName, 
                Priv, 
                UserId = null, 
                Schema = "", 
                Path = "") : Boolean

Name	Type	Default	Description
TableName	String		The table name you wish to obtain column information about.
Priv	String		The table privilege being evaluated. May be one of the following (or a datasource specific privilege): SELECT : The connected user is permitted to retrieve data for one or more columns of the table. INSERT : The connected user is permitted to insert new rows containing data for one or more columns into the table. UPDATE : The connected user is permitted to update the data in one or more columns of the table. DELETE : The connected user is permitted to delete rows of data from the table. REFERENCES : Is the connected user permitted to refer to one or more columns of the table within a constraint (for example, a unique, referential, or table check constraint).
UserId	String	null	Name of the user that owns the table(s) (also referred to as schema). Required for some datasources for situations where there may be multiple tables with the same name in the datasource, but owned by different users. userID is evaluated in the following manner: userID == null (or not given) ... userID is ignored (DEFAULT) userID == "" ... userID set equal to username userID != "" ... userID set equal to 'userID'
Schema	String
Path	String		Used for file based database systems

Checks the ODBC datasource for the existence of a table. If a userID is specified, then the table must be accessible by that user (user must have at least minimal privileges to the table).

writeSqlLog

writeSqlLog(Msg) : Boolean

Name	Type	Default	Description
Msg	String		Message to write to the log

If SQL logging is off when a call to writeSqlLog() is made, or there is a failure to write the log message to the log file, the function returns false without performing the requested log, otherwise true is returned

wxJavaScript

wxDb

Constants

DATA_TYPE

GRANT_TYPE

Class Properties

Constructor

wxDb

Properties

Methods

catalog

close

commitTrans

createView

dropView

execSql

getCatalog

getColumnCount

getColumns

getNext

grant

modifyColumn

open

rollbackTrans

setSqlLogging

sqlColumnName

sqlTableName

tableExists

tablePrivileges

writeSqlLog

Table of Contents

Class Properties

Constructor

Properties

Methods