Delphi iOS Tutorial: Using InterBase ToGo in an iOS Application

By: Tim DelChiaro

Abstract: Tutorial from the Delphi XE4 and RAD Studio XE4 Online Documentation

    iOS Tutorial: Using InterBase ToGo in an iOS Application


Go Up to iOS Tutorials: Delphi iOS Application Development



Before starting this tutorial, you should read and perform the following tutorial session:

Tip:  Following this tutorial requires a  license  for  IBToGo  or  IBLite . If you have purchased RAD Studio XE4 Professional and up, or Delphi XE4 Professional with Mobile and up, you have received a key for an unlimited development and deployment license for IBLite. If you are a trial user, and would like to test InterBase on iOS, you can get access to an IBToGo test deployment license during your trial. To activate your deployment trial license, please follow this link:  InterBase ToGo Deployment .

This tutorial describes the basic steps to browse data managed by InterBase ToGo on your iOS device through the dbExpress framework.


    Using dbExpress to Connect to the Database

dbExpress is a very fast database access framework, written in Delphi. RAD Studio provides drivers for most major databases, such as InterBase, Oracle, DB2, SQL Server, MySQL, Firebird, SQLite and ODBC. You can access these different databases using procedures similar to the procedure described here.

  • For the iOS platform, dbExpress supports InterBase ToGo as well as SQLite. These database products can run on iOS devices.
  • For other databases, such as Oracle, you need to have at least a client library. On Windows platforms, the client library is provided as a DLL to connect to. Therefore, you need to develop applications using middle-tier technologies such as DataSnap to connect to these database products from iOS devices.

Another tutorial discusses how to connect to Enterprise Database without using a client library on iOS device; see iOS Tutorial: Connecting to an Enterprise Database from an iOS Client Application.

    Design and Set Up the User Interface

This tutorial uses one TListBox component as the UI element.

To set up a ListBox component, use the following steps:

  1. To create an HD FireMonkey Mobile Application, select File > New > FireMonkey Mobile Application - Delphi > Blank Application.
  2. Drop a TListBox component on the form.
  3. In the Object Inspector, set the following properties of the ListBox:
    • Set the Align property to alClient, so that the ListBox component uses the entire form.
    • Set the DefaultItemStyles.ItemStyle property to listboxitembottomdetail.
  4. Right-click the TListBox component in either the Designer or the Editor, select Add Item, and add the following components:
  5. Close the Items Designer.
  6. Add a TLabel component to the TListBoxHeader, and set the following properties in the Object Inspector:
    • Set the Align property for the TLabel component to alClient.
    • Set the StyleLookup property to toollabel.
    • Set the TextAlign property to taCenter.
    • Set the Text property to DB DEMO.

    Connecting to the Data

Following are the basic steps to connect to data in a database using dbExpress:

  1. On the Tool Palette, double-click the TSQLConnection component.
  2. In the Object Inspector, set the following properties for TSQLConnection:
    1. This app uses InterBase ToGo, so set the Driver property to IBLite/ToGo.
    2. Set the LoginPrompt property to False, so that the user is not prompted for a login.
    3. Click the ellipsis [...] for the Params property, and set the Database value to C:\Users\Public\Documents\RAD Studio\11.0\Samples\Data\dbdemos.gdb (location of the database); then close the dialog box:

    4. Set the Connected property to True.
      Note: If you get an error ("unavailable database") on development environment, this means you do not have a current license for InterBase. The license of InterBase Developer Edition is included as part of the product for some product editions. For more information, see Troubleshooting.
  3. Add a TSQLDataSet component to the form, and set the following properties:
    1. Set the SQLConnection property to SQLConnection1 (the one that you added in a previous step).
    2. Set the CommandText property to select COMMON_NAME, SPECIES_NAME from BIOLIFE order by COMMON_NAME.
    3. Set the Active property to True.
  4. Open the LiveBindings Designer and connect the data and the user interface as follows:
    1. Click COMMON_NAME in BindSourceDB1, and drag the mouse cursor to Item.Text in ListBox1.

    2. Click SPECIES_NAME in BindSourceDB1, and drag the mouse cursor to Item.Detail in ListBox1.

    Deploying your Application to iOS

Up to this point, you have used InterBase on your desktop. This means that the actual database is located at your local hard disk drive (for example, C:\Users\Public\Documents\RAD Studio\11.0\Samples\Data\dbdemos.gdb). On the iOS Device, the application is sand-boxed, and typically you can only read and write data that is located in the Documents folder under your application folder.

To connect to a local database on iOS, you need to perform the following actions:

  • Deploy the database to the iOS Device.
  • Change the configuration (to connect to the database file) to a local file under the Documents folder.

    Deploy InterBase ToGo, dbExpress Driver, and the Database File to iOS

