Platforms to show: All Mac Windows Linux Cross-Platform
SQLConnectionMBS.CancelAllCommands
Function:
Cancel all commands for the connection.
Notes: This loops over the list of commands associated with this connection and calls Cancel on them.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 18.4 | Yes | Yes | Yes | Yes | No |
Notes: This loops over the list of commands associated with this connection and calls Cancel on them.
SQLConnectionMBS.Commands as SQLCommandMBS()
Function:
Queries list of all command objects related to the connection.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 18.4 | Yes | Yes | Yes | Yes | No |
SQLConnectionMBS.Commit
Function:
Saves any changes and ends the current transaction.
Notes:
Use Commit method to write transaction changes permanently to a database. It commits the work of all commands that associated with that connection.
All changes to the database since the last commit are made permanent and cannot be undone. Before a commit, all changes made since the start of the transaction can be rolled back using Rollback method.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 9.3 | Yes | Yes | Yes | Yes | No |
Notes:
Use Commit method to write transaction changes permanently to a database. It commits the work of all commands that associated with that connection.
All changes to the database since the last commit are made permanent and cannot be undone. Before a commit, all changes made since the start of the transaction can be rolled back using Rollback method.
SQLConnectionMBS.Connect(DBString as string, UserID as string, Password as string, client as Integer = 0)
Function:
Opens the connection to a data source.
Example:
Notes:
Using the Connect method on a SAConnection object establishes the physical connection to a data source. After this method successfully completes, the connection is live and you can issue commands against it and process the results.
If you use the default value of Client parameter, you should set Client before using Connect.
To check whether a connection established use isConnected method. To check whether a connection is broken or not use isAlive method.
see also for server specific notes:
https://www.sqlapi.com/ApiDoc/class_s_a_connection.html
For IPv6 we changed plugin to use , instead of : for the port separator. So please use , to separate port from IP or host.
For Firebird, if you connect to a database and you have 32/64bit mismatch, you get error number 3.
See Option() for various options you can set before connecting.
e.g. c.Option("SQLiteVFSFlags") = "1" for SQLite for read only access.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 9.3 | Yes | Yes | Yes | Yes | No |
Example:
dim con as SQLConnectionMBS// your connection
// some calls for MS SQL Server:
con.Connect("srv2@pubs","", "", SQLConnectionMBS.kSQLServerClient)
con.Connect("@pubs", "", "", SQLConnectionMBS.kSQLServerClient)
con.Connect("BEDLAM\SQL2005EX_EN@pubs", "", "", SQLConnectionMBS.kSQLServerClient)
con.Connect("BEDLAM\SQLEXPRESS@master", "", "", SQLConnectionMBS.kSQLServerClient)
// for MySQL:
con.Connect("192.168.1.80,3306@test","root","password", SQLConnectionMBS.kMySQLClient)
// for Postgre SQL:
con.Connect("somedb", "name", "password",SQLConnectionMBS.kPostgreSQLClient)
// with options
con.Connect("PostgreSQL:127.0.0.1,5432@dbname=postgres connection_timeout=10 sslmode=require", "name", "password",SQLConnectionMBS.kPostgreSQLClient)
// for SQLite:
con.Connect("/test.db", "", "",SQLConnectionMBS.kSQLiteClient)
| DBString: | Name of database this connection will connect to (see Server specific notes). |
| UserID: | A string containing a user name to use when establishing the connection (see Server specific notes). |
| Password: | A string containing a password to use when establishing the connection. |
| client: | Optional. One of the following values from k*Client constants. |
Using the Connect method on a SAConnection object establishes the physical connection to a data source. After this method successfully completes, the connection is live and you can issue commands against it and process the results.
If you use the default value of Client parameter, you should set Client before using Connect.
To check whether a connection established use isConnected method. To check whether a connection is broken or not use isAlive method.
see also for server specific notes:
https://www.sqlapi.com/ApiDoc/class_s_a_connection.html
For IPv6 we changed plugin to use , instead of : for the port separator. So please use , to separate port from IP or host.
For Firebird, if you connect to a database and you have 32/64bit mismatch, you get error number 3.
See Option() for various options you can set before connecting.
e.g. c.Option("SQLiteVFSFlags") = "1" for SQLite for read only access.
SQLConnectionMBS.ConnectMT(DBString as string, UserID as string, Password as string, client as Integer = 0)
Function:
Opens the connection to a data source.
Notes:
Using the Connect method on a SAConnection object establishes the physical connection to a data source. After this method successfully completes, the connection is live and you can issue commands against it and process the results.
If you use the default value of Client parameter, you should set Client before using Connect.
To check whether a connection established use isConnected method. To check whether a connection is broken or not use isAlive method.
see also for server specific notes:
https://www.sqlapi.com/ApiDoc/class_s_a_connection.html
For IPv6 we changed plugin to use , instead of : for the port separator. So please use , to separate port from IP or host.
The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.
The MT method will not trigger WillConnect and DidConnect events.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 15.4 | Yes | Yes | Yes | Yes | No |
Notes:
| DBString: | Name of database this connection will connect to (see Server specific notes). |
| UserID: | A string containing a user name to use when establishing the connection (see Server specific notes). |
| Password: | A string containing a password to use when establishing the connection. |
| client: | Optional. One of the following values from k*Client constants. |
Using the Connect method on a SAConnection object establishes the physical connection to a data source. After this method successfully completes, the connection is live and you can issue commands against it and process the results.
If you use the default value of Client parameter, you should set Client before using Connect.
To check whether a connection established use isConnected method. To check whether a connection is broken or not use isAlive method.
see also for server specific notes:
https://www.sqlapi.com/ApiDoc/class_s_a_connection.html
For IPv6 we changed plugin to use , instead of : for the port separator. So please use , to separate port from IP or host.
The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.
The MT method will not trigger WillConnect and DidConnect events.
SQLConnectionMBS.CubeSQLReceiveData(byref data as String, byref IsEndChunk as Boolean) as Boolean
Function:
Receives a data chunk for file download.
Notes:
Returns true on success.
Data is set with data and IsEndChunk is set to true for last chunk.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
Returns true on success.
Data is set with data and IsEndChunk is set to true for last chunk.
SQLConnectionMBS.CubeSQLSendData(data as MemoryBlock)
Function:
Sends data chunk for file upload.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
See also:
SQLConnectionMBS.CubeSQLSendData(data as String)
Function:
Sends data chunk for file upload.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
See also:
SQLConnectionMBS.CubeSQLSendEndData
Function:
Sends end data packet.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
SQLConnectionMBS.Disconnect
Function:
Disconnects the connection from the database.
Notes: Closes all commands objects and RecordSets.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 9.3 | Yes | Yes | Yes | Yes | No |
Notes: Closes all commands objects and RecordSets.
SQLConnectionMBS.InsertRecord(TableName as String, Record as Dictionary)
Function:
Convenience function to insert a record.
Example:
Notes:
The plugin builds for you SQL statement with prepared statement and runs the insert command with values.
Lasterror is set or exception raised as with SQLExecute.
You can check statement via LastStatement property.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 17.5 | Yes | Yes | Yes | Yes | No |
Example:
dim con as SQLConnectionMBS // your database connection
dim d as new Dictionary
d.Value("ID")=2
d.Value("text")="test insert"
d.Value("other")="Just a test"
con.InsertRecord("test_tbl", d)
The plugin builds for you SQL statement with prepared statement and runs the insert command with values.
Lasterror is set or exception raised as with SQLExecute.
You can check statement via LastStatement property.
SQLConnectionMBS.Listen
Function:
Start listening for notifications.
Notes:
Works only for PostgresSQL Client.
Please set client or connect before calling this method.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 15.1 | Yes | Yes | Yes | Yes | No |
Notes:
Works only for PostgresSQL Client.
Please set client or connect before calling this method.
SQLConnectionMBS.MySQLInsertID as Int64
Function:
Returns the last auto increment value from last insert command.
Notes:
see also
http://dev.mysql.com/doc/refman/5.1/en/mysql-insert-id.html
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
see also
http://dev.mysql.com/doc/refman/5.1/en/mysql-insert-id.html
SQLConnectionMBS.Option(name as string) as string
Function:
A string value of a specific connection or command option.
Example:
Notes:
see also:
https://www.sqlapi.com/ApiDoc/class_s_a_connection.html
(Read and Write computed property)
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| property | SQL | MBS SQL Plugin | 9.3 | Yes | Yes | Yes | Yes | No |
Example:
dim c as SQLConnectionMBS // your connection
// for Microsoft SQL use OLEDB, so you don't need native SQL drivers installed...
c.Option("UseAPI") = "OLEDB"
c.Option("SQLNCLI.LIBS") = "sqlsrv32.dll" // Library included in Windows Vista and newer
// for SQLite, set flag to open database file read only:
c.Option("SQLiteVFSFlags") = "1"
// set 10 seconds timeout for MySQL
c.Option("MYSQL_OPT_CONNECT_TIMEOUT") = "10"
// turn on auto cache
c.Option("AutoCache") = "true"
// set connection timeout for ODBC:
c.Option("SQL_ATTR_CONNECTION_TIMEOUT") = "10"
see also:
https://www.sqlapi.com/ApiDoc/class_s_a_connection.html
(Read and Write computed property)
SQLConnectionMBS.Rollback
Function:
Cancels any changes made during the current transaction and ends the transaction.
Notes:
Rollback method rolls back the database to the state it was in at the completion of the last commit operation. All uncommitted work is undone.
Rollback method rolls back the work of all commands that associated with that connection.
To commit all changes made since the start of the transaction use Commit method.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 9.3 | Yes | Yes | Yes | Yes | No |
Notes:
Rollback method rolls back the database to the state it was in at the completion of the last commit operation. All uncommitted work is undone.
Rollback method rolls back the work of all commands that associated with that connection.
To commit all changes made since the start of the transaction use Commit method.
SQLConnectionMBS.SetFileOption(name as string, file as folderitem)
Function:
Sets an option with passing a file path.
Example:
Notes:
Makes sure the path is correct and you have a 32 or 64-bit library matching the architecture of your application.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 10.5 | Yes | Yes | Yes | Yes | No |
Example:
dim db as new SQLConnectionMBS
// where is the library?
db.SetFileOption SQLConnectionMBS.kOptionLibraryMySQL, SpecialFolder.UserHome.Child("libmysqlclient.dylib")
SQLConnectionMBS.SQLExecute(command as string, CommandType as Integer = 0)
Function:
Executes a SQL command and ignores result.
Notes:
This is a convenience function.
Internally it creates a SQLCommandMBS with the given command and calls Execute.
All text strings sent to the plugin must have a defined encoding. Else the internal text encoding conversions will fail.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 10.2 | Yes | Yes | Yes | Yes | No |
Notes:
This is a convenience function.
Internally it creates a SQLCommandMBS with the given command and calls Execute.
All text strings sent to the plugin must have a defined encoding. Else the internal text encoding conversions will fail.
SQLConnectionMBS.SQLExecuteMT(command as string, CommandType as Integer = 0)
Function:
Executes a SQL command and ignores result.
Notes:
This is a convenience function.
Internally it creates a SQLCommandMBS with the given command and calls Execute.
All text strings sent to the plugin must have a defined encoding. Else the internal text encoding conversions will fail.
The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 10.4 | Yes | Yes | Yes | Yes | No |
Notes:
This is a convenience function.
Internally it creates a SQLCommandMBS with the given command and calls Execute.
All text strings sent to the plugin must have a defined encoding. Else the internal text encoding conversions will fail.
The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.
SQLConnectionMBS.SQLiteBackupFinish(Backup as SQLite3BackupMBS) as integer
Function:
Finishes a backup run.
Notes:
When BackupStep has returned kErrorDone, or when the application wishes to abandon the backup operation, the application should destroy the SQLite3BackupMBS by passing it to BackupFinish. The BackupFinish interfaces releases all resources associated with the SQLite3BackupMBS object. If BackupStep has not yet returned kErrorDone, then any active write-transaction on the destination database is rolled back. The SQLite3BackupMBS object is invalid and may not be used following a call to BackupFinish.
The value returned by BackupFinish is kErrorOK if no BackupStep errors occurred, regardless or whether or not BackupStep completed. If an out-of-memory condition or IO error occurred during any prior BackupStep call on the same SQLite3BackupMBS object, then BackupFinish returns the corresponding error code.
A return of kErrorBusy or kErrorLocked from BackupStep is not a permanent error and does not affect the return value of BackupFinish.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
When BackupStep has returned kErrorDone, or when the application wishes to abandon the backup operation, the application should destroy the SQLite3BackupMBS by passing it to BackupFinish. The BackupFinish interfaces releases all resources associated with the SQLite3BackupMBS object. If BackupStep has not yet returned kErrorDone, then any active write-transaction on the destination database is rolled back. The SQLite3BackupMBS object is invalid and may not be used following a call to BackupFinish.
The value returned by BackupFinish is kErrorOK if no BackupStep errors occurred, regardless or whether or not BackupStep completed. If an out-of-memory condition or IO error occurred during any prior BackupStep call on the same SQLite3BackupMBS object, then BackupFinish returns the corresponding error code.
A return of kErrorBusy or kErrorLocked from BackupStep is not a permanent error and does not affect the return value of BackupFinish.
SQLConnectionMBS.SQLiteBackupInit(Dest as Variant, DestName as String, Source as Variant, SourceName as String) as SQLite3BackupMBS
Function:
Initializes a backup.
Notes:
The backup API copies the content of one database into another. It is useful either for creating backups of databases or for copying in-memory databases to or from persistent files.
see also
http://www.sqlite.org/c3ref/backup_finish.html
Exclusive access is required to the destination database for the duration of the operation. However the source database is only read-locked while it is actually being read; it is not locked continuously for the entire backup operation. Thus, the backup may be performed on a live source database without preventing other users from reading or writing to the source database while the backup is underway.
To perform a backup operation:
The D and N arguments to BackupInit(D,N,S,M) are the database connection associated with the destination database and the database name, respectively. The database name is "main" for the main database, "temp" for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database. The S and M arguments passed to BackupInit(D,N,S,M) identify the database connection and database name of the source database, respectively. The source and destination database connections (parameters S and D) must be different or else BackupInit(D,N,S,M) will file with an error.
If an error occurs within BackupInit(D,N,S,M), then nil is returned and an error code and error message are store3d in the destination database connection D. The error code and message for the failed call to BackupInit can be retrieved using the ErrCode and ErrMessage functions. A successful call to BackupInit returns a SQLite3BackupMBS object. The SQLite3BackupMBS object may be used with the BackupStep and BackupFinish functions to perform the specified backup operation.
Concurrent Usage of Database Handles
The source database connection may be used by the application for other purposes while a backup operation is underway or being initialized. If SQLite is compiled and configured to support threadsafe database connections, then the source database connection may be used concurrently from within other threads.
However, the application must guarantee that the destination database connection is not passed to any other API (by any thread) after BackupInit is called and before the corresponding call to BackupFinish. SQLite does not currently check to see if the application incorrectly accesses the destination database connection and so no error code is reported, but the operations may malfunction nevertheless. Use of the destination database connection while a backup is in progress might also also cause a mutex deadlock.
If running in shared cache mode, the application must guarantee that the shared cache used by the destination database is not accessed while the backup is running. In practice this means that the application must guarantee that the disk file being backed up to is not accessed by any connection within the process, not just the specific connection that was passed to BackupInit.
The SQLite3BackupMBS object itself is partially threadsafe. Multiple threads may safely make multiple concurrent calls to BackupStep. However, the BackupRemaining and BackupPageCount APIs are not strictly speaking threadsafe. If they are invoked at the same time as another thread is invoking BackupStep it is possible that they return invalid values.
Source and Dest can be SQLConnectionMBS or SQLDatabaseMBS. You need to pass source and dest, even if one is self as we give you the option to decide where to pass the current database connection.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
The backup API copies the content of one database into another. It is useful either for creating backups of databases or for copying in-memory databases to or from persistent files.
see also
http://www.sqlite.org/c3ref/backup_finish.html
Exclusive access is required to the destination database for the duration of the operation. However the source database is only read-locked while it is actually being read; it is not locked continuously for the entire backup operation. Thus, the backup may be performed on a live source database without preventing other users from reading or writing to the source database while the backup is underway.
To perform a backup operation:
- BackupInit is called once to initialize the backup,
- BackupStep is called one or more times to transfer the data between the two databases, and finally
- BackupFinish is called to release all resources associated with the backup operation.
The D and N arguments to BackupInit(D,N,S,M) are the database connection associated with the destination database and the database name, respectively. The database name is "main" for the main database, "temp" for the temporary database, or the name specified after the AS keyword in an ATTACH statement for an attached database. The S and M arguments passed to BackupInit(D,N,S,M) identify the database connection and database name of the source database, respectively. The source and destination database connections (parameters S and D) must be different or else BackupInit(D,N,S,M) will file with an error.
If an error occurs within BackupInit(D,N,S,M), then nil is returned and an error code and error message are store3d in the destination database connection D. The error code and message for the failed call to BackupInit can be retrieved using the ErrCode and ErrMessage functions. A successful call to BackupInit returns a SQLite3BackupMBS object. The SQLite3BackupMBS object may be used with the BackupStep and BackupFinish functions to perform the specified backup operation.
Concurrent Usage of Database Handles
The source database connection may be used by the application for other purposes while a backup operation is underway or being initialized. If SQLite is compiled and configured to support threadsafe database connections, then the source database connection may be used concurrently from within other threads.
However, the application must guarantee that the destination database connection is not passed to any other API (by any thread) after BackupInit is called and before the corresponding call to BackupFinish. SQLite does not currently check to see if the application incorrectly accesses the destination database connection and so no error code is reported, but the operations may malfunction nevertheless. Use of the destination database connection while a backup is in progress might also also cause a mutex deadlock.
If running in shared cache mode, the application must guarantee that the shared cache used by the destination database is not accessed while the backup is running. In practice this means that the application must guarantee that the disk file being backed up to is not accessed by any connection within the process, not just the specific connection that was passed to BackupInit.
The SQLite3BackupMBS object itself is partially threadsafe. Multiple threads may safely make multiple concurrent calls to BackupStep. However, the BackupRemaining and BackupPageCount APIs are not strictly speaking threadsafe. If they are invoked at the same time as another thread is invoking BackupStep it is possible that they return invalid values.
Source and Dest can be SQLConnectionMBS or SQLDatabaseMBS. You need to pass source and dest, even if one is self as we give you the option to decide where to pass the current database connection.
SQLConnectionMBS.SQLiteBackupPageCount(Backup as SQLite3BackupMBS) as integer
Function:
Returns the number of pages in total.
Notes:
Each call to BackupStep sets two values inside the SQLite3BackupMBS object: the number of pages still to be backed up and the total number of pages in the source databae file. The BackupRemaining and BackupPageCount interfaces retrieve these two values, respectively.
The values returned by these functions are only updated by BackupStep. If the source database is modified during a backup operation, then the values are not updated to account for any extra pages that need to be updated or the size of the source database file changing.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
Each call to BackupStep sets two values inside the SQLite3BackupMBS object: the number of pages still to be backed up and the total number of pages in the source databae file. The BackupRemaining and BackupPageCount interfaces retrieve these two values, respectively.
The values returned by these functions are only updated by BackupStep. If the source database is modified during a backup operation, then the values are not updated to account for any extra pages that need to be updated or the size of the source database file changing.
SQLConnectionMBS.SQLiteBackupRemaining(Backup as SQLite3BackupMBS) as integer
Function:
Returns the number of pages remaining.
Notes:
Each call to BackupStep sets two values inside the SQLite3BackupMBS object: the number of pages still to be backed up and the total number of pages in the source databae file. The BackupRemaining and BackupPageCount interfaces retrieve these two values, respectively.
The values returned by these functions are only updated by BackupStep. If the source database is modified during a backup operation, then the values are not updated to account for any extra pages that need to be updated or the size of the source database file changing.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
Each call to BackupStep sets two values inside the SQLite3BackupMBS object: the number of pages still to be backed up and the total number of pages in the source databae file. The BackupRemaining and BackupPageCount interfaces retrieve these two values, respectively.
The values returned by these functions are only updated by BackupStep. If the source database is modified during a backup operation, then the values are not updated to account for any extra pages that need to be updated or the size of the source database file changing.
SQLConnectionMBS.SQLiteBackupStep(Backup as SQLite3BackupMBS, Pages as Integer) as integer
Function:
Copies up to Pages pages between the source and destination databases specified by SQLite3BackupMBS object.
Notes:
If N is negative, all remaining source pages are copied. If BackupStep(B,N) successfully copies N pages and there are still more pages to be copied, then the function resturns kErrorOK. If BackupStep(B,N) successfully finishes copying all pages from source to destination, then it returns kErrorDone. If an error occurs while running BackupStep(B,N), then an error code is returned. As well as kErrorOK and kErrorDone, a call to BackupStep may return kErrorReadOnly, kErrorNoMem, kErrorBusy, kErrorLocked, or an kErrorIOACCESS | kErrorIOXXX extended error code.
The BackupStep might return kErrorReadOnly if the destination database was opened read-only or if the destination is an in-memory database with a different page size from the source database.
If BackupStep cannot obtain a required file-system lock, then the sqlite3_busy_handler | busy-handler function is invoked (if one is specified). If the busy-handler returns non-zero before the lock is available, then kErrorBusy is returned to the caller. In this case the call to BackupStep can be retried later. If the source database connection is being used to write to the source database when BackupStep is called, then kErrorLocked is returned immediately. Again, in this case the call to BackupStep can be retried later on. (If kErrorIOACCESS | kErrorIOXXX, kErrorNoMem, or kErrorReadOnly is returned, then there is no point in retrying the call to BackupStep. These errors are considered fatal.) The application must accept that the backup operation has failed and pass the backup operation handle to the BackupFinish to release associated resources.
The first call to BackupStep obtains an exclusive lock on the destination file. The exclusive lock is not released until either BackupFinish is called or the backup operation is complete and BackupStep returns kErrorDone. Every call to BackupStep obtains a shared lock on the source database that lasts for the duration of the BackupStep call. Because the source database is not locked between calls to BackupStep, the source database may be modified mid-way through the backup process. If the source database is modified by an external process or via a database connection other than the one being used by the backup operation, then the backup will be automatically restarted by the next call to BackupStep. If the source database is modified by the using the same database connection as is used by the backup operation, then the backup database is automatically updated at the same time.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
If N is negative, all remaining source pages are copied. If BackupStep(B,N) successfully copies N pages and there are still more pages to be copied, then the function resturns kErrorOK. If BackupStep(B,N) successfully finishes copying all pages from source to destination, then it returns kErrorDone. If an error occurs while running BackupStep(B,N), then an error code is returned. As well as kErrorOK and kErrorDone, a call to BackupStep may return kErrorReadOnly, kErrorNoMem, kErrorBusy, kErrorLocked, or an kErrorIOACCESS | kErrorIOXXX extended error code.
The BackupStep might return kErrorReadOnly if the destination database was opened read-only or if the destination is an in-memory database with a different page size from the source database.
If BackupStep cannot obtain a required file-system lock, then the sqlite3_busy_handler | busy-handler function is invoked (if one is specified). If the busy-handler returns non-zero before the lock is available, then kErrorBusy is returned to the caller. In this case the call to BackupStep can be retried later. If the source database connection is being used to write to the source database when BackupStep is called, then kErrorLocked is returned immediately. Again, in this case the call to BackupStep can be retried later on. (If kErrorIOACCESS | kErrorIOXXX, kErrorNoMem, or kErrorReadOnly is returned, then there is no point in retrying the call to BackupStep. These errors are considered fatal.) The application must accept that the backup operation has failed and pass the backup operation handle to the BackupFinish to release associated resources.
The first call to BackupStep obtains an exclusive lock on the destination file. The exclusive lock is not released until either BackupFinish is called or the backup operation is complete and BackupStep returns kErrorDone. Every call to BackupStep obtains a shared lock on the source database that lasts for the duration of the BackupStep call. Because the source database is not locked between calls to BackupStep, the source database may be modified mid-way through the backup process. If the source database is modified by an external process or via a database connection other than the one being used by the backup operation, then the backup will be automatically restarted by the next call to BackupStep. If the source database is modified by the using the same database connection as is used by the backup operation, then the backup database is automatically updated at the same time.
SQLConnectionMBS.SQLiteEnableLoadExtension(OnOff as boolean)
Function:
Enables/disables extension loading for the given connection.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
SQLConnectionMBS.SQLiteLastInsertRowID as Int64
Function:
Returns Last Insert Rowid.
Notes:
Each entry in an SQLite table has a unique 64-bit signed integer key called the ROWID. The rowid is always available as an undeclared column named ROWID, OID, or _ROWID_ as long as those names are not also used by explicitly declared columns. If the table has a column of type INTEGER PRIMARY KEY then that column is another alias for the rowid.
This routine returns the rowid of the most recent successful INSERT into the database from the database connection in the first argument. If no successful INSERTs have ever occurred on that database connection, zero is returned.
(If an INSERT occurs within a trigger, then the rowid of the inserted row is returned by this routine as long as the trigger is running. But once the trigger terminates, the value returned by this routine reverts to the last value inserted before the trigger fired.)
An INSERT that fails due to a constraint violation is not a successful INSERT and does not change the value returned by this routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, and INSERT OR ABORT make no changes to the return value of this routine when their insertion fails. ^(When INSERT OR REPLACE encounters a constraint violation, it does not fail. The INSERT continues to completion after deleting rows that caused the constraint problem so INSERT OR REPLACE will always change the return value of this interface.)^
For the purposes of this routine, an INSERT is considered to be successful even if it is subsequently rolled back.
This function is accessible to SQL statements via the last_insert_rowid() SQL function.
If a separate thread performs a new INSERT on the same database connection while the LastInsertRowID function is running and thus changes the last insert rowid, then the value returned by LastInsertRowID is unpredictable and might not equal either the old or the new last insert rowid.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
Each entry in an SQLite table has a unique 64-bit signed integer key called the ROWID. The rowid is always available as an undeclared column named ROWID, OID, or _ROWID_ as long as those names are not also used by explicitly declared columns. If the table has a column of type INTEGER PRIMARY KEY then that column is another alias for the rowid.
This routine returns the rowid of the most recent successful INSERT into the database from the database connection in the first argument. If no successful INSERTs have ever occurred on that database connection, zero is returned.
(If an INSERT occurs within a trigger, then the rowid of the inserted row is returned by this routine as long as the trigger is running. But once the trigger terminates, the value returned by this routine reverts to the last value inserted before the trigger fired.)
An INSERT that fails due to a constraint violation is not a successful INSERT and does not change the value returned by this routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, and INSERT OR ABORT make no changes to the return value of this routine when their insertion fails. ^(When INSERT OR REPLACE encounters a constraint violation, it does not fail. The INSERT continues to completion after deleting rows that caused the constraint problem so INSERT OR REPLACE will always change the return value of this interface.)^
For the purposes of this routine, an INSERT is considered to be successful even if it is subsequently rolled back.
This function is accessible to SQL statements via the last_insert_rowid() SQL function.
If a separate thread performs a new INSERT on the same database connection while the LastInsertRowID function is running and thus changes the last insert rowid, then the value returned by LastInsertRowID is unpredictable and might not equal either the old or the new last insert rowid.
SQLConnectionMBS.SQLiteLibVersion as String
Function:
Queries the version string of the SQLite library.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
SQLConnectionMBS.SQLiteLoadExtension(file as FolderItem, ByRef ErrorMessage as String) as Integer
Function:
Loads an SQLite extension library from the named file.
Notes:
The LoadExtension interface attempts to load an SQLite extension library contained in the file.
Returns kErrorOk on success and kErrorError if something goes wrong.
Extension loading must be enabled using EnableLoadExtension prior to calling this API, otherwise an error will be returned.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
The LoadExtension interface attempts to load an SQLite extension library contained in the file.
Returns kErrorOk on success and kErrorError if something goes wrong.
Extension loading must be enabled using EnableLoadExtension prior to calling this API, otherwise an error will be returned.
See also:
SQLConnectionMBS.SQLiteLoadExtension(path as String, ByRef ErrorMessage as String) as Integer
Function:
Loads an SQLite extension library from the named file.
Notes:
The LoadExtension interface attempts to load an SQLite extension library contained in the file.
Returns kErrorOk on success and kErrorError if something goes wrong.
Extension loading must be enabled using EnableLoadExtension prior to calling this API, otherwise an error will be returned.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes:
The LoadExtension interface attempts to load an SQLite extension library contained in the file.
Returns kErrorOk on success and kErrorError if something goes wrong.
Extension loading must be enabled using EnableLoadExtension prior to calling this API, otherwise an error will be returned.
See also:
SQLConnectionMBS.SQLiteMemoryHighwater(reset as boolean = false) as Int64
Function:
Queries maximum memory usage so far.
Notes: Can be reset with reset parameter being true.
| Type | Topic | Plugin | Version | macOS | Windows | Linux | Console & Web | iOS |
| method | SQL | MBS SQL Plugin | 19.5 | Yes | Yes | Yes | Yes | No |
Notes: Can be reset with reset parameter being true.
The items on this page are in the following plugins: MBS SQL Plugin.
Links
MBS Xojo Chart Plugins
