Opening a database
In order to open a database, your application should implement the following steps:
1. Create a new Connection event.
2. Call the Connection event's openDatabase action with the database's service ID, database URL, autocommit preference, and the name of the callback action.
3. Create the handler action for the openDatabase callback action.
The definitions for the different forms of the openDatabase actions are:
action openDatabase(
string serviceId,
string databaseURL,
string user,
string password,
string autoCommit,
action <Connection, string> callback)
and
action openDatabaseFull (
string serviceId,
string databaseURL,
string user,
string password,
string autocommit,
boolean readOnly,
dictionary<string,string> extraParams,
action <Connection, string> callback)
In addition to these open actions you can also open a database using an already open matching connection if one exists using the openDatabaseShared action. If an existing connection is not found, the action opens a new connection.
action openDatabaseShared (
string serviceId,
string databaseURL,
string user,
string password,
string autocommit,
boolean readOnly,
dictionary<string,string> extraParams,
action <Connection, string> callback)
The value for the
autocommit parameter is a combination of the
AutoCommit and
StoreCommitInterval properties. For information on these properties, see
Configuring an ADBC adapter. The value for the
autocommit parameter can be one of the following modes:
"" — An empty string specifies that the value set in the configuration file should be used.
true — Use the data source's value as determined by the ODBC or JDBC driver.
false — Disable
autocommit.
x.x — Use time auto commit interval in seconds.
The readOnly parameter specifies if the connection should be read-only. If the connection is read-only an error will be reported for any API action that requires writes (Store, Commit, or Rollback). Most databases do not prevent writes from a connection in read-only mode so it is still possible to perform writes using the Command actions.
Specifying parameter values in the open actions overrides the property values set in the configuration file.
The relevant code in the samples\adbc\api-example\ADBC_Example.mon file is similar to this:
com.apama.database.Connection conn :=
new com.apama.database.Connection;
action handleAvailableDatabases(string error,
sequence<com.apama.database.Database> results)
{
if error.length() != 0 {
log "Error occurred getting available databases: " +
error at ERROR;
}
else {
if results.size() > 0 {
// Save name of first db found
if getDbName() = "" {
dbName := results[0].shortName;
}
com.apama.database.Database db;
log " Databases: " at INFO;
for db in results {
log " " + db.shortName + " - " +
db.description + " - " + db.dbURL at INFO;
}
log "Opening Database " + dbName + " ..." at INFO;
string serviceId := getDbServiceId();
conn.openDatabase(serviceId, results[0].dbUrl, USER,
PASSWORD, "", handleOpenDatabase);
}
else {
log " No Databases found" at INFO;
}
}
}
Note:
If reusing a database connection, rather than calling openDatabase again, it is advised to use reopenWithAck instead. In cases where there are issues using the current connection, for example, the call to closeDatabase is not succeeding following an incident where the IAF went down, then you should call reopenWithAck to recover the connection.