Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
 Chapter Titles v

Chapter Titles
Chapter Titles .................................................................................................................. v
Table of Contents ......................................................................................................... vii
About the Author ........................................................................................................ xvii
About the Technical Reviewers .................................................................................. xix
Acknowledgements ..................................................................................................... xxi
Introduction ..................................................................................................................... 1
Chapter 1 Overview of FireDAC ..................................................................................... 5
Chapter 2 Connecting to Data ..................................................................................... 15
Chapter 3 Configuring FireDAC ................................................................................... 47
Chapter 4 Basic Data Access ...................................................................................... 81
Chapter 5 More Data Access ..................................................................................... 109
Chapter 6 Navigating and Editing Data .................................................................... 145
Chapter 7 Creating Indexes ....................................................................................... 165
Chapter 8 Searching Data .......................................................................................... 197
Chapter 9 Filtering Data ............................................................................................. 217
Chapter 10 Creating and Using Virtual Fields .......................................................... 259
Chapter 11 Persisting Data ........................................................................................ 297
Chapter 12 Understanding FDMemTables ................................................................ 329
Chapter 13 More FDMemTables: Cloned Cursors and Nested DataSets ............... 369
Chapter 14 The SQL Command Preprocessor ......................................................... 397
Chapter 15 Array DML ................................................................................................ 425
Chapter 16 Using Cached Updates ........................................................................... 439
Chapter 17 Understanding Local SQL ...................................................................... 487
Appendix A Code Download, Database Preparation, and Errata............................ 507
Index ............................................................................................................................ 519

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
 Table of Contents vii

Table of Contents
Dedication ......................................................................................................... 3
Chapter Titles .................................................................................................................. v
Table of Contents ......................................................................................................... vii
About the Author ........................................................................................................ xvii
Cary Jensen ................................................................................................... xvii
About the Technical Reviewers .................................................................................. xix
Dmitry Arefiev............................................................................................... xix
Holger Flick ................................................................................................... xix
Jens Fudge ...................................................................................................... xx
Bruce McGee .................................................................................................. xx
Acknowledgements ..................................................................................................... xxi
Introduction ..................................................................................................................... 1
Who Is This Book For ...................................................................................... 2
Conventions ...................................................................................................... 2
Chapter 1 Overview of FireDAC ..................................................................................... 5
FireDAC Features ............................................................................................. 6
Cross-Platform Support .......................................................................................... 7
Exceptional Support for Databases ......................................................................... 7
Flexible Queries Using the SQL Command Preprocessor ...................................... 8
Blazing Performance with Array DML ................................................................... 8
Support for a Variety of Query Execution Modes ................................................... 9
Powerful Monitoring Capabilities........................................................................... 9
Cached Updates .................................................................................................... 10
Result Set Persistence ............................................................................................ 10
Data Type Mapping ............................................................................................... 11
Local SQL .............................................................................................................. 11
Additional Features ............................................................................................... 12
Connection Recovery ................................................................................................................... 12
Advanced Transaction Support..................................................................................................... 12
Built-In Dialog Support ................................................................................................................ 12
Support for Database-Specific Services........................................................................................ 12
Customizable Data Access ........................................................................................................... 13
Batch Move Support ..................................................................................................................... 13

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
viii Delphi in Depth: FireDAC

Written in Object Pascal .............................................................................................................. 13

Chapter 2 Connecting to Data ...................................................................................... 15
Creating Unnamed Connections ..................................................................... 15
Creating Temporary Connections ......................................................................... 16
Defining a Temporary Connection Using FDConnection.Params........................ 26
Defining a Temporary Connection at Runtime ...................................................... 27
Creating Named Connections ......................................................................... 28
Creating Named Connections Definition Using the Database Explorer ............... 29
Creating a Named Connection Definition Using the FireDAC Explorer .............. 33
Creating a Persistent Connection .......................................................................... 36
Creating a Private Connection .............................................................................. 39
Connecting to Any Database Using ODBC .................................................... 41
Chapter 3 Configuring FireDAC ................................................................................... 47
Share Configuration Properties ....................................................................... 48
Configuration Property Inheritance ...................................................................... 48
Overriding Individual Configuration Properties ................................................... 50
Restoring Configuration Property Inheritance...................................................... 50
Configuring the Shared Properties .................................................................. 51
Fetch Options......................................................................................................... 54
General Fetching .......................................................................................................................... 56
Items to Fetch .............................................................................................................................. 57
Items to Cache ............................................................................................................................. 57
Master-Detail ............................................................................................................................... 57
Live Data Window ....................................................................................................................... 58
Format Options ...................................................................................................... 58
Data Mapping Rules .................................................................................................................... 60
Handling BCD/FmtBCD Type and DataSnap Compatibility....................................................... 62
Handling String Type ................................................................................................................... 62
Parameters Default Type.............................................................................................................. 63
Value Preprocessing .................................................................................................................... 63
Dataset Sorting............................................................................................................................. 64
Quotation Identifier...................................................................................................................... 64
Default Field Formats .................................................................................................................. 65
Resource Options ................................................................................................... 65
Command Text Processing .......................................................................................................... 67
Persistence Mode ......................................................................................................................... 68
Command Execution.................................................................................................................... 69
Connection Resources.................................................................................................................. 69
Update Options ...................................................................................................... 70

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
 Table of Contents ix

