08 Migrating the database configuration

GTR programs read their database connection from an INI file. ProfDia uses NCPro_db.ini, NestCut uses Nestcut_db.ini. After the migration of the database to Firebird 5, the database section in this file still points to Firebird 2.5. The GTR DB Config tab changes this section to Firebird 5.

The INI files are stored locally. If the database is on a server, first migrate it on the server. Then run the steps of this chapter on every client that has a GTR program.

Supported files

The tab accepts every INI file with this structure:

• a section [DatabaseGeneral]. Its key Database= names the section the program uses.
• at least one section whose name starts with FIREBIRD, for example [FIREBIRD]

Other sections, for example [ADO] or [ColumnWidth], stay unchanged.

The tool refuses any other file with <file> is not a supported database INI file. followed by the reason:

• The section [DatabaseGeneral] is missing.
• The file has no [FIREBIRD] section.

Before you start

1. Migrate the database with the Operations tab. See How the operations work.
2. Close the program that uses the INI file, for example ProfDia or NestCut, on this computer.
3. If the INI file lies in a write-protected folder, for example below C:\Program Files, start Firebird Management as administrator.

Step 1: Load the file

In the box Database configuration file:

1. Click Browse… and select the INI file. The dialog lists files named *_db.ini first. Select INI files to see every .ini file. The tool loads the file right away.
2. Or type the path into the field INI file: and click Load.

The Log Output panel shows the number of database sections and the active section, for example Loaded C:\ProfDia\NCPro_db.ini: 4 FIREBIRD sections, active: FIREBIRD.

The tool reads the file in the Windows ANSI code page, the format the GTR programs write. It refuses a file in UTF-8 with a byte order mark: <file> is UTF-8 with BOM; GTR programs expect an ANSI file.

Step 2: Select the section

The box Database sections lists every section whose name starts with FIREBIRD. The columns are Section, DriverIdent, Server, Database and Status.

The Status column contains:

Status	Meaning
active	The program uses this section. [DatabaseGeneral] names it in Database=.
no DriverIdent	The section has no DriverIdent value.
already Firebird 5	The section has DriverIdent=firebird-5.0.

The tool selects the active section when it loads the file. Load on the same file keeps the selected section. Click another row to select a different section.

If you edited new values and then select another section or load a file, the dialog Unsaved changes asks Discard your changes to <section>?. Click No to keep your edits.

Sections that an earlier save created as backups are hidden. Tick Show backup sections to list them.

Step 3: Check the new values

The box New values shows one row per key. The column Current value shows the value in the file. The column New value holds the value that Save writes. You can edit every new value.

Key	New value
DriverIdent	firebird-5.0
DriverPath	The Firebird 5 client library for the selected Driver, see below
Username	unchanged
Password	FB50_PASSWD from .env, or FB_PASSWD if FB50_PASSWD is not set
Server	unchanged
Database	unchanged
Port	FB50_PORT from .env, 3055 if it is not set

The column Current value shows a password as ********. The field for the new password hides its characters. Hold down the left mouse button on Show next to the field to see the new password in clear text. The field hides it again when you release the button or move the mouse pointer off it.

For a section that already has DriverIdent=firebird-5.0, the tool shows the values of the file as new values. It fills in only empty keys.

Password and Port come from the Firebird 5 installation on this computer. Server keeps the value of the file. For a Firebird 5 server on another computer, enter the password and the port of that server.

Driver

The program loads the Firebird client library from DriverPath. The library must have the same bitness as the program. ProfDia and NestCut are 32-bit programs. The Driver row offers two choices:

Choice	DriverPath
x86 (32-bit program)	C:\ProgramData\GTR mbH\drivers\firebird50\bin\fbclient.dll, the 32-bit client from the GTR Firebird setup
x64 (64-bit program)	FB50_CLIENT from .env

The tool presets the choice from the library in the current DriverPath. If the bitness is unknown, it selects x86 and shows one of these hints:

• Bitness of the current driver unknown (file not found or not a DLL); x86 suggested because ProfDia and NestCut are 32-bit programs. A relative DriverPath, for example .\drivers\firebird25\fbclient25.dll in Nestcut_db.ini, also leads to this hint. The path is relative to the program folder, which the tool does not know.
• Bitness of the current driver not checked (network path); x86 suggested because ProfDia and NestCut are 32-bit programs. The tool does not read a driver on a network path, because an unreachable server would block the window.

A change of the choice replaces DriverPath, unless you edited the field yourself. The new DriverPath is an absolute path.

Database on this computer or on another server

The tool checks whether Server names this computer. localhost, 127.0.0.1, ::1, the computer name, its full domain name and its IP addresses count as this computer.

Server on this computer: the field Database keeps the value of the file and cannot be edited. A migration on this computer keeps the database file under its name, so the path stays valid.

Server on another computer: the field Database can be edited. Enter the path of the migrated database as the Firebird 5 server sees it. Then tick The database at this path is already migrated to Firebird 5. Save stays disabled until you tick it. A change of Server between this computer and another computer clears the tick.

Step 4: Save

1. Click Save. Every key except Password needs a value. Otherwise the tool shows Enter a value for <keys>.
2. The Save dialog names the section and the file. Click Yes.

The tool then:

1. copies the file to <file name>.<yyyymmdd_hhmmss>.bak in the same folder, for example NCPro_db.ini.20261012_153000.bak
2. inserts a copy of the old section as [<SECTION>_FB25_<yyyymmdd_hhmmss>] directly after the section, for example [FIREBIRD_FB25_20261012_153000]
3. writes the new values into the section. A key that does not exist is added at the end of the section.

All other lines of the file stay unchanged, including comments and the line endings. [DatabaseGeneral] keeps its value, so the program uses the changed section.

The log shows the backup file and the name of the backup section. To return to Firebird 2.5, replace the INI file with the .bak file.

Save errors

Message	Cause and solution
Cannot write <file>. Start Firebird Management as administrator and try again.	The file or its folder is write-protected. The file stays unchanged.
Writing <file> failed: <reason>. The file may be incomplete.	Writing stopped after the file was opened. The message names the .bak file with the previous content. Copy it back over the INI file.
The value for <Key> contains a character that <file name> cannot store (code page <cp>).	A new value contains a character outside the ANSI code page. Replace the character. The file stays unchanged.
Section <name> no longer exists in <file>. Load the file again.	Another program changed the file after it was loaded. Click Load and repeat the steps.
<file> no longer exists. Load the file again.	The file was deleted or moved after it was loaded. Check the path and click Load.

Step 5: Test the connection

Test connection is available for a section with DriverIdent=firebird-5.0, so after Save. The hint beside the button says Test connection is available after saving the migrated section. The test runs two checks with the values in the box New values:

1. Connection: the tool connects to Server, Port and Database with Username and Password. It reads the Firebird version and the ODS of the database. Example: Connection: OK, Firebird 5.0.4, ODS 13.1.
2. Driver: the tool checks that the file in DriverPath exists and matches the selected Driver. Example: Driver: C:\ProgramData\GTR mbH\drivers\firebird50\bin\fbclient.dll is x86 as selected.

The tool connects with its own Firebird client library, not with the library in DriverPath. On 64-bit Windows the tool is a 64-bit program and cannot load a 32-bit library. For the 32-bit driver it checks the file type only. Start the program to test the 32-bit driver itself.

The ODS is the format version of the database file. Firebird 5 creates databases with ODS 13.1. Firebird 2.5 databases have ODS 11.2.

The result appears in the Connection test dialog and in the log. Troubleshooting explains the error messages.