READ THIS FIRST!

Important: Firebird 2.0.x and 2.1.x support the full range of Windows server platforms from Windows 2000 onward. Over the past decade, some platform rules have become progressively complicated. What worked on W2K might not work on later Windows platforms. It is strongly recommended that you study this section before you begin, even if you have been cheerfully running v.1.5 for years!

And note, although you might get Firebird 2.x to install and run on Windows 95, 98 or ME, they are no longer supported platforms for Firebird servers.

Make sure you are logged in as Administrator.
Check to make sure that there is no FIREBIRD environment variable defined that is visible to Administrator-level users or to the LocalSystem user - see the section called The FIREBIRD variable at the start of the first chapter.
If you already have an earlier version of Firebird or InterBase^® on your server and you think you might want to go back to it, set up your fall-back position before you begin:
- Use the existing version of gbak to back up your database files in transportable format. Do this before you uninstall the old version.
- If migrating from a Firebird version earlier than version 2.0 you should use gbak to back up your old security database. It is named security.fdb for Firebird 1.5 or isc4.gdb for a Firebird 1.0 installation. You can restore it later as security2.fdb, using the directions in the chapter entitled Security in the Firebird 2.0.x Release Notes.
- Go to your System directory and make backup copies of fbclient.dll and/or gds32.dll if you have applications that rely on finding those libraries there. You might want to name the backup gds32.dll.fb15 or gds32.dll.fb103 or something similarly informative; or hide it in another directory.
- Heed all the warnings and notes about incompatibilities and changes required. Don't start experimenting with new features on your active production databases!
STOP ANY FIREBIRD OR INTERBASE^® SERVER THAT IS RUNNING.

At install time, the installer will try to detect if an existing version of Firebird or InterBase^® is installed and/or running. However this detection is not foolproof. For a non-installer install, you are on your own!

Important: A new installation of Firebird will not work correctly if an old version is still running. The uninstaller will usually stop an existing server as part of the uninstallation process, so you probably need not worry about this if you run an uninstall. However, if you do have problems later this is something to go back and check.

Before installing Firebird 2.1 it is recommended that you uninstall a previous version of Firebird or InterBase^®, if it exists on your system. If you have special settings in your existing firebird.conf (ibconfig, for Firebird 1.0) there may be some values that you want to transfer to equivalent parameters in the new firebird.conf. The uninstaller for all versions of Firebird will preserve certain configuration files. See below for more details.

Note: If you are upgrading from Firebird 1.0.x or InterBase^®, you should review the release notes for Firebird 1.5.x. There you will find details of the correlation between settings in ibconfig and firebird.conf. Study the notes about firebird.conf to work out what can be copied directly and what parameters require new syntax.

If this document is not in the documentation directory after installation, you can read or download it from the Release Notes section of the Firebird Documentation Index.

When reinstalling Firebird 2.1, certain configuration files in the installation directory will be preserved if you run the installer. These files are:

aliases.conf
firebird.conf
firebird.log
security2.fdb

The default aliases.conf is just a place holder file, so if it already exists it will be left as it is. If it doesn't exist it will be generated.
If firebird.conf exists the installer will generate a firebird.conf.default file with the default values and leave the existing file untouched.

Important: Each release (v.2.0. v.2.1, v.2.5, etc.) adds new parameters to firebird.conf and, potentially, might change how an older parameter works. Certain parameters are included from time to time, to enable legacy applications to continue "working around" legacy bugs for a limited time. Such parameters are removed eventually. Ensure that you read the relevant chapter in each release notes volume and, if necessary, use a difference tool to merge existing settings into the new firebird.conf.

The firebird.log file is generated automatically by the server when required. An empty log file is not created at installation time.
If the security2.fdb database exists it will be used. If it doesn't exist an empty, default database will be installed.

It is assumed that:
1. you understand how your network works,
2. you understand why a client/server system needs both a server and clients,
3. you have read the accompanying Release Notes — or at least realise that you need to read them if something seems to have gone wrong,
4. you know to go to the Firebird lists index to find a suitable support list if you encounter a problem.
Provided you do not have a FIREBIRD environment variable defined, the default root location of Firebird 2.1 will be C:\Program Files\Firebird\Firebird_2_1. For Firebird 2.0 it will be C:\ProgramFiles\Firebird\Firebird_2_0.

Naming databases on Windows

