1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
|
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>FlameRobin 0.8.6 Manual</title><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="frrelnotes"></a><span class="application">FlameRobin</span> 0.8.6 Manual</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Nando</span> <span class="surname">Dessena</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Milan</span> <span class="surname">Babuskov</span></h3></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#d0e23">About this manual</a></span></dt><dt><span class="section"><a href="#frrelnotes-alphatest">About the ALPHA test program</a></span></dt><dt><span class="section"><a href="#frrelnotes-what-fr-is">What FlameRobin is</a></span></dt><dt><span class="section"><a href="#frrelnotes-what-fr-is-not">What FlameRobin is NOT</a></span></dt><dt><span class="section"><a href="#frrelnotes-who-we-are">Who we are</a></span></dt><dt><span class="section"><a href="#frrelnotes-license">License</a></span></dt><dt><span class="section"><a href="#frrelnotes-changes">What's new?</a></span></dt><dt><span class="section"><a href="#frrelnotes-installation">Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e81">General information</a></span></dt><dt><span class="section"><a href="#d0e105">Windows (Win32)</a></span></dt><dt><span class="section"><a href="#d0e112">Linux</a></span></dt><dt><span class="section"><a href="#d0e119">MacOS X</a></span></dt></dl></dd><dt><span class="section"><a href="#frrelnotes-getting-started">Getting started / basic features</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e129">Adding a server</a></span></dt><dt><span class="section"><a href="#d0e134">Adding an existing database</a></span></dt><dt><span class="section"><a href="#d0e144">Creating a new database</a></span></dt><dt><span class="section"><a href="#d0e151">Connecting to a registered database</a></span></dt><dt><span class="section"><a href="#d0e156">Browsing metadata</a></span></dt><dt><span class="section"><a href="#d0e163">Editing objects</a></span></dt><dt><span class="section"><a href="#d0e171">Browsing and editing data</a></span></dt><dt><span class="section"><a href="#frmanual-running-sql-statements">Running SQL statements and scripts</a></span></dt><dt><span class="section"><a href="#d0e208">Backup and restore</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e218">Advanced features</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e223">DDL extraction</a></span></dt><dt><span class="section"><a href="#d0e232">Alter View functionality</a></span></dt><dt><span class="section"><a href="#d0e237">Creating a selectable stored procedure for a table</a></span></dt><dt><span class="section"><a href="#d0e242">Connected users</a></span></dt><dt><span class="section"><a href="#d0e247">Event monitoring</a></span></dt><dt><span class="section"><a href="#d0e252">User management</a></span></dt><dt><span class="section"><a href="#d0e260">Grant and revoke privileges</a></span></dt><dt><span class="section"><a href="#d0e265">Server and client version</a></span></dt><dt><span class="section"><a href="#d0e282">Advanced metadata search</a></span></dt><dt><span class="section"><a href="#d0e289">Logging</a></span></dt><dt><span class="section"><a href="#d0e302">Test data generator</a></span></dt></dl></dd><dt><span class="section"><a href="#frrelnotes-configuration">Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e315">General</a></span></dt><dt><span class="section"><a href="#d0e341">Main Tree View</a></span></dt><dt><span class="section"><a href="#d0e383">SQL Editor</a></span></dt><dt><span class="section"><a href="#d0e478">Data Grid</a></span></dt><dt><span class="section"><a href="#d0e523">Property Pages</a></span></dt><dt><span class="section"><a href="#d0e538">Sql Statement generation</a></span></dt><dt><span class="section"><a href="#d0e613">Fields</a></span></dt><dt><span class="section"><a href="#frmanual-conf-logging">Logging</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e648">Database configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e653">Main Tree View</a></span></dt><dt><span class="section"><a href="#d0e664">Connection</a></span></dt><dt><span class="section"><a href="#frmanual-dbconf-logging">Logging</a></span></dt></dl></dd><dt><span class="section"><a href="#d0e690">Customizing the FlameRobin environment</a></span></dt><dt><span class="section"><a href="#d0e732">Advanced topics</a></span></dt><dd><dl><dt><span class="section"><a href="#d0e737">Encrypted password storage</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e23"></a>About this manual</h2></div></div></div><p>We try to keep all the features in FlameRobin usable in an intuitive
manner. However, there are things that you still need to know if you want
to grasp the full power of the application, and this manual contains
details about them. In this document, you will find an overview of the
features, a description of all configuration parameters and advanced
installation and customization notes.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-alphatest"></a>About the ALPHA test program</h2></div></div></div><p>Lots of people have been using FlameRobin in day-to-day work for a
long time now. Yet, we still consider the software in ALPHA state until it
reaches feature-completeness, which will come with release 1.0. FlameRobin
is very near to that state. Meanwhile, we thank you for evaluating and
using this software and encourage you to send comments, bug reports and
feature requests back to us so we can make it a better product.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-what-fr-is"></a>What FlameRobin is</h2></div></div></div><p>FlameRobin is a GUI administration and data manipulation tool for
Firebird databases. It is designed to be small, simple and cross-platform,
yet offer all the basic features needed to administer Firebird servers and
create/maintain databases. FlameRobin is Open Source software and binaries
are currently available for Windows, several GNU/Linux and BSD flavours
and MacOS X. Ports to other platforms are possible, subject to the
availability of maintainers for those platforms.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-what-fr-is-not"></a>What FlameRobin is NOT</h2></div></div></div><p>FlameRobin is not a full-featured administration tool with lots of
bells and whistles, as there are plenty available for Firebird from
several different parties. Our first goal with FlameRobin is to provide
people not used to the command line with a GUI tool to get started with
Firebird. Our longer-term goal is to develop a richer tool mainly for the
Linux platform; while there are several rich and mature GUI tools under
Windows, some of them available for free or for a modest price, there
isn't any for Linux. Another goal of the project is for a "lite" edition
of FlameRobin to be bundled with the Firebird server to serve as a
starting kit for new users. This bundle may be distributed by the Firebird
Project itself or by some third party.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-who-we-are"></a>Who we are</h2></div></div></div><p>The home page of the FlameRobin project is located at <a href="http://www.flamerobin.org" target="_top">http://www.flamerobin.org</a>. The
project itself is hosted on <a href="http://sourceforge.net/projects/flamerobin" target="_top">SourceForge</a>.
Please use our mailing list (flamerobin-devel) to contact the developers.
Details and archives available <a href="http://sourceforge.net/mail/?group_id=124340" target="_top">here</a>. You are
also encouraged to use our <a href="http://sourceforge.net/tracker/?group_id=124340&atid=699234" target="_top">bugs</a>
and <a href="http://sourceforge.net/tracker/?group_id=124340&atid=699237" target="_top">feature
requests</a> trackers to report back to us the results of your alpha
testing. If you are a developer interested in joining the FlameRobin
project, let us know. We always welcome contributors.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-license"></a>License</h2></div></div></div><p>FlameRobin is released under the Expat License. You can find the
complete license text in the file fr_license.html, or <a href="http://www.flamerobin.org/license.html" target="_top">here</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-changes"></a>What's new?</h2></div></div></div><p>Please refer to fr_whatsnew.html for a detailed history of all the
changes since the previous release.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-installation"></a>Installation</h2></div></div></div><p>If you want to build FlameRobin from sources, please find
instructions on our web site or Subversion repository. In this section we
talk about installing the pre-built version of FlameRobin under all
currently supported platforms.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e81"></a>General information</h3></div></div></div><p>If you have installed a previous ALPHA version of FlameRobin which
is <span class="emphasis"><em>less than 0.4.0</em></span>, it is recommended that you
remove it before installing this version.</p><p>You won't be able to keep a config.ini file from an earlier
version, because the name and file format have changed in version
0.4.0.</p><p>You might be able to keep your servers.xml file, provided that you
rename it to fr_databases.conf and move it to your data folder.
FlameRobin will tell you the exact path of this file (which changes with
the platform) upon first startup, when it cannot find the file.</p><p>Here are the files used by FlameRobin to store configuration
information:</p><div class="itemizedlist"><ul type="disc"><li><p>fr_databases.conf is the list of Firebird servers and
databases you work with; FlameRobin will create it (and
automatically add the "localhost" server) when you run it for the
first time; then you can register new servers and databases.</p></li><li><p>fr_settings.conf stores FlameRobin's configuration
information, like the position and size of the main program window.
You don't need to edit it by hand.</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The location of these files changes with the platform, and it's
usually a directory owned by the current user. FlameRobin needs write
access to that folder.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e105"></a>Windows (Win32)</h3></div></div></div><p>To install FlameRobin under Windows you need the Firebird client
(gds32.dll for Firebird 1.0, fbclient.dll for Firebird 1.5 and up)
installed and available, then just run the automatic installer of
FlameRobin which will copy all required files in a directory of your
choice and optionally create desktop and start menu shortcuts.</p><p>If you need to uninstall FlameRobin you can do so from the start
menu icon (unless you told the installation program not to create one)
or from the Control Panel.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e112"></a>Linux</h3></div></div></div><p>While some Linux distributions might provide installation packages
suitable for specific versions of that distribuion, FlameRobin project
provides generic compressed archives containing the executable and all
needed files. There are two flavors, depending of your preferences. You
can use Gtk1 version, which runs faster and has less dependencies. It is
suitable for slower computers and should run out-of-the-box on most
distributions. Gtk2 version uses Gtk2 toolkit, so it looks nicer on the
screen and it also has Unicode support.</p><p>To install FlameRobin, just unpack the chosen .tar.bz2 archive, cd
into that directory and type "make install" as root. This will install
FlameRobin and all the needed files to appropriate locations. After
that, any user can type "flamerobin" to run the program.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e119"></a>MacOS X</h3></div></div></div><p>Installation on Mac OS X is an absolute no-brainer: just drag the
icon from the installation package to the folder you want the
application to live in. Unpacking is handled via double clicking the
downloaded file.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-getting-started"></a>Getting started / basic features</h2></div></div></div><p>Upon first startup, FlameRobin will show a "Home" tree containing
only the local server (localhost), and will invite you to create new
servers and databases as required. You'll also see a menu bar at the top
of the window, and a search bar and status bar at the bottom. Here is a
brief how-to for getting started with FlameRobin.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e129"></a>Adding a server</h3></div></div></div><p>You can add a server by right-clicking on "Home" and choosing
"Register server..." (alternatively, use the "Register server..."
command from the "Server" menu). You will have to specify a display name
and optionally the host name and TCP port number on which the Firebird
server listens. Leave the display name empty to have FlameRobin build
one automatically from the host name and port values (if you don't have
a host name, because yours is a local or embedded Firebird server, you
will be required to type in a display name manually). Once you have
added a server, you can register databases under its node.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e134"></a>Adding an existing database</h3></div></div></div><p>To access an existing database from FlameRobin you have to
register it. Registration will make FlameRobin remember the database
connection properties so you don't have to re-enter them every time.
Locate the correct server in the tree, right click it and choose
"Register existing database...". You will have to enter a display name,
type in or locate (or drag and drop) the database path (or alias name),
the user name and password.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you don't specify the password, FlameRobin will prompt for it
every time you try to connect to the database, which is the most
secure option. If you want to specify the password, you can have
FlameRobin optionally encrypt it in the configuration file.</p></div><p>You can also optionally specify a connection charset and
role.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e144"></a>Creating a new database</h3></div></div></div><p>To create a new, empty database, locate the desired server in the
tree, right click it and choose "Create new database...". You will then
need to input the database file or alias name, the user name and
password for the owner of the new database (use SYSDBA as the user name
and masterkey if you don't know what to put in these fields), the
character set, the role, the page size (the default value of 4096 is
just fine) and the SQL dialect (leave it set at 3 if you don't know what
a SQL dialect is). The new database will be created and registered
(which means it is available in FlameRobin).</p><p>You can also drop an existing registered database, optionally
keeping the FlameRobin registration information. Use the "Drop" menu
command to do that.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e151"></a>Connecting to a registered database</h3></div></div></div><p>Just double click on the database name in the tree, or right click
it and choose "Connect" or "Connect as...". Choose "Disconnect" to close
the connection to the database. This causes the load of essential
metadata information. FlameRobin tries to play well with slow network
connections by delaying metadata retrieval as much as possible, yet
connecting to a database still needs some data transfer beyond the
connection itself.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e156"></a>Browsing metadata</h3></div></div></div><p>Upon connection, the sub-tree under the database name is populated
with a description of the database structure (metadata). Browse the tree
to explore the metadata. You can also use the quick search feature to
locate a particular object in the tree. Just type the name of the object
you are looking for (use the "*" wildcard character for a partial match)
in the search box at the bottom of FlameRobin's main window and the
first object in the tree whose name matches your search string will be
highlighted. Now you can hit Enter to focus the tree and add the object
name (or search string) to the search box's drop-down list. For your
convenience, FlameRobin will remember your search strings for further
use. Click the arrow buttons next to the search box to move to the next
and previous matches.</p><p>There is also an advanced metadata search feature, which is
described later.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e163"></a>Editing objects</h3></div></div></div><p>You can view and/or change the properties of every object you see
in the tree by choosing the "Properties..." option from the object's
context menu or from the "Object" menu. Please note that currently not
all object types are supported in full (domain editing, for example, is
very basic ATM), but you'll find some level of support for all of them.
The property page is a HTML window with a summary of the object's
properties and links which open other pages or specific editors. Some of
the options are not yet available, but you can edit almost all aspects
of the most common objects (tables, views, stored procedures, and so
on). Please have a look at fr_whatsnew.html to see, well, what's
new.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Although we try to test the features as much as we can, this
is ALPHA software and you should only use it to work on backup
copies of your databases, or perform backup copies before using
FlameRobin on them. Having said that, we have to add that many users
(including us) have been using FlameRobin in their everyday Firebird
development for several years now without major problems.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e171"></a>Browsing and editing data</h3></div></div></div><p>After connecting to a database, locate a table, view or selectable
stored procedure of your interest in the tree and right-click it.
Choosing either "Select ... from ..." option will open the SQL editor
with the table/view data shown in the grid at the bottom. In the case of
selectable stored procedures with parameters, just the select statement
appears in the SQL editor, so you should fill the parameter values (if
you have any) and click the Execute button to see the data.</p><p>FlameRobin's data grid fetches data from the server in small
chunks, so that you don't have to wait for the fetch to complete if you
only look at the first few pages of rows. You can have the grid fetch
all data (in background) through the Fetch all records command in the
grid's context menu (there is also a configuration option to make
complete fetching the default behaviour, something we usually don't
recommend). Fetching a very large result set might take some time, so if
you change your mind you can use the Stop fetching all records
command.</p><p>Once you have some data in the grid, you can re-sort the data by
double clicking on column headers.</p><p>You can change the data through direct editing in the grid, add
new records by means of the Insert button (which opens a specialized
dialog box) and delete the currently selected record(s) by clicking the
Delete button. Confirm any changes by clicking the Commit button, or
cancel them through the Rollback button. Deleted records are still
displayed (on a red background color) until you commit, just in case you
change your mind.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Emptying a cell that displays a string field will set the
field's value to ''; if you want to set it to null, then delete all
contents and then hit the DEL key once more.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You can type the strings "NOW", "DATE", "TODAY", "TOMORROW",
"YESTERDAY" in cells of type date or timestamp, and the strings "NOW"
and "TIME" in cells of type time. They will be translated by
FlameRobin to their respective meanings.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>FlameRobin handles all interactive edit operations by generating
corresponding SQL statements. By default they are all logged in the
history, but you can turn logging off for an instance of the SQL
editor through the History/Enable logging menu command. You can also
to turn logging off globally or for a particular database, through the
preferences.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="frmanual-running-sql-statements"></a>Running SQL statements and scripts</h3></div></div></div><p>Of course you can use the SQL editor window to create and execute
arbitrary SQL statements. FlameRobin provides a rather advanced and
sophisticated, yet simple to use SQL editor. You can open a SQL editor
window by right clicking on a database node and choosing "Run a query".
The SQL editor tool offers script execution capabilities (including SET
AUTODDL and SET TERM support), load/save buttons, auto-completion and
call-tip features, commit/rollback, detailed execution statistics
(including but not limited to the query PLAN and the number of records
inserted, deleted, updated in each affected table), a data export tool
and more.</p><p>To execute a script (meaning a sequence of more than one SQL
statements), just load it (or drag and drop a file, or type it in) and
run it. To execute a single statement when more statements are present
in the editor, select it before clicking the Run button.</p><p>You can use the drop-down menus or the context menu in the SQL
editor as well as the buttons.</p><p>Auto-completion can be invoked automatically or manually (see the
rich set of configuration options about it), and supports table and
column names, procedure and function parameters, and so on.</p><p>To activate the data export tool, right click on the data grid.
The data export tool is currently able to copy the data to the
clipboard, generate SQL INSERT or UPDATE statements or export the data
to a HTML or CSV file. All options work on the whole grid contents or
just the selected parts. You can also multiple-select several different
grid "islands" and have the tool export them. This is particularly handy
to generate customized INSERT or UPDATE statements.</p><p>For SELECT statements, you can also drag and drop objects from the
tree view to visually build queries (provided the appropriate
configuration option is enabled). Dragging and dropping tables will
automatically create JOIN conditions (based on existing foreign key
definitions) in the statement you are building.</p><p>FlameRobin will try to let you edit whatever result set your
SELECT statement returns, or part of it. Fields that you cannot edit
will be displayed in a special background colour in the grid.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e208"></a>Backup and restore</h3></div></div></div><p>You can perform a database backup by right clicking on a database
and choosing "Backup database...". Choose "Restore database..." to
restore a backup file over the current database (you will have to
disconnect first). Choose "Restore backup into new database..." (this
time on the server node) to create a new database from a backup file.
You can drag and drop files in these windows.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>It is considered bad practice to restore a backup file over an
existing database.</p></div><p>The Backup and Restore tools work in background, so you are
allowed to continue working with FlameRobin while they proceed. You can
work on a database while it is being backed up, but you can't work on a
database while you are restoring it.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e218"></a>Advanced features</h2></div></div></div><p>This section illustrates features in FlameRobin that you won't
likely use every day, but often enough to make them useful to know.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e223"></a>DDL extraction</h3></div></div></div><p>You can generate DDL (Data Definition Language) creation scripts
for any object you have in the database, or even for the whole database.
Just open the DDL subpage of an object's property page to see the DDL
code that creates the object.</p><p>Extracting DDL scripts is useful if you want to replicate an
object's structure in a different database, or create a slightly
different object in the same database.</p><p>A shortcut command for extracting the entire database metadata is
available in the Advanced submenu of the database's context menu.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e232"></a>Alter View functionality</h3></div></div></div><p>Firebird doesn't have an ALTER VIEW DDL command, which means that
if you want to modify a view definition you need to DROP and CREATE it
back. But dropping an object in Firebird requires dropping all objects
that depend on it, and so on recursively. Doing this by hand is very
hard, especially if the database structure is complex. A unique feature
in FlameRobin, which you activate by righ-clicking a View object and
selecting the "Alter..." menu command (or selecting the "Alter..."
command from the "Object" menu after selecting a View), will generate a
script that drops all the objects that depend on the view (in the
correct order), drops and recreates the view, then recreates all the
objects (again, in the correct order). The script is pasted into the SQL
editor window so you can modify the view definition and recreate
everything with a single click.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e237"></a>Creating a selectable stored procedure for a table</h3></div></div></div><p>This feature, that you can use through the Create selectable
procedure command in each table's context menu (or the namesake item in
the Object menu), will open the SQL Editor on a CREATE PROCEDURE
statement; the procedure fetches and returns all records in the table,
and has an output parameter for each column. Since this is a pretty
common pattern, it is intended to be modified to suit your needs rather
than used as-is.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e242"></a>Connected users</h3></div></div></div><p>Select "Show connected users" at the database level (or in the
"Database" menu) to see a list of users connected to that database. This
only works reliably with the SuperServer variant of Firebird. If you are
using Firebird Classic you will see at most one user connection there,
which is yours.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e247"></a>Event monitoring</h3></div></div></div><p>FlameRobin allows you to listen for Firebird events interactively.
Just select the "Monitor events" command at the database level (or in
the "Database" menu) to open the Event Monitor window (you will need to
connect to the database first). This window allows you to monitor one or
more events, save the received events to a text file and load them back.
Events are posted from the database when the POST_EVENT statement is
called (and the transaction is committed).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e252"></a>User management</h3></div></div></div><p>Current versions of Firebird use a central server-wide user
repository. FlameRobin allows you to add, modify and delete user
accounts (but it will not allow you to delete the SYSDBA predefined
user) by means of the "Manage users..." option in the Server menu (or
the server's context menu item, or the Object menu item with the same
caption). It is Firebird's security policy that you need to be SYSDBA to
use this feature.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The proper way to change the SYSDBA password on LInux is to run
the changeDBAPassword.sh script in Firebird's bin directory. Otherwise
Firebird's startup and shutdown scripts won't be updated.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e260"></a>Grant and revoke privileges</h3></div></div></div><p>Every object in the database has a list of privileges that
identify the users and roles that can work with that object. On an
object's property page (in the "Privileges" subpage) you can view the
privleges associated with that object, and if you hover the mouse over
icons, you can see who granted them in the status bar. Clicking on the
"Grant and revoke privileges" link will open a dialog box that will help
granting and revoke privileges to that object (which you'll find
pre-selected in the dialog box) and/or other objects as well. The dialog
box allows you to build a list of grant/revoke SQL statements by
clicking on appropriate controls and then on the "Add To List" button.
When satisfied, click the "Execute All" button to run all the statements
in the SQL editor (which will also log them for future use, as with any
SQL statement executed in FlameRobin, if logging is enabled).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e265"></a>Server and client version</h3></div></div></div><p>Select "Retrieve server version" from the "Server" menu (or from a
server's context menu) to see a dialog box with the server's version
string. A server's version string reveals the exact build number of your
Firebird server and the platform it is running on. For example, a
version string equal to "WI-V1.5.2.4731 Firebird 1.5" means Firebird
1.5.2, build 4731, on Windows.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Currently FlameRobin doesn't show the version string of the
Firebird client it is using, for these reasons:</p><div class="itemizedlist"><ul type="disc"><li><p>Not all versions of Firebird support this feature, and
FlameRobin needs to stay compatible with all Firebird
versions.</p></li><li><p>At some point in the future FlameRobin will be able to load
different client libraries for different databases (at least on
platforms that support it). We will probably add the client
version display feature then.</p></li></ul></div></div><p>You can also look at the version string of the Firebird client
FlameRobin is using, in the About box (Help/About).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e282"></a>Advanced metadata search</h3></div></div></div><p>This feature, which you can fire through the lens button in
FleameRobin's main window, allows you to perform more advanced search
operations in your database's metadata (or in more databases at the same
time). You can search with wildcards, search on object names and
descriptions, in the DDL definition (which includes the source code for
triggers and stored procedures), and do other, more specialized, search
operations. Just add all criteria you need through the Add buttons, and
then click the Start search button. The criteria will be concatenated
with an "and" boolean operator, that is all of them must be satisfied
for an object to be included in the SEARCH RESULTS pane.</p><p>This feature is provided on an experimental basis, as we're
currently looking for suggestions about how to improve both the user
interface and the capabilities. We already have some ideas that will
radically change the appearance of this dialog box, but we thought users
might want to try it out so they can give us some good tips.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e289"></a>Logging</h3></div></div></div><p>The SQL Editor can log all executed statements to a text file, a
set of text files or a database table. This gives you the ability to
work visually and produce scripts to easily replicate sequences of
operations on other databases. For database logging, in a future
release, FlameRobin will also provide a visual interface to the log
table, so that you can view a list of modifications to an object.</p><p>Look <a href="#frmanual-conf-logging" title="Logging">here</a> for the
options you use to configure this feature globally, and <a href="#frmanual-dbconf-logging" title="Logging">here</a> for database-level logging
options.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e302"></a>Test data generator</h3></div></div></div><p>FlameRobin includes a test data generator which you can use to
create test databases with dummy data values. You can launch it through
the Database/Advanced/Test data generator. In the resulting dialog box
you can select the tables for which you want to generate data, how many
records you want to generate for each table, and the data generation
strategy on a per-colum basis. Among the available strategies you'll
find sequential values, random values, values taken from other columns,
values loaded from external files, and a customizable NULL ratio. Your
settings can be saved to an XML file and reloaded later. When you're
ready, hit Generate data and the database will be filled with test
data.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="frrelnotes-configuration"></a>Configuration</h2></div></div></div><p>This section documents the options you can set to tune FlameRobin's
behaviour to your liking. You can set the options by means of the
Preferences dialog, which is invoked through the "Preferences..." command
in the "View" menu. The Preferences are organized in categories; here is a
description of each category. Please read the tooltip that appears when
you move the mouse cursor over each option to know more about it.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Since new options are added to FlameRobin daily, this section of
the documentation will likely be out-of-date. Please refer to the
tooltips for fresh descriptions of all the available options.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e315"></a>General</h3></div></div></div><p>Here you can find options to tune the visual appearance and
behaviour of FlameRobin. You can choose whether FlameRobin will remember
the size and position of opened windows between sessions or not, whether
FlameRobin will ask for quit confirmation or not, and other such
things.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e320"></a>Center dialogs on their parent window</h4></div></div></div><p>Set this option to always have dialogs displayed at the center
of their parent window. Otherwise dialogs are displayed at a
system-defined position.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e325"></a>Remember window positions and sizes</h4></div></div></div><p>If you enable this option, FlameRobin will remember the position
and size of each window you open and will open the same window at the
same position and with the same time the next time. You can also
choose the granularity of this option for property pages and
backup/restore dialogs:</p><div class="itemizedlist"><ul type="disc"><li><p>Choose "Same settings for all objects" to store a single
set of values; this means that whenever an Object Properties
dialog is opened it will have the position and size of the last
Object Properties dialog used.</p></li><li><p>Select "Same settings for all objects of same type" to
store a set of values for each object type. This means that a
Table Properties dialog will have different settings than a
Trigger Properties dialog, but two Table Properties dialog will
share the same set of values.</p></li><li><p>The third option, "Separate settings for individual
objects", will make it so that every object's property page will
have a set of options of its own. This mode is the most
flexible, but consumes more disk space and memory.</p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e341"></a>Main Tree View</h3></div></div></div><p>Here you can tune the appearance and behaviour of FlameRobin's
metadata navigation tool, the main tree.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e346"></a>Order server entries alphabetically</h4></div></div></div><p>Set this option to have your servers displayed in alphabetical
order, otherwise they are displayed in the order they appear in
servers.xml.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e351"></a>Order database entries alphabetically</h4></div></div></div><p>Set this option to have your databases displayed in alphabetical
order, otherwise they are displayed in the order they appear in
servers.xml.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e356"></a>Show columns and parameters in tree</h4></div></div></div><p>Enable this option to have table/view columns and procedure
parameters displayed as tree nodes; otherwise, the tree stops at the
table/view or procedure level. In case you choose to have columns and
parameters displayed as tree nodes, you can also indicate whether you
wish that a double click on a table/view or procedure node opens the
relevant property page or expands the subtree.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e361"></a>When table, view or stored procedure is activated</h4></div></div></div><p>Here you choose what should happen when you double click on a
table, view or stored procedure node in the tree. Available options
include opening the property page, show columns as sub-nodes of the
selected node or select from the table, view or stored procedure to
see the data.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="frmanual-show-sys-tables"></a>Show system tables in tree</h4></div></div></div><p>The metadata for a Firebird database is stored in the database
itself, in a set of tables whose names start with RDB$, called the
system tables. There is usually no point in working with Firebird's
system tables directly, as FlameRobin already queries them and
translates the information in friendlier form for you: the tree view,
object property pages and various dialogs all display information
coming from the system tables. FlameRobin also allows to change the
database metadata in a safe way (that is, keeping the database
structure's integrity), something which is not guaranteed if you try
to edit the system tables directly.</p><p>For the rare cases in which a direct look at the system tables
is required, and you know exactly where and how to look, you can
enable this option, which will add all system tables for a database to
the tree. This will impose a slight performance penalty upon
connection.</p><p>You can override this setting at the database level.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e375"></a>Allow drag and drop query building</h4></div></div></div><p>The SQL editor allows you to drag and drop objects from the tree
view to visually build queries (see <a href="#frmanual-running-sql-statements" title="Running SQL statements and scripts">the relevant
section</a>). This feature may occasionally hang FlameRobin on
Linux, so we are proving this option to switch it off until the
problem is corrected in the wxWidgets library. Plus, you might want to
disable the feature, if you don't use it, in order to avoid spurious
start-drag operations when working with the mouse on the tree
view.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e383"></a>SQL Editor</h3></div></div></div><p>Use these options to customize the behaviour of the SQL Editor,
which is used in FlameRobin to execute any kind of system-generated or
user-supplied query.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e388"></a>Automatically commit DDL statements</h4></div></div></div><p>Enable this option to have FlameRobin automatically "click" the
Commit button on your part each time it detects a DDL (Data Definition
Language) statements. DDL statements are those that modify the
database structure (as opposed to DML, or Data Manipulation Language
statements, which modify the data). Firebird does support
transactional DDL, yet it is common practice to auto-commit these
statements to avoid unexpected behaviours (for example, adding a
column to an existing table and populate it through an UPDATE
statement in the same transaction can lead to unexpected results with
current versions of Firebird). This option sets a default state that
you can change with the script commands SET AUTODDL ON and SET AUTODDL
OFF.</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e393"></a>When text is selected in editor</h5></div></div></div><p>Leave this option to "Execute the entire buffer" if you don't
want to take advantage of FlameRobin's advanced selection handling.
If you set it to "Execute only the selection" you will be able to
type (or load) entire scripts in the SQL editor and only execute
single parts of them by selecting them and clicking the "Execute"
button. If you don't select anything, FlameRobin will execute the
whole text in the editor.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e398"></a>Treat selected text as a single statement</h5></div></div></div><p>If you only ever select a single statement at a time, then you
can save FlameRobin's parser some work by enabling this option. When
you disable it, instead, FlameRobin will parse the selected text
before executing it, break it into several statements if necessary
and send them to Firebird one at a time; this is necessary since
Firebird does not support executing more than one statement (i.e. a
script) at a time. It can also be used if you have CREATE PROCEDURE
or CREATE TRIGGER (or similar) statements with SET TERM. This way,
you can select and execute the CREATE statement, and you don't need
SET TERM at all.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e403"></a>Clear the messages when executing new statements</h5></div></div></div><p>The SQL Editor has a message pane that shows information about
each executed statement. By default this pane is cleared
automatically only when you end transaction. Set this option to have
FlameRobin clear it before executing a statement.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e408"></a>Display detailed query statistics</h5></div></div></div><p>Enable this option to have the SQL Editor show detailed
statistic information for each query, in addition to the query PLAN.
This includes number of fetches, marks, reads, writes; number of
inserts, updates, deletes; number of indexed vs sequential reads;
delta memory; execution time.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e413"></a>Enable call-tips for procedures and functions</h5></div></div></div><p>When this option is enabled, then each time you type an open
round bracket after a stored procedure or UDF name in the SQL
Editor, a floating tooltip (called a call-tip) will appear reminding
you what the input and output parameters of the stored procedure or
UDF are.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e418"></a>Show long line marker</h5></div></div></div><p>Activate this option to have the editor display a vertical
line that visually marks the place where a line break would occur if
lines couldn't be longer than a certain amount of characters. The
marker is only a visual indicator, as FlameRobin will not enforce
any limit to the length of text lines. You can also customize the
column at which the marker will appear.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e423"></a>Tab size</h5></div></div></div><p>Here you can set the number of space characters the SQL Editor
will render for each TAB.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e428"></a>Code Completion</h5></div></div></div><p>This page contains options to customize FlameRobin's code
completion feature.</p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d0e433"></a>Enable automatic invocation of completion list</h6></div></div></div><p>This is the general switch to turn automatic code completion
in the SQL Editor on or off. Disable it if you don't like code
completion windows that pop up while you write SQL code. If you
keep it enabled, then you can set a certain number of characters
you'll have to type before code completion kicks in, and choose to
disable code completion when a call-tip is displayed (as it would
close the call-tip window) or inside quoted text.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d0e438"></a>Manually invoke completion list on</h6></div></div></div><p>Code completion may also be invoked manually. Here you
select how (Ctrl+Space or Tab key).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d0e443"></a>Confirm completion with Enter</h6></div></div></div><p>Set this option to have the currently selected item in the
code completion window copied to the text buffer when you hit
Enter. Otherwise you can use the Tab key for that.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d0e448"></a>Load columns when required for completion</h6></div></div></div><p>FlameRobin only loads column definition data when requested
to do so (for example, when you double click a table name in the
tree view). Set this option to let FlameRobin load missing column
information automatically when needed to show an auto-complete
list.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e453"></a>Statement History</h5></div></div></div><p>FlameRobin can remember the statements you execute and allow
you to retrieve and re-execute past statements. This page allows you
to customize the feature.</p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d0e458"></a>Share SQL statement history</h6></div></div></div><p>You can have a single statement history list for all the
databases you work with ("Between all databases") or a separate
history list for each of them ("Don't share"). Additionally, you
can make it so that all databases with the same display name
(typically copies of the same database, or databases with the same
structures, on different servers) share a history list.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d0e463"></a>Limit history item size</h6></div></div></div><p>By default, each history list item is allowed to grow
without bounds. If you are concerned about the size of your
statement history lists, you can set an upper limit in Kilobytes
for each statement in the history list. Statements bigger than the
specified amount will not be added to the history list. This is
useful if you execute entire database-creation scripts
often.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d0e468"></a>Remember unsuccessfully executed buffers</h6></div></div></div><p>By default, only statements that are executed without errors
are added to the history list. Set this option to have FlameRobin
remember also statements that caused errors.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="d0e473"></a>Remember statements generated by FlameRobin</h6></div></div></div><p>FlameRobin translates as much visual operations as possible
to SQL statements. Uncheck this option to prevent this kind of
statements from being added to the history lists.</p></div></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e478"></a>Data Grid</h3></div></div></div><p>When you issue a SQL SELECT statement in the SQL Editor, then the
Data Grid comes into play to show the results. Here you customize its
appearance and behaviour.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e483"></a>Date format</h4></div></div></div><p>Choose the format you'd like for showing date and timestamp
values in the grid.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e488"></a>Time format</h4></div></div></div><p>Choose the format you'd like for showing time and timestamp
values in the grid.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e493"></a>Grid header font</h4></div></div></div><p>Choose a character font for the grid header (the column
names).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e498"></a>Grid cell font</h4></div></div></div><p>Choose a character font for the grid cells (the data).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e503"></a>Re-format float and double precision numbers</h4></div></div></div><p>If unchecked, decimal numbers are displayed as returned from
server; otherwise, they are formatted according to the specified
number of decimal digits.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e508"></a>Maximize data grid after execution of SELECT statement</h4></div></div></div><p>Here you can turn off an useful feature that will enlarge the
data grid to the maximum available size when a SQL SELECT statement
returns more than a specified number of rows.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e513"></a>Automatically fetch all records in result set</h4></div></div></div><p>Makes it so the grid will automatically fetch all records
whenever a SELECT statement is executed, instead of doing it in
batches.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e518"></a>Show BLOB data in the grid</h4></div></div></div><p>Check this option if you want to see data fetched from BLOB
fields in the grid. By default FlameRobin doesn't fetch BLOBs. You can
also set a threshold, thus telling FlameRobin to fetch at most a
specified amount of data for each BLOB. This allows you to see the
first part of every BLOB field automatically without risking to
download huge amounts of data for no gain. Check the "Show data for
binary BLOBs" if you want the above settings applied to binary BLOBs
as well (by default they are applied to text BLOBs only).</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e523"></a>Property Pages</h3></div></div></div><p>This section contains customization options for FlameRobin-s
property pages.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e528"></a>Show default column values</h4></div></div></div><p>Set this option to display the "Default" column in a table's
property page.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e533"></a>Show column descriptions</h4></div></div></div><p>Set this option to display the "Description" column in a table's
property page.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e538"></a>Sql Statement generation</h3></div></div></div><p>This page offers options to customize the way FlameRobin generated
SQL code, deals with object names in general, and quoted identifiers in
particular. If you don't know how quoted identifiers work in Firebird,
you should leave the relevant settings to their default values.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e543"></a>Use UPPER CASE keywords</h4></div></div></div><p>Uncheck this option if you prefer FlameRobin to use lowercase
keywords in generated SQL code.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e548"></a>Quote names only when needed</h4></div></div></div><p>Uncheck this option to have FlameRobin always quote object names
with " in dialect 3 databases. Leave it checked to let FlameRobin
detect on its own when it is needed to quote identifiers. The setting
"Quote names in mixed case" is only used for names entered by the user
(for example, when you add a new field to a table, you type in its
name).</p><p>If "Quote names only when needed" is checked and "Quote names in
mixed case" is not, FlameRobin will leave the name entered by the user
as it is, even if it is written in mixed case (unless the name is a
reserved word or contains non-ASCII characters, in which case it is
quoted).</p><p>Here are two use cases to better explain how these settings
interact with each other:</p><div class="table"><a name="d0e557"></a><p class="title"><b>Table 1. Case 1: "Quote names only when needed" = on; "Quote names
in mixed case" = off</b></p><div class="table-contents"><table summary="Case 1: "Quote names only when needed" = on; "Quote names
 in mixed case" = off" border="1"><colgroup><col><col></colgroup><tbody><tr><td>User enters</td><td>Turns into</td></tr><tr><td>FIELD1</td><td>FIELD1</td></tr><tr><td>Field1</td><td>Field1</td></tr><tr><td>Date</td><td>"Date"</td></tr></tbody></table></div></div><p><br class="table-break"></p><div class="table"><a name="d0e582"></a><p class="title"><b>Table 2. Case 2: "Quote names only when needed" = on; "Quote names
