Using InterBase Lite and InterBase ToGo in Delphi iOS Applications - Step by Step Guide
With RAD Studio XE4 a new InterBase edition has been rolled out. The existing InterBase edition family (Server, Desktop, Developer and ToGo) has been enhanced by an edition called “IBLite”. This edition may be deployed for free with your applications. IBLite uses the embedded deployment model similar to the InterBase “ToGo” edition, some limitations apply though. Following is an overview of InterBase editions and their features and limitations:
(click on Images to enlarge)
The most important IBLite limitations are:
- Max. 100MB database size
- Max. 1 simultaneous transaction
If you need more space or transactions, then your other (paid though) option for iOS devices is the “ToGo” Edition. On mobile devices 100 MB with one transaction is very likely to be sufficient though.
Developing and Deploying InterBase Applications for iOS Devices
All following steps are identical for IBLite and InterBase ToGo.
License Keys
RadStudio XE4 comes with a free IBLite serial key and an InterBase ToGo serial key for test deployments. The ToGo serial key may only be used for testing deployments and is not meant to be published with apps to the App Store. To go into production with InterBase ToGo you need a separate InterBase ToGo deployment license. Please contact you local Embarcadero office for pricing and terms. The IBLite key that comes with XE4 is good to be used in production environment - it is completely free!
The keys look like this:
IBLite XE3 for iOS Deployment License
AAAA-BBBBBB-CCCCCC-DDDD
InterBase XE3 ToGo Test Deployment
AAAA-BBBBBB-CCCCCC-DDDD
The InterBase version that comes with RAD Studio XE4 / Delphi XE is „XE3“ - so don‘t get confused on the version numbers.
You need to register the keys and create a REG______.txt file, which will be deployed onto the device together with your app.
The registration process is a little tricky and hopefully Embarcadero will make that more convenient in the future. If anyone knows shortcuts to this process, then drop me a note, so that I can update this documentation.
After installing InterBase XE3 Developer Edition (which is usually done by the installation process of RAD Studio XE4) you need to launch the Embarcadero License Manager. The License Manager can be found in the InterBase bin directory.
These are the default location of the InterBase bin directory:
Windows 64bit
C:\Program Files (x86)\Embarcadero\RAD Studio\11.0\InterBaseXE3\bin\ LicenseManager.exe
Windows 32bit
C:\Program Files\Embarcadero\RAD Studio\11.0\InterBaseXE3\bin\ LicenseManager.exe
In the LicenseManager select Serial - Add from the Menu:
In the „Add Serial Number“ Dialog type in your IBLite or InterBase ToGo key and Press OK.
Now your key should show up in the Treeview under „Unregistered serial numbers“
License Registration
All license keys need to be registered with Embarcadero, to do so, open the context menu for the key you just entered and click „Register“
The Embarcadero Product Registration Dialog will pop up. That is the same dialog you have seen after you installed RAD Studio /Delphi itself:
The next Step is VERY IMPORTANT and different from the RAD Studio / Delphi registration process:
The online registration process does not work using this dialog, unfortunately. So, in other words: DO NOT REGISTER ONLINE with this dialog!
Did I mention this already?
DO NOT REGISTER ONLINE with this dialog!
Once again:
DO NOT REGISTER ONLINE with this dialog!
Remember:
DO NOT REGISTER ONLINE with this dialog!
Instead, open your Web browser and go to https://reg.codegear.com
Yes, use the CodeGear domain name as the SSL certificate is still under CodeGear‘s name and not under Embarcadero‘s. (Embarcadero Web master - I am looking at you SSL certificates are not that expensive any more. Certificate errors on embarcadero.com are ☺).
Enter your Serial Number and Registration Code from the LicenseManager into the Web form:
Press „Next“ in the Web form. The next step requires you to login with your Embarcadero EDN Account credentials.
After pressing „Next“ again, you should get the following „Product Registration“ Web form:
At the very bottom of that Web form you will find options to download or send per email an activation file for InterBase.
This activation file comes as REG___.txt, which you need to add to your iOS App, to get InterBase unlocked.
First, rename REG____.txt, depending on the edition you have chosen:
- reg_iblite.txt (IBLite)
- reg_ibtogo.txt (InterBase ToGo)
Copy the registration file(s) to:
C:\Users\Public\Documents\InterBase\redist\InterBaseXE3
Now you are ready to to develop your first iOS Application with RAD Studio/Delphi XE4 and InterBase
Sample Application
Create an new FireMonkey Mobile Application
Add a TButton and a TListbox to your blank main form.
Now add a new connection to the employee sample database. To do so open the Data Explorer Window in Delphi and select „Add New Connection“ under the IBLite/ToGo tree item and name the connection „Employee“.
In the Connection Configuration dialog add the path to Employee.gdb. This file can usually be found in Delphi‘s Sample folder, under „Data“. Default user name is „sysdba“, default password is „masterkey“ (without quotes). See the screenshot for details:
Double click / open the new „employee“ tree node to see all tables, that come with Employee.gdb.
Now drag and drop „employee“ from the tree onto your main form. This will automatically create a correctly configured TSQLConnection component on your form:
Remarks: In my sample I am storing Employee.gdb on the iOS device under
/Documents/data/employee.gdb. Of course you can use any directory which is available to your app on the device. Using the Documents folder has the advantage that everything in here will be included in the iOS Device backup process. This is true for local backups with iTunes or iCloud backups. The /tmp/ folder in contrast would not be backed up.
To connect to the database at runtime (on the iOS device that is), an IFDEF IOS is used in the „BeforeConnect“ event of the TSQLConnection to set the path to the database file.
In the „ButtonClick“ event add the following code:
Before running the App on the iOS simulator or iOS device we have to add some items to the Deployment Manager in which can be opened via menu item „Project - Deployment“
The Deployment Manager lists all files that get bundled and deployed with your App on the device. Important to note is that all items have a local path (on your development machine) and a remote path on the iOS device:
You need to add InterBase client files and the license file that you created earlier.
Remarks: Select „All Configurations“ in the Deployment Manager. Otherwise you will have to perform these steps for Simulator, Device and Debug/Release configurations separately.
First add some items from the „Featured Files“ dialog:
For IBLite use „InterBase ToGo“ too, as the different behavior between IBLite and InterBase ToGo is controlled by the license file.
After adding these items you will find them in the Deployment Manager‘s items list. You will also see two license files: reg_iblite.txt and reg_ibtogo.txt. Make sure that only ONE of them gets deployed, i.e. disable or remove either of them.
Now add the EMPLOYEE.GDB File to Deployment Manger:
After adding the file you need to change its remote path for the simulator and the device! To do so, double click the „Remote Path“ cell. Enter: „StartUp\Documents\data\“
Now save all files and run your first InterBase App on the iOS Device.
Good luck and have fun
Daniel Magin , Olaf Monien, Daniel Wolf
info ( a t ) Developer-Experts.net
Embarcadero MVP