General Updating.......................................................................................................................... 72
Locking......................................................................................................................................... 72
Refreshing .................................................................................................................................... 73
Automatic Incrementing ............................................................................................................... 73
Posting Changes ........................................................................................................................... 74
Transaction Options .............................................................................................. 75
Isolation Level .............................................................................................................................. 76
Update Ability .............................................................................................................................. 76
Automatic Committing ................................................................................................................. 77
DBMS-Specific Parameters .......................................................................................................... 77
Disconnection Action ................................................................................................................... 78
Nesting ......................................................................................................................................... 78
Understanding UpdateOptions.UpdateMode .................................................. 78
Chapter 4 Basic Data Access ...................................................................................... 81
The User Interface and Data Binding ............................................................. 85
Navigation and VCL Data Links ........................................................................... 86
The DBNavigator ......................................................................................................................... 86
Multi-Record VCL Controls and Navigation: DBGrid and DBCtrlGrid ...................................... 89
Navigation and LiveBindings ................................................................................ 91
The BindNavigator ................................................................................................ 92
Position-Related LiveBindings .............................................................................. 94
Understanding FDTable.................................................................................. 97
Configuring an FDTable ....................................................................................... 97
Executing Datasets at Design Time ....................................................................... 99
Executing DataSets at Runtime ........................................................................... 100
When Should You Connect? ................................................................................ 100
Live Data Window ............................................................................................... 102
Executing Queries and Stored Procedures .................................................... 103
Executing Queries ............................................................................................... 103
Executing Stored Procedures ........................................................................ 105
Chapter 5 More Data Access ..................................................................................... 109
Parameterized Queries and Stored Procedures ............................................. 109
The Advantages of Parameters............................................................................ 110
Greater Flexibility ...................................................................................................................... 110
Improved Performance ............................................................................................................... 110
Prevention of SQL Injection ....................................................................................................... 111
Defining Parameters at Design Time .................................................................. 112
Parameterized FDQueries and the Query Editor................................................ 115

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
x Delphi in Depth: FireDAC

Defining Parameters at Runtime ......................................................................... 118

Taking Control of Updates: FDUpdateSQL ................................................. 121
Defining the Query .............................................................................................. 122
Configuring the DataSet ...................................................................................... 124
Creating the Parameterized FDUpdateSQL Queries .......................................... 128
FDCommand, FDTableAdapter, and FDMemTable .................................... 130
Managing Transactions ................................................................................. 133
Implicit and Explicit Transactions....................................................................... 133
Transaction Isolation ........................................................................................... 138
Dirty Read Isolation ................................................................................................................... 139
Read Committed Isolation ......................................................................................................... 139
Repeatable Read Isolation.......................................................................................................... 139
Nested Transactions............................................................................................. 139
Asynchronous Queries .................................................................................. 140
Monitoring FireDAC Queries ....................................................................... 141
Chapter 6 Navigating and Editing Data .................................................................... 145
Understanding Fields .................................................................................... 145
The Current Record....................................................................................... 148
Detecting Changes to Record State............................................................... 148
Calculating Performance..................................................................................... 152
Navigating Programmatically ....................................................................... 153
Basic Navigation .................................................................................................. 154
Have I Gone Too Far? Bof and Eof ..................................................................... 154
Using MoveBy ...................................................................................................... 155
Navigating Using RecNo ..................................................................................... 156
Scanning a FireDAC DataSet .............................................................................. 157
Disabling Controls While Navigating.................................................................. 157
Navigating Using Bookmarks .............................................................................. 160
Editing a DataSet ................................................................................................. 161
Chapter 7 Creating Indexes ........................................................................................ 165
Index Overview ............................................................................................. 166
Temporary Indexes ....................................................................................... 167
An Example of Creating Temporary Indexes at Runtime .................................... 168
Temporary Indexes and FormatOptions.SortOptions.......................................... 171
Persistent Indexes.......................................................................................... 172
Defining Persistent Indexes ................................................................................. 173
Creating Field-Based Indexes ............................................................................. 178
Creating a Field-Based Index at Design Time ........................................................................... 178
Selecting an Index at Design Time ............................................................................................ 179
Creating a Field-Based Index at Runtime .................................................................................. 180

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
 Table of Contents xi

