Connect with the local database

The following instructions are applicable to both the UltraLite database and the SQLite database.

To connect with the local database, you should first add a special parameter called EnabledLocalDB to allow the mobile application to establish a local database connection, this is described in this section, and then you should configure the connection settings for the local database in PowerServer Toolkit, this is described in Task 3: Configure the offline settings in Tutorial 4.

Step 1: Add the EnabledLocalDB parameter to the DBParm property of the transaction object, and set its value to True (or Yes or 1). For example,

SQLCA.DBMS = "ODBC"
SQLCA.AutoCommit = False
SQLCA.DBParm = "ConnectString='DSN=Mobile15TestDB;UID=DBA;PWD=sql'; EnabledLocalDB='true'"

Notes:

  • EnabledLocalDB could have the following value pairs: 'true'/'false', 'yes'/'no', 1/0. When it is set to 'true', 'yes' or 1, it indicates that the mobile app is able to connect with the local/offline database on the mobile device.

  • The EnabledLocalDB parameter is specially provided and supported by PowerServer Mobile only, therefore, it will be ignored when executed in the PB application and the Web application, and will only take effect when executed in the mobile application.

  • The ConnectString parameter will be ignored when executed in the mobile application, because the connection with the local database (such as user name, password etc.) is configured separately in PowerServer Toolkit. For details, refer to Task 3: Configure the offline settings in Tutorial 4.

Step 2: Choose the method to connect with the local/offline database: by using the PB transaction object or by using the CacheName parameter of the PB transaction object, according to the database connection scenarios in the application.

Scenario 1: Connect with one local database in one transaction object. This method requires no special coding. You only need to input the transaction object name and configure the database file in PowerServer Toolkit. For detailed instructions, refer to Task 3: Configure the offline settings in Tutorial 4.

Scenario 2: Connect with more than one local database in one transaction object. This method requires special coding as well as configuration in PowerServer Toolkit. You will first need to create the data source for the corresponding database file in PowerServer Toolkit; if there are multiple local databases, then you should create multiple data sources; and then you need to add the CacheName parameter to the DBParm property of the transaction object and set its value to the data source.

For detailed instructions on how to create the data source in PowerServer Toolkit, refer to Task 3: Configure the offline settings in Tutorial 4. The CacheName parameter will take precedence over the transaction object if both transaction object and data source are configured in PowerServer Toolkit.

Here is the PowerBuilder code example for using the CacheName parameter to connect with the local/offline database. The CacheName parameter will be handled differently when executed in the mobile application than when executed in the PB application.

SQLCA.DBMS = "ODBC"
SQLCA.AutoCommit = False
SQLCA.DBParm = "ConnectString='DSN=Mobile15TestDB;UID=DBA;PWD=sql'; EnabledLocalDB='true'; CacheName='MyUltralite'"
connect;
……
disconnect;
SQLCA.DBMS = "ODBC"
SQLCA.AutoCommit = False
SQLCA.DBParm = "ConnectString='DSN=Mobile15TestDB;UID=DBA;PWD=sql'; EnabledLocalDB='true'; CacheName='MySQLite'"
connect;