To execute your application on iOS, you need to deploy the following files:

  • Interbase ToGo
  • dbExpress Driver to InterBase
  • The database file (dbdemos.gdb)
  1. Open the Deployment Manager by selecting Project > Deployment.
  2. Select All-Configurations - iOS Simulator platform from the drop-down list of target platforms at the top of the Deployment Manager.
  3. Select Add Featured Files (DMgrAddFeatFiles.png):

  4. Select the following database modules, and then click OK to close the Featured Files dialog box:
    • InterBase ToGo. You need to select the license to be used when deploying the application on the device. The suggested names for the license files available are listed in theFeatured Files dialog, under the following name pattern: reg_*.txt. As you can see in the image below, for this tutorial, the reg_ibtogo.txt license file is selected.
      You might have received from Embarcadero a license file for ToGo or IBLite that has a pattern of reg_nnnnnnn.txt, where nnnnnnn is a generated number:
      • If you have saved that file over reg_ibtogo.txt or reg_iblite.txt in the location below (for example, C:\Users\Public\Documents\InterBase\redist\InterBaseXE3), you can just select the desired license.
      • If you have saved the file with its original name, then select Add Files (shown in the next step) and include the license file in the list of files that need to be deployed with the application.
    • DBExpress InterBase Driver

  5. Select Add Files, and select the database file (for example, C:\Users\Public\Documents\RAD Studio\11.0\Samples\Data\dbdemos.gdb).

  6. Select dbdemos.gdb, and change Remote Path to StartUp\Documents\.

  7. Select the Platforms column (double-click the ellipsis [...] in the row for dbdemos.gdb):
    1. Ensure that iOS Simulator and iOS Device are present for dbdemos.gdb.
    2. Remove Win32 from the list if it is present (you do not have to copy database files to the Win32 platform).
  8. Select All-Configurations - iOS Device platform, and make sure dbdemos.gdb is set to be deployed to StartUp\Documents\.

As you just configured, the database file (dbdemos.gdb) is to be deployed to the Documents folder in the sandbox area of your iOS app.

    Modify Your Code to Connect to a Local Database File on iOS

As described in the previous step, the TSQLConnection component is connected to a database on your local file system with an absolute path. So you need to replace the location of the file before connecting to the database, as follows:

  1. In the Form Designer, select the SQLConnection1 component.
  2. In the Object Inspector, double-click the Value field of the BeforeConnect event.
  3. Add the following code to this event handler:
procedure TForm1.SQLConnection1BeforeConnect(Sender: TObject);
    := GetHomePath + PathDelim
       + 'Documents' + PathDelim + 'dbdemos.gdb';

The GetHomePath function gives you the actual home location of an iOS app. Using the PathDelim constant is recommended, as PathDelim specifically uses the path delimiter of the target platform (instead of hard-coded delimiters, such as \ or /).

    Run Your Application on the iOS Simulator or an iOS Device

Now your application is ready to run. You should be able to browse data just as you can in the IDE. You can also narrow down the list using the Search Box as shown in the second image:

BrowseDataOniOS.PNG NarrowDownListWithFish.png


    InterBase License Issues

If you get an error ("unavailabale database") when you connect to the database in the development environment, this means you do not have a current license for InterBase.

  • A license for InterBase Developer Edition is included as part of the product for some product editions.
  • To activate the license of InterBase Developer Edition for a registered RAD Studio installation, go to the Embarcadero Product License Manager (click Start | All Programs | Embarcadero InterBase XE3).

    Exception Handling Issues

If your application raises an exception without having proper exception handling code, your iOS app simply crashes (disappears) at run time.

If you encounter a crash, you might want to connect manually to the database while you troubleshoot the issue using the following steps:
  1. Select the SQLConnection1 component, and change the Connected property to False.
  2. Drop a button on the form, and create the following event handler to manually connect to the database:
procedure TForm1.Button1Click(Sender: TObject);
    SQLConnection1.Connected := True;
    SQLDataSet1.Active := True;
    on e: Exception do

    Typical Errors and Resolutions

Following are typical errors that you might encounter when you connect to the database, and suggestions for resolving the issues:

Error on iOS Suggestion
GDBFileNotFound.PNG Check whether the dataBase file (dbdemos.gdb) is delivered to 'StartUp\Documents\'.
IBToGoLic.PNG Check whether the license file is delivered for InterBase ToGo.
NeedToPointLocalFile.PNG Check whether you pointed to the local file (add an event handler for the OnBeforeConnect event of the SQLConnection1 component).

    See Also

Server Response from: ETNASC04