Mobile Tutorial: Using InterBase ToGo with FireDAC (iOS and Android)

From RAD Studio
Jump to: navigation, search

Go Up to Mobile Tutorials: Mobile Application Development (iOS and Android)


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

Tip: To follow this tutorial, you need a license for IBToGo or IBLite:

  • If you purchased one of the following RAD Studio versions, you have received in Email a key for an unlimited development and deployment license for IBLite:
    • RAD Studio Rio Professional or higher All Editions
    • Delphi Rio Professional or higher with Mobile
  • If you are a trial user, your installation includes a trial license for IBToGo. You can test InterBase on iOS and Android by selecting your test license during the deployment step, as described in this tutorial. The trial licenses are installed with your trial product, in C:\Users\Public\Documents\Embarcadero\InterBase\redist\InterBase2020.

Follow the steps at IBLite and IBToGo Deployment Licensing to obtain and install your license file.

Note: On Android devices, InterBase ToGo apps require specific permissions to be set, specifically:
  • Read external storage (the database is placed in the external memory)
  • Write external storage (the database is placed in the external memory)
  • Internet (you need to connect with a remote server)

This tutorial describes the basic steps to browse data managed by InterBase ToGo on your iOS and Android devices through the FireDAC framework.

iOS Android

DBDemo iPod Runtime.png

DBDemo Runtime.png

Note: You can use FireDAC, dbExpress, and Interbase Express (IBX) components to build Interbase ToGo applications. For a detailed discussion on Interbase Express components usage in a Delphi application, read the Getting Started with InterBase Express article. For this tutorial, we will connect to Interbase ToGo using FireDAC.

Using FireDAC to Connect to the Database

FireDAC is a unique set of Universal Data Access Components for developing cross-platform database applications for Delphi and C++Builder. With its powerful common architecture, FireDAC enables native high-speed direct access from Delphi to InterBase, SQLite, MySQL, SQL Server, Oracle, PostgreSQL, IBM DB2, SQL Anywhere, Access, Firebird, Informix, and more.

  • For the mobile platforms, FireDAC supports InterBase ToGo as well as SQLite. These database products can run on iOS and Android 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 a mobile device.
Another tutorial discusses how to connect to Enterprise Database without using a client library on a mobile device; see Mobile Tutorial: Connecting to an Enterprise Database from a Mobile Client (iOS and Android).

Design and Set Up the User Interface

This tutorial uses TListView and TPanel components as the UI elements.

To set up a ListView and a Panel component, use the following steps:

  1. To create an HD Multi-Device Application, select either of the following:
    • File > New > Multi-Device Application - Delphi > Blank Application
    • File > New > Multi-Device Application - C++Builder > Blank Application
  2. Drop a TListView component on the form.
  3. In the Object Inspector, set the following properties of the ListView:
    • Set the Align property to Client, so that the ListView component uses the entire form.
    • Set the ItemAppearance to ListItemRightDetail.
    • Set the SearchVisible to true.
  4. Add a TPanel component to the form, and set the following properties in the Object Inspector:
    • Set the Align property for the TPanel component to Top.
  5. Add a TLabel component to the Panel, and set the following properties in the Object Inspector:
    • Set the Align property for the TLabel component to Client.
    • Set the Views to either iOS or Android.
    • Set the StyleLookup property to listboxitemlabel.
    • Set back the Views to Master.
    • Set the HorzAlign property in TextSettings to Center.
    • Set the Text property to DB DEMO.

Connecting to the Data

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

  1. On the Tool Palette, double-click the TFDConnection component.
    FDConnectionComp.png
  2. Right-click the TFDConnection component and choose Connection Editor.
  3. In the FireDAC Connection Editor, set the following parameters of the TFDConnection:
    1. Set the Driver ID property to IB.
    2. Set the Database parameter to:
      C:\Users\Public\Documents\Embarcadero\Studio\20.0\Samples\Data\dbdemos.gdb (location of the database)
      and click Open in the File Open dialog box.
    3. Set the User_name parameter to sysdba.
    4. Set the Password parameter to masterkey.
    5. Set the Protocol parameter to TCPIP.
      FDConnectionEditor.png

    6. Click the Test button to test the connection.
    7. Click OK to close the Connection Editor.
  4. In the Object Inspector, set the following properties of TFDConnection:
    1. Set the LoginPrompt property to False, so that the user is not prompted for a login.
    2. Set the Connected property to True.
      Note: If you get an error ("unavailable database") in the 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.
  5. Add a TFDQuery component to the form.
  6. Right-click the TFDQuery component and choose Query Editor.
    1. Write in the SQL Command Text editor select COMMON_NAME, SPECIES_NAME from BIOLIFE order by COMMON_NAME.
    2. Click the Execute button to see the command results.
      FDQueryCommandDBDemo.png

    3. Click OK to close the Query Editor.
  7. In the Object Inspector, set the Active property of the TFDQuery component to True.
  8. Open the LiveBindings Designer and connect the data and the user interface as follows:
    1. Click COMMON_NAME in FDQuery1, and drag the mouse cursor to Item.Text in ListView1.
      LiveBindingsDesignerCommon Name.png

      At this point, TBindSourceDB and TBindingsList components were added to the form.
    2. Click SPECIES_NAME in BindSourceDB1, and drag the mouse cursor to Item.Detail in ListView1.
      DBDemoDesignTime.png
  9. Add a TFDPhysIBDriverLink component to the form.
  10. Add a TFDGUIxWaitCursor component to the form.
Note: The Preparing a FireDAC Application for Run Time topic explains the use of the TFDGUIxWaitCursor and TFDPhysIBDriverLink components in a FireDAC application.

