The difference between open/4 and persistentOpen/4 is that this method checks if there is an unused database connection for the same database with the same username and password, and if so starts using that free database connection.
| superclass(es) | object |
| subclass(es) | - |
| description | The database class is for opening, controlling and closing database sources. |
| remarks | The default transaction mode is automatic, this means that every database
operation is a transaction that is committed when finished. This class is located in the file db.txt. |
| see also | dbSession - query |
| With the database class it is possible to open and
close ODBC datasources. There are three methods for opening
databases, the difference between these methods is the amount of information supplied. If
for instance a username and password is required to open an ODBC datasource and the open method with 2 arguments is used the ODBC datasource driver will
display a dialog to ask for the username and password. The persistentOpen/4 method can re-use existing
database connections if they are opened for the same database with the same username and
password. If the opened datasource is only used for reading data then it is possible to put the database in read-only mode with the method putReadOnly/2. SQL statements can be executed asynchronous or synchronous (is default). If a SQL statement is executed asynchronous the ODBC database driver does minimal processing (for instance: only syntax checking) before returning again. To check if an asynchronous statement has finished the same method must be called again with the same parameters, if the statement is still executing an error code value of 17 will be returned. Not all databases support asynchronous processing so if a program must be portable between databases it is advisable not to use asynchronous processing. The capabilities of the database and the ODBC database driver can be queried by the methods: asyncActivities/1, connectionTimeout/1, maxDriverConnections/1, maxConcurrentActivities/1, maxAsyncConcurrentActivities/1 and proceduresSupport/1. There are two modes for processing transactions, in the automatic transaction mode each separate statement is considered a transaction and is committed or rolled back automatically. The second mode is the manual transaction mode and in this mode a transaction must be explicitly committed or rolled back. The default mode for ODBC is the automatic transaction mode. There is no method for starting a transaction as a transaction starts when a transaction is committed or rolled back. The method putAutoCommit/2 can be used for setting the transaction mode. Some databases also support nested transactions. Interaction between multiple concurrent transaction is determined by the transaction isolation level, there are four possible transaction isolation levels:
The transaction isolation level does not affect a transaction's ability to see it's own changes; transaction can always see their own changes. Typically each level requires more processing of the database. It is not required that each database supports all the transaction isolation levels. Some databases, especially desktop databases do not even support transactions. The default format strings for date and time fields can also be set with the methods putDateFormatString/1 and putTimeFormatString/1. All new query instances allocated after these methods were called will have the changed format date and/or time string. see also: Statements and transactions Date and time formatting |
| func | A dialog is displayed by which the user can choose to open a database. |
| pre | TRUE |
| post | If a database was opened then true was assigned to the variable Output, else if no database was successfully opened then was false assigned to Output. |
| func | Attempt to open a specific database, the name of the database to open is the value of the first parameter. It is possible that an username and password must be entered before the database can be opened, if this is so a dialog to enter that information is displayed by the database driver or engine. |
| pre | The variable Name must contain a string. |
| post | If a database was opened then true was assigned to the variable Output, else if no database was successfully opened then was false assigned to Output. |
open(Name, User, Password, Output)
| func | Attempt to open a specific database, the name of the database to open is the value of the first parameter. The username and password for opening the database are the values of the second and third parameters. |
| pre | The variables Name, User and Password must contain a string. |
| post | If a database was opened then true was assigned to the variable Output, else if no database was successfully opened then was false assigned to Output. |
persistentOpen(Name, User, Password, Output)
| func | Attempt to open a specific database, the name of the database to open is
the value of the first parameter. The username and password for opening the database are
the values of the second and third parameters. The difference between open/4 and persistentOpen/4 is that this method checks if there is an unused database connection for the same database with the same username and password, and if so starts using that free database connection. |
| pre | The variables Name, User and Password must contain a string. |
| post | If a database was opened then true was assigned to the variable Output, else if no database was successfully opened then was false assigned to Output. |
|
If a persistent database connection is closed then the open connection is stored for possible later use. |
| func | Get the name of the database opened. |
| pre | TRUE |
| post | If a database was opened then the name of the database was assigned to the variable Output, else if no database was successfully opened then no value was assigned to Output. |
| func | Determine if the database instance has opened a ODBC datasource or not. |
| pre | TRUE |
| post | If a database was opened then true was assigned to the variable Output, else if no database was successfully opened then false was assigned to Output. |
| func | Determine if the database that was opened in read-only mode or not. |
| pre | TRUE |
| post | If a database was opened in read-only mode then true was assigned to the variable Output, else if no database was successfully opened or not in read-only mode then false was assigned to Output. |
| func | Put the opened database in read-only mode or remove the read-only mode. |
| pre | The variable YesNo must contain true or false |
| post | If the mode of a database was successfully changed then true was assigned to the variable Output, else false was assigned. |
| func | Close the opened database. |
| pre | TRUE |
| post | If the mode of a database was successfully closed then true was assigned to the variable Output, else false was assigned. |
|
If a persistent database connection is closed then the open connection is stored for possible later use, see for more information persistentOpen/4. |
| func | Put the default date format string for date fields. All new query instances allocated after this method was called will have the same date format string. |
| pre | The variable Str must contain a string. |
| post | The value of the parameter Str was stored as the date format string. |
|
for more information about format strings see date and time formatting. |
| func | Put the default time format string for time fields. All new query instances allocated after this method was called will have the same time format string. |
| pre | The variable Str must contain a string. |
| post | The value of the parameter Str was stored as the time format string. |
|
for more information about format strings see date and time formatting. |
putLongFieldReadMode( LFReadMode )
| func | Determine how long fields are read. The three allowed values of the LFReadMode parameter are; read_ignore , read_limited, and read_complete. |
| pre | The LFReadMode parameter must have one of the following values: read_ignore , read_limited, and read_complete. |
| post | The value of the parameter LFReadMode was stored. |
|
see also: long fields. If a query is associated with a database then it copies the readmode attribute of the database instance. |
longFieldReadMode( LFReadMode )
| func | Return the value of the parameter that determines how long fields are read. |
| pre | TRUE |
| post | The value of the parameter LFReadMode was unified with the read mode. |
|
see also: long fields |
putLongFieldReadLimit( NumBytes )
| func | Determine how many bytes are read if long fields are not completely read. |
| pre | The NumBytes parameter must contains a positive integer value. |
| post | The value of the parameter NumBytes was stored. |
|
see also: long fields. If a query is associated with a database then it copies the number-of-bytes attribute of the database instance. |
longFieldReadLimit( OutputBytes )
| func | Return the number of bytes that is read if only parts of long fields are read. |
| pre | TRUE |
| post | The number of bytes that is read was unified with the OutputBytes parameter. |
 |