Note that the recommended extension for database files on Windows ME and XP is .fdb to avoid possible conflicts with System Restore feature of these Windows versions. Failure to address this issue on these platforms will give rise to the known problem of delay on first connection to a database whose primary file and/or secondary files are named using the .gdb extension that used to be the Borland convention for suffixing InterBase^® database file names.

The issue is described in more detail in Other Win32 issues at the end of the Windows installation notes.

Microsoft C/C++ runtime libraries

The problems associated with installing different versions of Microsoft system libraries are so notorious that it has acquired the name "DLL Hell". And as each new generation of Microsoft operating systems is released the policy for dealing with this issue changes. Sometime this can lead to even more hell.

The main source of problems is that, each time a new release appears, people have a habit of overlooking the fact that Windows servers and clients always need the MS runtimes. No Firebird server (be it Superserver, Classic, Superclassic or Embedded) nor client (fbclient.dll) will work without access to both the C and the C++ runtime libraries pertaining to the built version of the binary.

In reality, almost every application installed on Windows needs at least the C runtime and many need also the C++ runtime. The runtimes were almost always present in the system directory of established host servers and it was relatively rare during the heyday of WinXP and Server2003 for an installation of an older Firebird version not to run "straight out of the box".

What happens if the runtimes are missing?

Both Firebird servers and Firebird clients depend on calls to the C/C++ runtimes. If the appropriate runtime is missing, Windows cannot load the binary. Most of the errors you will see in the logs (firebird and system) will be operating system ones, rather than exceptions that the Firebird binaries themselves could have detected or handled. Some data access layers that load the Firebird client library dynamically might transform failure to load the binary into feedback such as Cannot connect to database, wrongly implying that there is something wrong with the database.

However, genuine Firebird exceptions due to "losing" the runtimes can still occur, even if they were found for loading the client library, because the INTL library needs them, too. A User name or password is not defined or Character set X is not defined error during the connection start-up usually means the server could not load the INTL library. It is most likely to happen during the attachment to the security database, since that precedes anything else.

Runtimes for Firebird 2.1.x

As Microsoft Vista approached, successive service packs for WinXP/Server2003, and possibly also Win2000, showed signs of tightened rules for installing DLLs. The new rules were synchronised with the design-time assemblies of the Microsoft Visual Studio 8 C++ compiler, which is used for compiling the Firebird 2.1 series. The corresponding distributable runtimes are msvcr80.dll and msvcp80.dll.

Now, with certain platform exceptions, it is necessary to install the runtimes correctly as an assembly. The minimal runtime consists of three files: msvcr80.dll, msvcp80.dll and the manifest (Microsoft.VC80.CRT.manifest).

Until v.2.1.1, the preferred way to do this was to install the vcredist_32 or vcredist_64 Microsoft installer (.msi) package, as appropriate for the architecture of your host server, from the Microsoft support site. For Windows 2000 and for WinXP and Server2003 prior to Service Pack 1, you need(ed) to download and install the .msi Installer software and then install the MSVC8 redistributable pack.

ATTENTION! Firebird binaries are built against the original version of Visual C++. Because of this, the required runtimes are those distributed in the vcredist_32/64 pack, not those that might have been latterly installed as part of a service pack.

The result of installing the MSVC8 redistributable is that a shared assembly is installed on WinXP, Server2003 or MS Vista. For Windows 2000, it simply writes the two DLLs to the system directory and registers them.

Tip for Windows 2000: It has been assumed that simply copying the DLLs to the system directory is all that is needed. However, on a Win2K system with SP4 and all subsequent updates, it has been reported that an operating system directive exception occurred and investigation of the system log indicated that registering the DLLs was required, using the regsvr32.exe utility. It fixed the problem.

It is suggested that you explore this route only if you encounter the operating system directive exception problem on Windows 2000 and see that advice when you follow it up in the system log.

Private assembly

Installing the runtime assembly from the Microsoft redistributable is the easiest and thus the preferred way to get them on board. However, from Firebird 2.1.2 onward, it becomes possible to isolate the runtimes for your Firebird server or client installation in a private assembly. The server engine and the client, as well as the DLLs in Firebird's \intl folder, have been taught to search for the private assembly — the two runtime DLLs and the manifest file Microsoft.VC80.CRT.manifest — in the same folder as the engine executable or client DLL.

For a detailed discussion of this change, refer to the special topic by Vlad Khorsun, Managing MSVC8 Runtime Assemblies near the end of this chapter.

Runtimes for Firebird 2.0.x

