<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>