Selecting an Index at Runtime .................................................................................................... 180

Creating Expression Indexes ............................................................................... 182
Creating Distinct Indexes .................................................................................... 184
Creating a Filter-Based Index ............................................................................. 186
Two Runtime Index Examples: Sorting a DBGrid On-The-Fly................... 190
Chapter 8 Searching Data .......................................................................................... 197
Searching FireDAC DataSets ....................................................................... 197
Simple Record-by-Record Searches .................................................................... 199
Searching with Indexes ........................................................................................ 200
Finding Data ............................................................................................................................... 201
Going to Data ............................................................................................................................. 204
Searching with Variants ...................................................................................... 207
Locating Data ............................................................................................................................. 208
Using Lookup ............................................................................................................................. 213
Chapter 9 Filtering Data ............................................................................................. 217
Filters ............................................................................................................ 217
Using a Range ..................................................................................................... 222
Setting Ranges ............................................................................................................................ 222
Using ApplyRange ..................................................................................................................... 228
Canceling a Range ...................................................................................................................... 231
A Comment About Ranges ......................................................................................................... 231
Using Filters.................................................................................................. 232
Basic Filters ........................................................................................................ 233
Special Filter Expressions ................................................................................... 234
Null Comparisons ....................................................................................................................... 236
String Functions ......................................................................................................................... 238
Date/Time Functions .................................................................................................................. 239
Miscellaneous Functions ............................................................................................................ 241
Escaping Wildcard Characters .................................................................................................... 242
FireDAC Scalar Functions.......................................................................................................... 243
Other Filter-Related Properties .......................................................................... 243
Using the OnFilterRecord Event Handler ........................................................... 245
Navigating Using a Filter.................................................................................... 246
Using Ranges and Filters Together..................................................................... 249
Master-Detail Views: Dynamically Filtered Detail Tables .......................... 250
Defining a Range-Based Dynamic Master-Detail Relationship.......................... 252
Defining a Parameter-Based Dynamic Master-Detail Relationship ................... 254
Detail Records and the FetchOptions.DetailDelay Property .............................. 258

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
xii Delphi in Depth: FireDAC

Chapter 10 Creating and Using Virtual Fields .......................................................... 259

Aggregate Fields ........................................................................................... 260
Creating Aggregate Fields................................................................................... 261
Adding the Aggregate Field ....................................................................................................... 264
Defining the Aggregate Expression ........................................................................................... 266
Setting Aggregate Index and Grouping Level ............................................................................ 268
Making the Aggregate Field Available ...................................................................................... 269
Turning Aggregates On and Off ................................................................................................ 272
Creating Aggregate Collection Items .................................................................. 272
Understanding Group State ........................................................................... 274
Creating AggregateFields at Runtime........................................................... 277
Calculated Fields ........................................................................................... 280
InternalCalc Fields and FireDAC Scalar Functions ........................................... 283
Lookup Fields ............................................................................................... 285
Understanding FieldOptions ......................................................................... 292
The FieldOptions Property .................................................................................. 293
Combine Options and PositionMode ................................................................... 295
The UpdatePersistent FieldOptions Property ..................................................... 295
Field and Fields Properties ................................................................................. 296
Chapter 11 Persisting Data......................................................................................... 297
Persisting Data to Files ................................................................................. 298
Saving to Files ..................................................................................................... 299
File formats ................................................................................................................................ 301
Storing Human-Readable Data .................................................................................................. 303
What to persist ........................................................................................................................... 305
Persisted Version Information ................................................................................................... 308
Loading from Files .............................................................................................. 309
File Formats ............................................................................................................................... 312
Merging Data When Loading .................................................................................................... 312
Automating Persistence ....................................................................................... 316
Maintaining Backups ........................................................................................... 317
Persisting to Streams ..................................................................................... 321
Saving to a Stream ............................................................................................... 322
Loading from a Stream ........................................................................................ 324
Persistence and FDSchemaAdapters............................................................. 326
Chapter 12 Understanding FDMemTables ................................................................ 329
The Role of FDMemTable in FireDAC Applications .................................. 330
Defining an FDMemTable's Structure .......................................................... 331

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
 Table of Contents xiii

Defining Structure Using FieldDefs .................................................................... 332