For the Firebird 2.0.x series, which has been in release and maintenance since November 2006, the Microsoft C and C++ runtimes are msvcr71.dll and msvcp71.dll, respectively. Unfortunately, some of the earlier documentation applicable to Firebird 2.0 erroneously cited the names of the older runtimes used by Firebird 1.5, (msvcrt.dll and the C++ runtime msvcp60.dll). Firebird 2.0.x will not work if those (or lower) runtimes are the only ones available.

The deployment rules for the ..71.dll runtimes are similar to those for older versions (for both the runtimes and the Firebird components): it is enough to copy them to the Windows system directory on Win2000, WinXP and Server2003 servers and clients. Microsoft Vista is not so tolerant about post-installing DLLs in its system directory but it appears that copying msvcr71.dll and msvcp71.dll there does work, at least at the Windows service patch levels current in the first quarter 2009.

The Firebird installer executable for v.2.0.x actually attempts to install the runtimes on any Windows platform, including Vista. However, on Vista and, possibly, on 64-bit versions of WinXP or Server2003 with the later service packs, it is advisable to check after a reboot whether those runtimes are actually there. If not, you can copy them from the \bin folder of the Firebird installation.

Other pre-installation issues

Microsoft installer version

The binary installer will determine the host operating system and try to install system libraries appropriately for that O/S. In most cases there will be no problems. As already alluded to above, early versions of WinXP and Windows 2003 that have not used Windows Update will not have the correct version of the Windows Installer required to install the side-by-side assemblies of the run-time libraries.

The only recommended solution is to run Windows Update to bring your XP or Server2003 installation up to the level of Service Pack 2 or higher. This should ensure that you have the appropriate installer available before executing the installer for your selected Firebird kit or for installing the assembly yourself when installing Firebird from a zip kit.

Tip: If you haven't studied the previous section and are confused, then do so now.

Checking the Windows Installer version

To check the version of the Windows installer installed on your WinXP or later host, run msiexec.exe from a console prompt. A help screen will be displayed that shows the version. If it is earlier than v.3.0 you must update.

Older Windows platforms

If the host O/S is pre-WinXP runtime libraries (msvcp80.dll and msvcr80.dll and the MSVC80 manifest for v.2.1.x, or msvcp71.dll and msvcr71.dll for v.2.0.x) can be copied directly from the Firebird \bin\ directory into the Windows or WINNT \system32\ directory.

Installing under 64-bit versions of Windows

The 64-bit binary installer includes a 32-bit client kit so that everything will work 'out of the box'. On the other hand, the zip kits are platform specific, so don't forget to install the 32-bit MS C runtime msi, along with the 32-bit client library if you need to use 32-bit applications on the server.

Simultaneous installation of 32-bit and 64-bit versions of Firebird is possible, but at least one must be installed and configured manually. Note that under these circumstances the FIREBIRD environment variable must NOT be defined at the system level AT ALL.

Installation of `fbclient.dll` on the server

Since Firebird 1.5, gds32.dll is not the "native" name of the client library. It is now called fbclient.dll. Considering the problems that Microsoft has had with DLL hell, it would make little sense if we continued to store the Firebird client library in the system directory by default.

Furthermore, as we want to allow multiple engines to run simultaneously we would be creating our own DLL hell if we continued to encourage the practice of using the system directory for the client library.

So, from Firebird 1.5 on, the client library for local use on the server has resided in the \bin directory along with all the other binaries. For those whose local server applications still need to find the client library in the system directory, the installer provides the option (unchecked) to copy the client to the system directory and also to rename it to gds32.dll, if need be.

Note: You don't need to commit yourself one way or the other during the initial installation. Your Windows kits come with tools that can be used to customise such things later. Please refer to the Customising your installation section at the end of this chapter.

Registry key

A registry key is added and all Firebird 2.1-compliant applications should use this key if they need to read a registry key to locate the correct version of Firebird that they wish to use. The new key is:

 HKEY_LOCAL_MACHINE\SOFTWARE\Firebird Project\Firebird Server\Instances

Firebird will guarantee that one entry under this key always exists. It will be known as

 "DefaultInstance"

and will store the path to the root directory of the default installation. Those who don't care about particular installations can always use the default instance to locate the fbclient.dll.

Future versions of Firebird may see other entries under Instances when the installation utilities can be taught to isolate and configure instances reliably. Applications would then be able to enumerate the registry entries to determine which server instance they wish to load.

Cleaning up release candidate installs

It should be noted that the installer removes fbclient.dll from the <system> directory if the file is found there. The installer also removes any deprecated HKLM\Software\Firebird* registry keys.