in mixed case" = on</b></p><div class="table-contents"><table summary="Case 2: "Quote names only when needed" = on; "Quote names
 in mixed case" = on" border="1"><colgroup><col><col></colgroup><tbody><tr><td>User enters</td><td>Turns into</td></tr><tr><td>FIELD1</td><td>FIELD1</td></tr><tr><td>Field1</td><td>"Field1"</td></tr><tr><td>Date</td><td>"Date"</td></tr></tbody></table></div></div><p><br class="table-break"> The rationale behind all this is that if you write a name
in mixed case, then you probably want it quoted (since you bothered to
mix the case). Some users, however, find this rule awkward and
unpredictable, and need a way to disable it.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e608"></a>Treat quote characters like other characters</h4></div></div></div><p>This setting determines what happens if you type the quote
character (") as a part of some name. Again, it only affects
user-entered names. One option (unchecked) is to ignore it, other is
to treat it like any other character (checked). Quotes are special
cases, since they need to be escaped (by doubling them). When this
setting is off, user can force quoting even when it is not required,
by writing the name quoted in the text box.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e613"></a>Fields</h3></div></div></div><p>Here you can customize the appearance of field types in the tree
and property windows.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e618"></a>When a column has a user-defined domain</h4></div></div></div><p>In this case you can choose to see after the column name the
domain name, the data type, or both.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e623"></a>When a table column is computed</h4></div></div></div><p>For computed columns, you can choose to see after the name the
data type or the computation expression, or both.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="frmanual-conf-logging"></a>Logging</h3></div></div></div><p>The SQL Editor can log all executed statements to a text file, a
set of text files or a database table. Here you set the relevant options
for file-based logging, while logging to a database table is decided
<a href="#frmanual-dbconf-logging" title="Logging">on a per-database
basis</a>.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e636"></a>Log DML statements</h4></div></div></div><p>When logging is enabled, by default only DDL (CREATE, ALTER,
DROP...) statements are logged. Turn this option on to enable logging
of DML (SELECT, INSERT, UPDATE, DELETE) statements as well.</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="d0e641"></a>Enable logging to file</h5></div></div></div><p>Here you choose whether you want to log statements or not,
select the log file name(s), and choose if you want to output for
each statement also a comment with the version of FlameRobin,
database and user name, and execution date and time. Each statement
can go into separate file, and it uses incremental numbers for
filenames. You can format your own filenames by using %d as a
placeholder for number. If you want numbers with fixed number of
digits, like 0003 instead of 3, then use %04d as placeholder, where
4 means four digits, and 0 means that it should be padded with
zeros.</p><p>There are also options to add a comment header to each logged
statement, and to add SET TERM statements if required.</p></div></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e648"></a>Database configuration</h2></div></div></div><p>There is a set of options in FlameRobin that you can set on a
per-database basis. You access the database configuration window by right
clicking on a database and selecting the "Database preferences..."
command, or selecting the same command from the "Database" menu. Like
global preferences, database preferences are organized in categories; here
is a description of each category. Please read the tooltip that appears
when you move the mouse cursor over each option to know more about
it.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e653"></a>Main Tree View</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e656"></a>Show system tables in tree</h4></div></div></div><p>This is a database-level override of the global option with the
same name described <a href="#frmanual-show-sys-tables" title="Show system tables in tree">here</a>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e664"></a>Connection</h3></div></div></div><p>This page holds options that apply to database connection and
database registration info.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e669"></a>Warn when connection charset is different from database
charset</h4></div></div></div><p>In Firebird it is quite an usual situation to have a single
character set for an entire database, and use that character set for
connecting to the database, otherwise string transliteration won't
work correctly. For this reason, FlameRobin will warn you on
connection if the two charsets don't match. There are cases, though,
in which you might want to connect to a database with a different
character set (for example when you use different charsets for
different tables or even columns, something Firebird allows), so here
you can turn off the warning for that particular database</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="frmanual-dbconf-logging"></a>Logging</h3></div></div></div><p>Please see the section about <a href="#frmanual-conf-logging" title="Logging">global logging configuration</a>. The
options are the same here, but they apply to the current database only.
There is an additional option to turn off logging for a particular
database only, while leaving it active for all the other
databases.</p><p>There are also additional options to enable logging to a database
table. The table is called <span class="symbol">FLAMEROBIN$LOG</span> and it is
created automatically the first time it's needed. Each record written to
this table gets an ID fetched by executing a SELECT statement that you
can customize. By default, FlameRobin fetches the values from a
generator called <span class="symbol">FLAMEROBIN$LOG_GEN</span>, which is created
on demand as well. You might want to set a custom SELECT statement if
you want to use the ID as some kind of metadata version number for your
database, in which case you define the logic to follow when generating
new IDs. For example, you could write a stored procedure and have
FlameRobin call it.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e690"></a>Customizing the FlameRobin environment</h2></div></div></div><p>FlameRobin needs, or creates, some external files. This section
documents what these files contain, and where they are found. While
FlameRobin is installed with usable default settings, it is possible to
fine-tune the installation for special uses or multiple users. For
example, you can change the icons, the HTML templates used as property
pages for the objects in a database, or where FlameRobin stores and looks
for its configuration files.</p><p>FlameRobin uses the following files and folders:</p><div class="itemizedlist"><ul type="disc"><li><p>fr_settings.conf; a file containing all settings you see in the
Preferences dialog box and other global settings of FlameRobin, like
position and size of open windows. FlameRobin needs write access
privileges to this file.</p></li><li><p>fr_databases.conf; a file containing all the servers and
databases defined in FlameRobin's Home tree. FlameRobin needs write
access privileges to this file.</p></li><li><p>the html-templates and conf-defs folders, which contain metadata
used to render some of FlameRobin's windows, and the docs folder,
containing documentation files that can be opened through FlameRobin's
main menu. FlameRobin only needs read access to the files in these
folders.</p></li></ul></div><p>Locations:</p><div class="itemizedlist"><ul type="disc"><li><p>$frhome is FlameRobin's home path. FlameRobin will find
html-templates, conf-defs and docs (which are immutable and integral
part of the FlameRobin distribution) in its home path. The home path
is usually the application folder (on Windows) and an otherwise
fixed folder on POSIX platforms.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Defining the environment variable FR_HOME will override this
path.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Passing -h <path> on FlameRobin's command line will
override this path and the environment variable as well.</p></div></li><li><p>$fruserhome is FlameRobin's user home path. FlameRobin will
find the conf files in its user home path. This path has to be
writable and may be common to all users on the machine or different
for each user. The user home path defaults to the user local data
directory, which varies with the platform.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Defining the environment variable FR_USER_HOME will override
this path.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Passing -uh <path> on FlameRobin's command line will
override this path and the environment variable as well.</p></div></li></ul></div><p>Additionally, the <path> specification in the
command line parameters -h and -uh, or the value of the environment
variables FR_HOME and FR_USER_HOME may be "$app", which translates to the
common data folder (the application folder on Windows and an otherwise
fixed folder on POSIX platforms), or "$user", which translates to the user
local data directory. Otherwise, it has to be a path (without the trailing
path delimiter).</p><p>FlameRobin will only ever write to files in $fruserhome. If
FlameRobin is configured so that these files are shared by several users
(or concurrent instances of FlameRobin), then no precaution is taken to
avoid overwriting other users' changes.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e732"></a>Advanced topics</h2></div></div></div><p>This section will document some advanced topics about how FlameRobin
works. The topics are not necessarily related, and are grouped here only
for convenience.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e737"></a>Encrypted password storage</h3></div></div></div><p>FlameRobin can use strong encryption to safely store your
passwords in the configuration file (fr_databases.conf). Here's how it
works in detail:</p><div class="itemizedlist"><ul type="disc"><li><p>all passwords (PW) are encrypted with a master password
(MPW)</p></li><li><p>the MPW alone is never saved into any file, it is only known
by the user</p></li><li><p>PW + MPW comprise the Cipher (which is stored in the .conf
file)</p></li><li><p>whenever a PW needs to be decrypted, the user is prompted for
the MPW</p></li><li><p>Cipher + MPW yield the PW</p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e758"></a>Defense from "known plain-text" attack</h4></div></div></div><p>If an attacker gets hold of FlameRobin's .conf file, and he
knows one of the PWs, he would be able to compute the MPW (as Cipher +
PW yield the MPW). In order to prevent this, FlameRobin uses the
following scheme:</p><div class="itemizedlist"><ul type="disc"><li><p>the string composed by MPW + username + database connection
string is used as a seed for some irreversible random number
generator (RNG) like ISAAC</p></li><li><p>the PW is encrypted with the numbers produced by the
RNG</p></li><li><p>since numbers are unique for each username + database
connection string, and RNG is not reversible, the attacker cannot
get MPW, and he also cannot decrypt any other password</p></li></ul></div><p>For more information on ISAAC see:
http://en.wikipedia.org/wiki/ISAAC
http://www.burtleburtle.net/bob/rand/isaacafa.html</p><p></p></div></div></div></div></body></html>
|