Deploying your Application to Mobile

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\Embarcadero\Studio\20.0\Samples\Data\dbdemos.gdb). On the mobile Device, the application is sand-boxed, and typically you can only read and write data that is located in the Documents folder (for iOS device) and internal storage (for Android device) under your application folder.

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

  • Deploy the database to the mobile device.
  • Check the configuration (to connect to the database file) to a local file under the Documents folder (for iOS device) or internal storage (for Android device).

Deploying InterBase ToGo Required Files and the Database File to Mobile

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

  • Interbase ToGo required file (the license file and other configuration files)
  • The database file (dbdemos.gdb)

Deploy these files to your application as follows:

  1. You can add the database to your project with one of the following two methods:
    • Right-click the project name in the Project Manager and select Add… from the context menu (or Project > Add to Project) to display the Add to Project dialog box. Navigate to the database location C:\Users\Public\Documents\Embarcadero\Studio\20.0\Samples\Data, select the database dbdemos.gdb and click Open.
    • Navigate to the database location C:\Users\Public\Documents\Embarcadero\Studio\20.0\Samples\Data and drag and drop the database dbdemos.gdb to the project in the Project Manager. Click Yes to confirm that you want to add the file to your project.
  2. After adding the database file, the Featured Files window displays. Select InterBase ToGo in the Feature Files, and then click OK to close the Featured Files dialog box.
    • Under the node InterBase ToGo you need to select the license to be used when deploying the application on the device.
      • The Tip at the beginning of this tutorial describes how to activate an InterBase license.
      • The suggested names for the license files available are listed in the Featured Files dialog, under the following name pattern: reg_*.txt.
        As you can see in the image below, the reg_ibtogo.txt license file is selected for this tutorial.
      • You might have received from Embarcadero a license file for IBToGo 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\Embarcadero\InterBase\redist\InterBase2020), 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.
    FeaturedFilesiOSAndroidDB.png

  3. Open the Deployment Manager by selecting Project > Deployment.
  4. Select Debug configuration - iOS Device - 32 bit platform, Debug configuration - iOS Device - 64 bit platform or Debug configuration - Android platform from the drop-down list of target platforms at the top of the Deployment Manager and see that the database dbdemos.gdb has been added to the platforms.
  5. See how the Remote Path of dbdemos.gdb has been set for iOS and Android platforms:
    • Remote Path on iOS Device platform: StartUp\Documents\
    ChangeToStartUpDocuments.png
    • Remote Path on Android platform: assets\internal\
    AddDBforAndroidAssets.png

As you just configured, when you run the app on the mobile device, the database file (dbdemos.gdb) is to be deployed to the Documents folder (for iOS platform) or internal storage (for Android platform) in the sandbox area of your multi-device application.

For the TFDConnection, create the BeforeConnect event handler as follows:

  1. In the Form Designer, select the TFDConnection component.
  2. In the Object Inspector, go to the Events tab and double-click the BeforeConnect event.
  3. Implement the event handler for the BeforeConnect event by adding the following code:
    • For Delphi:
    procedure TForm1.FDConnection1BeforeConnect(Sender: TObject);
begin
  {$IF DEFINED(iOS) or DEFINED(ANDROID)}
   FDConnection1.Params.Values['Protocol'] := 'Local';
   FDConnection1.Params.Values['Database'] :=  TPath.Combine(TPath.GetDocumentsPath, 'dbdemos.gdb');
  {$ENDIF}
end;

    The TPath record is declared in System.IOUtils unit, so you need to add System.IOUtils in the uses clause, as follows: 

    implementation

{$R *.fmx}
{$R *.NmXhdpiPh.fmx ANDROID}
{$R *.iPhone4in.fmx IOS}

uses System.IOUtils;

procedure TForm1.FDConnection1BeforeConnect(Sender: TObject);
//  previous code goes here
    • For C++:
    void __fastcall TForm1::SQLConnection1BeforeConnect(TObject *Sender)
{
  #if defined(_PLAT_IOS) || defined(_PLAT_ANDROID)
      FDConnection1->Params->Values["Protocol"] = "Local";
      FDConnection1->Params->Values["Database"] = System::Ioutils::TPath::Combine(System::Ioutils::TPath::GetDocumentsPath(), "dbdemos.gdb");
  #endif
}

    You need to add #include <System.IOUtils.hpp> in the unit (.cpp file).

Run Your Application on a Simulator or on a Mobile Device

Now your application is ready to run (Run > Run or press F9). You should be able to browse data just as you can in the IDE. You can narrow down the list using the Search Box.

iOS Android

IPodSearchDBDemo.png

Screenshot 2013-11-02-03-34-10.png

Troubleshooting

InterBase Issues

See the following section with detailed information about Interbase License Issues.

Note: Follow the steps at IBLite and IBToGo Deployment Licensing to obtain a valid license file.

Exception Handling Issues

If your application raises an exception without having proper exception handling code, your multi-device application 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 FDConnection1 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:

    Delphi: 

    procedure TForm1.Button1Click(Sender: TObject);
begin
  try
    FDConnection1.Connected := True;
    FDQuery1.Active := True;
  except
    on e: Exception do
    begin
      ShowMessage(e.Message);
    end;
  end;
end;

    C++: 

    void __fastcall TForm1::Button1Click(TObject *Sender) {
    try {
        FDConnection1->Connected = true;
        FDQuery1->Active = true;
    }
    catch(Exception &e) {
        ShowMessage(e.Message);
    }
}
  3. Check the error message.

See Also

Samples

Retrieved from "https://docwiki.embarcadero.com/RADStudio/Rio/e/index.php?title=Mobile_Tutorial:_Using_InterBase_ToGo_with_FireDAC_(iOS_and_Android)&oldid=270175"