<?xml version="1.0" encoding="UTF-8"?>
<!-- For standalone validation, uncomment the following DOCTYPE declaration. -->
<!--
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-->
<article id="frrelnotes">
  <articleinfo>
    <title><application>FlameRobin</application> 0.8.6 Manual</title>

    <author>
      <firstname>Nando</firstname>

      <surname>Dessena</surname>
    </author>

    <author>
      <firstname>Milan</firstname>

      <surname>Babuskov</surname>
    </author>
  </articleinfo>

  <section>
    <title>About this manual</title>

    <para>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.</para>
  </section>

  <section id="frrelnotes-alphatest">
    <title>About the ALPHA test program</title>

    <para>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.</para>
  </section>

  <section id="frrelnotes-what-fr-is">
    <title>What FlameRobin is</title>

    <para>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.</para>
  </section>

  <section id="frrelnotes-what-fr-is-not">
    <title>What FlameRobin is NOT</title>

    <para>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.</para>
  </section>

  <section id="frrelnotes-who-we-are">
    <title>Who we are</title>

    <para>The home page of the FlameRobin project is located at <ulink
    url="http://www.flamerobin.org">http://www.flamerobin.org</ulink>. The
    project itself is hosted on <ulink
    url="http://sourceforge.net/projects/flamerobin">SourceForge</ulink>.
    Please use our mailing list (flamerobin-devel) to contact the developers.
    Details and archives available <ulink
    url="http://sourceforge.net/mail/?group_id=124340">here</ulink>. You are
    also encouraged to use our <ulink
    url="http://sourceforge.net/tracker/?group_id=124340&amp;atid=699234">bugs</ulink>
    and <ulink
    url="http://sourceforge.net/tracker/?group_id=124340&amp;atid=699237">feature
    requests</ulink> 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.</para>
  </section>

  <section id="frrelnotes-license">
    <title>License</title>

    <para>FlameRobin is released under the Expat License. You can find the
    complete license text in the file fr_license.html, or <ulink
    url="http://www.flamerobin.org/license.html">here</ulink>.</para>
  </section>

  <section id="frrelnotes-changes">
    <title>What's new?</title>

    <para>Please refer to fr_whatsnew.html for a detailed history of all the
    changes since the previous release.</para>
  </section>

  <section id="frrelnotes-installation">
    <title>Installation</title>

    <para>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.</para>

    <section>
      <title>General information</title>

      <para>If you have installed a previous ALPHA version of FlameRobin which
      is <emphasis>less than 0.4.0</emphasis>, it is recommended that you
      remove it before installing this version.</para>

      <para>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.</para>

      <para>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.</para>

      <para>Here are the files used by FlameRobin to store configuration
      information:</para>

      <itemizedlist>
        <listitem>
          <para>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.</para>
        </listitem>

        <listitem>
          <para>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.</para>
        </listitem>
      </itemizedlist>

      <note>
        <para>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.</para>
      </note>
    </section>

    <section>
      <title>Windows (Win32)</title>

      <para>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.</para>

      <para>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.</para>
    </section>

    <section>
      <title>Linux</title>

      <para>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.</para>

      <para>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.</para>
    </section>

    <section>
      <title>MacOS X</title>

      <para>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.</para>
    </section>
  </section>

  <section id="frrelnotes-getting-started">
    <title>Getting started / basic features</title>

    <para>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.</para>

    <section>
      <title>Adding a server</title>

      <para>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.</para>
    </section>

    <section>
      <title>Adding an existing database</title>

      <para>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.</para>

      <note>
        <para>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.</para>
      </note>

      <para>You can also optionally specify a connection charset and
      role.</para>
    </section>

    <section>
      <title>Creating a new database</title>

      <para>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).</para>

      <para>You can also drop an existing registered database, optionally
      keeping the FlameRobin registration information. Use the "Drop" menu
      command to do that.</para>
    </section>

    <section>
      <title>Connecting to a registered database</title>

      <para>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.</para>
    </section>

    <section>
      <title>Browsing metadata</title>

      <para>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.</para>

      <para>There is also an advanced metadata search feature, which is
      described later.</para>
    </section>

    <section>
      <title>Editing objects</title>

      <para>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.<note>
          <para>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.</para>
        </note></para>
    </section>

    <section>
      <title>Browsing and editing data</title>

      <para>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.</para>

      <para>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.</para>

      <para>Once you have some data in the grid, you can re-sort the data by
      double clicking on column headers.</para>

      <para>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.</para>

      <note>
        <para>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.</para>
      </note>

      <note>
        <para>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.</para>
      </note>

      <note>
        <para>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.</para>
      </note>
    </section>

    <section id="frmanual-running-sql-statements">
      <title>Running SQL statements and scripts</title>

      <para>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.</para>

      <para>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.</para>

      <para>You can use the drop-down menus or the context menu in the SQL
      editor as well as the buttons.</para>

      <para>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.</para>

      <para>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.</para>

      <para>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.</para>

      <para>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.</para>
    </section>

    <section>
      <title>Backup and restore</title>

      <para>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.</para>

      <note>
        <para>It is considered bad practice to restore a backup file over an
        existing database.</para>
      </note>

      <para>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.</para>
    </section>
  </section>

  <section>
    <title>Advanced features</title>

    <para>This section illustrates features in FlameRobin that you won't
    likely use every day, but often enough to make them useful to know.</para>

    <section>
      <title>DDL extraction</title>

      <para>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.</para>

      <para>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.</para>

      <para>A shortcut command for extracting the entire database metadata is
      available in the Advanced submenu of the database's context menu.</para>
    </section>

    <section>
      <title>Alter View functionality</title>

      <para>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.</para>
    </section>

    <section>
      <title>Creating a selectable stored procedure for a table</title>

      <para>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.</para>
    </section>

    <section>
      <title>Connected users</title>

      <para>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.</para>
    </section>

    <section>
      <title>Event monitoring</title>

      <para>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).</para>
    </section>

    <section>
      <title>User management</title>

      <para>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.</para>

      <note>
        <para>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.</para>
      </note>
    </section>

    <section>
      <title>Grant and revoke privileges</title>

      <para>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).</para>
    </section>

    <section>
      <title>Server and client version</title>

      <para>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.</para>

      <note>
        <para>Currently FlameRobin doesn't show the version string of the
        Firebird client it is using, for these reasons:</para>

        <itemizedlist>
          <listitem>
            <para>Not all versions of Firebird support this feature, and
            FlameRobin needs to stay compatible with all Firebird
            versions.</para>
          </listitem>

          <listitem>
            <para>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.</para>
          </listitem>
        </itemizedlist>
      </note>

      <para>You can also look at the version string of the Firebird client
      FlameRobin is using, in the About box (Help/About).</para>
    </section>

    <section>
      <title>Advanced metadata search</title>

      <para>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.</para>

      <para>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.</para>
    </section>

    <section>
      <title>Logging</title>

      <para>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.</para>

      <para>Look <link linkend="frmanual-conf-logging">here</link> for the
      options you use to configure this feature globally, and <link
      linkend="frmanual-dbconf-logging">here</link> for database-level logging
      options.</para>
    </section>

    <section>
      <title>Test data generator</title>

      <para>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.</para>
    </section>
  </section>

  <section id="frrelnotes-configuration">
    <title>Configuration</title>

    <para>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.</para>

    <note>
      <para>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.</para>
    </note>

    <section>
      <title>General</title>

      <para>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.</para>

      <section>
        <title>Center dialogs on their parent window</title>

        <para>Set this option to always have dialogs displayed at the center
        of their parent window. Otherwise dialogs are displayed at a
        system-defined position.</para>
      </section>

      <section>
        <title>Remember window positions and sizes</title>

        <para>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:</para>

        <para><itemizedlist>
            <listitem>
              <para>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.</para>
            </listitem>

            <listitem>
              <para>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.</para>
            </listitem>

            <listitem>
              <para>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.</para>
            </listitem>
          </itemizedlist></para>
      </section>
    </section>

    <section>
      <title>Main Tree View</title>

      <para>Here you can tune the appearance and behaviour of FlameRobin's
      metadata navigation tool, the main tree.</para>

      <section>
        <title>Order server entries alphabetically</title>

        <para>Set this option to have your servers displayed in alphabetical
        order, otherwise they are displayed in the order they appear in
        servers.xml.</para>
      </section>

      <section>
        <title>Order database entries alphabetically</title>

        <para>Set this option to have your databases displayed in alphabetical
        order, otherwise they are displayed in the order they appear in
        servers.xml.</para>
      </section>

      <section>
        <title>Show columns and parameters in tree</title>

        <para>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.</para>
      </section>

      <section>
        <title>When table, view or stored procedure is activated</title>

        <para>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.</para>
      </section>

      <section id="frmanual-show-sys-tables">
        <title>Show system tables in tree</title>

        <para>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.</para>

        <para>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.</para>

        <para>You can override this setting at the database level.</para>
      </section>

      <section>
        <title>Allow drag and drop query building</title>

        <para>The SQL editor allows you to drag and drop objects from the tree
        view to visually build queries (see <link
        linkend="frmanual-running-sql-statements">the relevant
        section</link>). 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.</para>
      </section>
    </section>

    <section>
      <title>SQL Editor</title>

      <para>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.</para>

      <section>
        <title>Automatically commit DDL statements</title>

        <para>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.</para>

        <section>
          <title>When text is selected in editor</title>

          <para>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.</para>
        </section>

        <section>
          <title>Treat selected text as a single statement</title>

          <para>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.</para>
        </section>

        <section>
          <title>Clear the messages when executing new statements</title>

          <para>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.</para>
        </section>

        <section>
          <title>Display detailed query statistics</title>

          <para>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.</para>
        </section>

        <section>
          <title>Enable call-tips for procedures and functions</title>

          <para>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.</para>
        </section>

        <section>
          <title>Show long line marker</title>

          <para>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.</para>
        </section>

        <section>
          <title>Tab size</title>

          <para>Here you can set the number of space characters the SQL Editor
          will render for each TAB.</para>
        </section>

        <section>
          <title>Code Completion</title>

          <para>This page contains options to customize FlameRobin's code
          completion feature.</para>

          <section>
            <title>Enable automatic invocation of completion list</title>

            <para>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.</para>
          </section>

          <section>
            <title>Manually invoke completion list on</title>

            <para>Code completion may also be invoked manually. Here you
            select how (Ctrl+Space or Tab key).</para>
          </section>

          <section>
            <title>Confirm completion with Enter</title>

            <para>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.</para>
          </section>

          <section>
            <title>Load columns when required for completion</title>

            <para>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.</para>
          </section>
        </section>

        <section>
          <title>Statement History</title>

          <para>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.</para>

          <section>
            <title>Share SQL statement history</title>

            <para>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.</para>
          </section>

          <section>
            <title>Limit history item size</title>

            <para>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.</para>
          </section>

          <section>
            <title>Remember unsuccessfully executed buffers</title>

            <para>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.</para>
          </section>

          <section>
            <title>Remember statements generated by FlameRobin</title>

            <para>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.</para>
          </section>
        </section>
      </section>
    </section>

    <section>
      <title>Data Grid</title>

      <para>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.</para>

      <section>
        <title>Date format</title>

        <para>Choose the format you'd like for showing date and timestamp
        values in the grid.</para>
      </section>

      <section>
        <title>Time format</title>

        <para>Choose the format you'd like for showing time and timestamp
        values in the grid.</para>
      </section>

      <section>
        <title>Grid header font</title>

        <para>Choose a character font for the grid header (the column
        names).</para>
      </section>

      <section>
        <title>Grid cell font</title>

        <para>Choose a character font for the grid cells (the data).</para>
      </section>

      <section>
        <title>Re-format float and double precision numbers</title>

        <para>If unchecked, decimal numbers are displayed as returned from
        server; otherwise, they are formatted according to the specified
        number of decimal digits.</para>
      </section>

      <section>
        <title>Maximize data grid after execution of SELECT statement</title>

        <para>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.</para>
      </section>

      <section>
        <title>Automatically fetch all records in result set</title>

        <para>Makes it so the grid will automatically fetch all records
        whenever a SELECT statement is executed, instead of doing it in
        batches.</para>
      </section>

      <section>
        <title>Show BLOB data in the grid</title>

        <para>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).</para>
      </section>
    </section>

    <section>
      <title>Property Pages</title>

      <para>This section contains customization options for FlameRobin-s
      property pages.</para>

      <section>
        <title>Show default column values</title>

        <para>Set this option to display the "Default" column in a table's
        property page.</para>
      </section>

      <section>
        <title>Show column descriptions</title>

        <para>Set this option to display the "Description" column in a table's
        property page.</para>
      </section>
    </section>

    <section>
      <title>Sql Statement generation</title>

      <para>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.</para>

      <section>
        <title>Use UPPER CASE keywords</title>

        <para>Uncheck this option if you prefer FlameRobin to use lowercase
        keywords in generated SQL code.</para>
      </section>

      <section>
        <title>Quote names only when needed</title>

        <para>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).</para>

        <para>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).</para>

        <para>Here are two use cases to better explain how these settings
        interact with each other:<table>
            <title>Case 1: "Quote names only when needed" = on; "Quote names
            in mixed case" = off</title>

            <tgroup cols="2">
              <tbody>
                <row>
                  <entry>User enters</entry>

                  <entry>Turns into</entry>
                </row>

                <row>
                  <entry>FIELD1</entry>

                  <entry>FIELD1</entry>
                </row>

                <row>
                  <entry>Field1</entry>

                  <entry>Field1</entry>
                </row>

                <row>
                  <entry>Date</entry>

                  <entry>"Date"</entry>
                </row>
              </tbody>
            </tgroup>
          </table><table>
            <title>Case 2: "Quote names only when needed" = on; "Quote names
            in mixed case" = on</title>

            <tgroup cols="2">
              <tbody>
                <row>
                  <entry>User enters</entry>

                  <entry>Turns into</entry>
                </row>

                <row>
                  <entry>FIELD1</entry>

                  <entry>FIELD1</entry>
                </row>

                <row>
                  <entry>Field1</entry>

                  <entry>"Field1"</entry>
                </row>

                <row>
                  <entry>Date</entry>

                  <entry>"Date"</entry>
                </row>
              </tbody>
            </tgroup>
          </table> 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.</para>
      </section>

      <section>
        <title>Treat quote characters like other characters</title>

        <para>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.</para>
      </section>
    </section>

    <section>
      <title>Fields</title>

      <para>Here you can customize the appearance of field types in the tree
      and property windows.</para>

      <section>
        <title>When a column has a user-defined domain</title>

        <para>In this case you can choose to see after the column name the
        domain name, the data type, or both.</para>
      </section>

      <section>
        <title>When a table column is computed</title>

        <para>For computed columns, you can choose to see after the name the
        data type or the computation expression, or both.</para>
      </section>
    </section>

    <section id="frmanual-conf-logging">
      <title>Logging</title>

      <para>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
      <link linkend="frmanual-dbconf-logging">on a per-database
      basis</link>.</para>

      <section>
        <title>Log DML statements</title>

        <para>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.</para>

        <section>
          <title>Enable logging to file</title>

          <para>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.</para>

          <para>There are also options to add a comment header to each logged
          statement, and to add SET TERM statements if required.</para>
        </section>
      </section>
    </section>
  </section>

  <section>
    <title>Database configuration</title>

    <para>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.</para>

    <section>
      <title>Main Tree View</title>

      <section>
        <title>Show system tables in tree</title>

        <para>This is a database-level override of the global option with the
        same name described <link
        linkend="frmanual-show-sys-tables">here</link>.</para>
      </section>
    </section>

    <section>
      <title>Connection</title>

      <para>This page holds options that apply to database connection and
      database registration info.</para>

      <section>
        <title>Warn when connection charset is different from database
        charset</title>

        <para>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</para>
      </section>
    </section>

    <section id="frmanual-dbconf-logging">
      <title>Logging</title>

      <para>Please see the section about <link
      linkend="frmanual-conf-logging">global logging configuration</link>. 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.</para>

      <para>There are also additional options to enable logging to a database
      table. The table is called <symbol>FLAMEROBIN$LOG</symbol> 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 <symbol>FLAMEROBIN$LOG_GEN</symbol>, 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.</para>
    </section>
  </section>

  <section>
    <title>Customizing the FlameRobin environment</title>

    <para>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.</para>

    <para>FlameRobin uses the following files and folders:</para>

    <itemizedlist>
      <listitem>
        <para>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.</para>
      </listitem>

      <listitem>
        <para>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.</para>
      </listitem>

      <listitem>
        <para>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.</para>
      </listitem>
    </itemizedlist>

    <para>Locations:</para>

    <para><itemizedlist>
        <listitem>
          <para>$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.</para>

          <note>
            <para>Defining the environment variable FR_HOME will override this
            path.</para>
          </note>

          <note>
            <para>Passing -h &lt;path&gt; on FlameRobin's command line will
            override this path and the environment variable as well.</para>
          </note>
        </listitem>

        <listitem>
          <para>$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.</para>

          <note>
            <para>Defining the environment variable FR_USER_HOME will override
            this path.</para>
          </note>

          <note>
            <para>Passing -uh &lt;path&gt; on FlameRobin's command line will
            override this path and the environment variable as well.</para>
          </note>
        </listitem>
      </itemizedlist>Additionally, the &lt;path&gt; 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).</para>

    <para>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.</para>
  </section>

  <section>
    <title>Advanced topics</title>

    <para>This section will document some advanced topics about how FlameRobin
    works. The topics are not necessarily related, and are grouped here only
    for convenience.</para>

    <section>
      <title>Encrypted password storage</title>

      <para>FlameRobin can use strong encryption to safely store your
      passwords in the configuration file (fr_databases.conf). Here's how it
      works in detail:</para>

      <itemizedlist>
        <listitem>
          <para>all passwords (PW) are encrypted with a master password
          (MPW)</para>
        </listitem>

        <listitem>
          <para>the MPW alone is never saved into any file, it is only known
          by the user</para>
        </listitem>

        <listitem>
          <para>PW + MPW comprise the Cipher (which is stored in the .conf
          file)</para>
        </listitem>

        <listitem>
          <para>whenever a PW needs to be decrypted, the user is prompted for
          the MPW</para>
        </listitem>

        <listitem>
          <para>Cipher + MPW yield the PW</para>
        </listitem>
      </itemizedlist>

      <section>
        <title>Defense from "known plain-text" attack</title>

        <para>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:</para>

        <itemizedlist>
          <listitem>
            <para>the string composed by MPW + username + database connection
            string is used as a seed for some irreversible random number
            generator (RNG) like ISAAC</para>
          </listitem>

          <listitem>
            <para>the PW is encrypted with the numbers produced by the
            RNG</para>
          </listitem>

          <listitem>
            <para>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</para>
          </listitem>
        </itemizedlist>

        <para>For more information on ISAAC see:
        http://en.wikipedia.org/wiki/ISAAC
        http://www.burtleburtle.net/bob/rand/isaacafa.html</para>

        <para></para>
      </section>
    </section>
  </section>
</article>