Creating FieldDefs at Design Time ............................................................................................ 332
Creating FieldDefs at Runtime ................................................................................................... 336
Defining an FDMemTable's Structure Using Fields ........................................... 339
Creating Fields at Design Time .................................................................................................. 339
Creating Fields at Runtime ......................................................................................................... 345
Loading FDMemTables Directly From DataSets ......................................... 347
Loading an FDMemTable Using CopyDataSet................................................... 348
Other FDDataSets and CopyDataSet .......................................................................................... 359
Copying Data Using the FDDataSet Data Property ........................................... 362
Editing Data at Design Time ........................................................................ 364
Chapter 13 More FDMemTables: Cloned Cursors and Nested DataSets ............... 369
Cloning and FDMemTables ......................................................................... 369
Master with Detail Clone .................................................................................... 371
Editing with Cloned Cursors and Cached Updates............................................. 375
Creating Nested DataSets ............................................................................. 379
Defining Nested DataSets at Design Time .......................................................... 380
Defining Nested DataSets at Runtime ................................................................. 384
Using FieldDefs at Runtime ....................................................................................................... 385
Using Fields at Runtime ............................................................................................................. 389
Final Thoughts About Nested DataSets ............................................................... 393
Chapter 14 The SQL Command Preprocessor ......................................................... 397
Macro Substitution........................................................................................ 400
Escape Sequences ......................................................................................... 406
Constant Substitution .......................................................................................... 407
Identifier Substitution .......................................................................................... 408
Conditional Substitution ...................................................................................... 409
FireDAC Scalar Functions .................................................................................. 412
FireDAC String/Character Scalar Functions .............................................................................. 415
Numeric Scalar Functions .......................................................................................................... 417
Date/Time Scalar Functions ....................................................................................................... 419
System Scalar Functions............................................................................................................. 421
The Convert Scalar Function ...................................................................................................... 422
Special Character Processing........................................................................ 423
Chapter 15 Array DML ................................................................................................ 425
Using Array DML......................................................................................... 426
Array DML Mode and Errors ....................................................................... 434

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
xiv Delphi in Depth: FireDAC

Handling Array DML Limits................................................................................ 437

Chapter 16 Using Cached Updates ............................................................................ 439
Cached Updates: The Basics ......................................................................... 441
Entering and Exiting Cached Updates ................................................................ 441
Detecting the Cache State .................................................................................... 442
Record Status and Change Filters ....................................................................... 444
What Has Changed? ............................................................................................ 447
Persisting the Cache ............................................................................................ 448
Managing the Cache ..................................................................................... 449
Canceling the Last Change .................................................................................. 449
Canceling a Specific Change ............................................................................... 450
Canceling All Updates ......................................................................................... 450
Clearing the Cache Without Canceling Changes ................................................ 451
Using Save Points ................................................................................................ 452
Applying Updates ......................................................................................... 453
Apply Updates Using Brute Force ....................................................................... 453
Calling the ApplyUpdates Method ....................................................................... 453
The ApplyUpdates Method in Automatic Mode ........................................................................ 457
ApplyUpdates and OnUpdateRecord ......................................................................................... 463
ApplyUpdates and Errors .................................................................................... 467
Managing Errors Following the Call to ApplyUpdates .............................................................. 467
Managing Errors Using Event Handlers .................................................................................... 469
Understanding Centralized Cached Updates ................................................ 477
Managing Master-Detail Tables in the Centralized Cached Updates Model ..... 481
Chapter 17 Understanding Local SQL ....................................................................... 487
Implementing Local SQL ............................................................................. 488
The Initial Setup ................................................................................................... 488
Configuring the SQLite Connection .................................................................... 492
Configuring the Datasets ..................................................................................... 493
Configuring FDLocalSQL ................................................................................... 495
Activating Local SQL Queries at Runtime ................................................... 499
Some Comments on FDLocalSQL ............................................................... 504
Appendix A Code Download, Database Preparation, and Errata ............................ 507
Code Download ............................................................................................ 507
Database Preparation .................................................................................... 509
Installation ........................................................................................................... 509
The DataPaths Unit ............................................................................................. 509
Using SharedDMVcl ............................................................................................ 512
The EMPLOYEE Named Connection .................................................................. 513

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
 Table of Contents xv

InterBase UDF Definitions.................................................................................. 515

Errata............................................................................................................. 517
Index ............................................................................................................................ 519

Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen

http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available
 Delphi in Depth: FireDAC, Copyright © 2017 Cary Jensen
http://www.JensenDataSystems.com/FireDACbook
ISBN: ISBN-10: 1546391274, ISBN-13: 978-1546391272, Ebook edition available