see also: long fields |
| func | Determine if the database executes the (SQL) statements asynchronous or synchronous. In asynchronous mode the ODBC driver immediately returns after initial processing of a statement, in synchronous mode the call to the ODBC driver returns after completion of the statement. Be careful to use asynchronous mode because there are databases drivers that do not support asynchronous execution. |
| pre | TRUE |
| post | If the mode of a database executes statements asynchronous then true was assigned to the variable Output, else was false assigned to the variable Output. |
putAsyncActivities(YesNo, Output)
| func | Enable or disable asynchronous processing of statements. In asynchronous mode the ODBC driver immediately returns after initial processing of a statement, in synchronous mode the call to the ODBC driver returns after completion of the statement. It is possible that this method fails because some databases do not support asynchronous execution mode. |
| pre | The variable YesNo must contain true or false. |
| post | If YesNo was true and true was assigned to the variable Output then the database is in asynchronous mode, else if there was an error putting the database in asynchronous mode then was false assigned to the variable Output. If the variable YesNo contained false then the database was switched to synchronous mode if true was assigned to Output. |
| func | Return the maximum number of seconds that is waited while establishing a connecting to a database. If the assigned value is 0 then there is no maximum. |
| pre | TRUE |
| post | The number of seconds that is waited for establishing a connection to a database is assigned to the variable Output. |
putConnectionTimeout(Seconds, Output)
| func | Set the maximum number of seconds that is waited while establishing a connecting to a database. If the assigned value is 0 then there is no maximum. |
| pre | The variable Seconds must contain an integer. |
| post | If the connection timeout was successfully assigned then was true assigned to the variable Output, else was false assigned. |
| func | Return the maximum number of connections that a database driver supports. The driver or the database engine can have a limit for the number the connections. |
| pre | TRUE |
| post | The maximum number of connections supported by the driver was assigned to the variable Output. If there is no specified limit or it is unknown then 0 was assigned to the variable Output. |
maxConcurrentActivities(Output)
| func | Return the maximum number of concurrent active statements that a driver or database supports for a connection. Active statements are statements that return results or return a row count like a DELETE or an UPDATE statement. |
| pre | TRUE |
| post | The maximum number of concurrent active statements supported by the driver was assigned to the variable Output. If there is no specified limit or it is unknown then 0 was assigned to the variable Output. |
maxAsyncConcurrentActivities(Output)
| func | Return the maximum number of concurrent active statements in asynchronous mode that a driver or database supports for a connection. Active statements are statements that return results or return a row count like a DELETE or an UPDATE statement. |
| pre | TRUE |
| post | The maximum number of concurrent asynchronous active statements supported by the driver was assigned to the variable Output. If there is no specified limit or it is unknown then 0 was assigned to the variable Output. |
transactionIsolationLevel(Output)
| func | Return the current transaction isolation level for the database. One of
the following four constants can be assigned to the output variable Output: read_uncommitted: transactions are not isolated from each other, transactions at this level are usually read-only. read_committed: the transaction waits until rows write-locked by other transactions are unlocked, this prevents the transaction from reading dirty data. read_repeatable_read: the transaction holds read locks on all rows returned and write locks on all rows it inserts, updates or deletes. This prevents any non-repeatable reads. read_serializable: the transaction holds a read lock or a write lock on the range of rows it affects, this can be an entire table. The transaction also waits until rows write-locked by other transactions are unlocked, this prevents it from reading 'dirty' data. |
| pre | TRUE |
| post | The current transaction isolation level was assigned to the variable Output. |
putTransactionIsolationLevel(Level, Output)
| func | Set the transaction isolation level for the database. One of the following four constants can be the value of the variable Level:read_uncommitted, read_committed, read_repeatable_read or read_serializable. |
| pre | TRUE |
| post | If the transaction isolation level was set successfully then true was assigned to the variable Output, else was false assigned. |
| func | Determine if the driver and the database support more than one active transaction at the same time or not. |
| pre | TRUE |
| post | If the driver supports more then one active transaction at the same time then was true assigned to the variable Output, else was false assigned. |
| func | Determine if the database is in auto commit mode or in manual commit mode. In auto commit mode each statement is committed automatically after it has been executed. In manual commit mode the application must explicitly commit or rollback a transaction. Default is autocommit. |
| pre | TRUE |
| post | If the driver is in the auto commit mode then true was assigned to the variable Output, else if the driver is in manual commit mode then false was assigned to the variable Output. |
| func | Put the driver in the auto commit mode or in the manual commit mode. In auto commit mode each statement is committed automatically after it has been executed. In manual commit mode the application must explicitly commit or rollback a transaction. |
| pre | The variable YesNo must contain true or false |
| post | If the variable YesNo contained true then an attempt was made to put the driver in the auto commit mode else in the manual commit mode. If the attempt was successful then true was assigned to Output else was false assigned. |
| func | Commit the current transaction. With ODBC a transaction starts immediately after a transaction has been committed or rolled back. |
| pre | TRUE |
| post | If the current transaction was successfully committed then true was assigned to Output else was false assigned. |
| func | Roll back the current transaction. With ODBC a transaction starts immediately after a transaction has been committed or rolled back. |
| pre | TRUE |
| post | If the rollback operation was successful then true was assigned to Output else was false assigned. |
| func | Determine if the driver and the database support 'stored' procedures or not. Procedure is a generic term for an executable object stored inside the database which can be executed by a client application, such an executable object can have input and output parameters. |
| pre | TRUE |
| post | If the driver and the database support procedures then true was assigned to Output else was false assigned. |