From 159faf60cae0f0688b2b5b045a31bc6e713cb28d Mon Sep 17 00:00:00 2001 From: cvs2git Date: Sat, 16 Jul 2011 01:58:10 +0000 Subject: [PATCH 01/33] This commit was manufactured by cvs2git to create branch 'B_Release'. Sprout from master 2011-07-16 01:58:09 UTC Paul Vinkenoog 'Improved lib and tools readmes.' Cherrypick from master 2010-12-09 02:39:57 UTC Paul Vinkenoog 'Changed doc date to 9 Dec; changed description of LIST() bug.': src/docs/refdocs/langref/langrefupd21.xml --- src/docs/refdocs/langref/langrefupd21.xml | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/src/docs/refdocs/langref/langrefupd21.xml b/src/docs/refdocs/langref/langrefupd21.xml index 2852d7c6..39fed284 100644 --- a/src/docs/refdocs/langref/langrefupd21.xml +++ b/src/docs/refdocs/langref/langrefupd21.xml @@ -12,7 +12,7 @@ Paul Vinkenoog et al. - ?? X....... 201?, document version 1.1 — covers Firebird 2.1–2.1.4 + 9 December 2010, document version 1.0 — covers Firebird 2.1–2.1.4 Introduction @@ -1091,7 +1091,7 @@ RDB$COLLATION_ATTRIBUTES = 4--> Comment - + DISABLE-COMPRESSIONS 0, 1 @@ -14102,14 +14102,6 @@ DECLARE EXTERNAL FUNCTION lpadbig License Notice: Added Frank Ingermann and Vlad Khorsun as contributors. (C) end year now 2010. - - 1.1 - ?? Xxx 201? - PV - - DDL statements :: COLLATION :: CREATE COLLATION: Gave Specific collation attributes table body valign=top. - - From a14badd3a3c4488f2133d28982a845114f08e3fa Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Sun, 24 Jul 2011 15:31:51 +0000 Subject: [PATCH 02/33] Merged changes from trunk; doc version 1.3 --- src/docs/firebirddocs/migrationmssql.xml | 1368 ++++++++-------------- 1 file changed, 466 insertions(+), 902 deletions(-) diff --git a/src/docs/firebirddocs/migrationmssql.xml b/src/docs/firebirddocs/migrationmssql.xml index 9c923d3a..e446315a 100644 --- a/src/docs/firebirddocs/migrationmssql.xml +++ b/src/docs/firebirddocs/migrationmssql.xml @@ -1,673 +1,436 @@ - +
Migration from MS-SQL to Firebird - Marcelo - Lopez Ruiz - - 14 September 2010 - Document version 1.2 + 24 July 2011 - Document version 1.3 - - Microsoft SQL Server (MS SQL) is a widely - used database server. There are many versions which currently account for - the majority of the user base and we mention MS SQL 2000 , MS SQL 2003 and MS SQL 2008. - Introduction - - This section describes the conversion guide itself. - - The conversion from MS SQL server documentation is meant, first, to - help users evaluate whether the process should be performed at all. It - then goes on to detail how this can be done, adding bits of experience + Microsoft SQL Server (MS SQL) is a widely used database server. + For an overview of its history and versions, see http://en.wikipedia.org/wiki/Microsoft_SQL_Server#History. + This conversion guide is meant, first, to help users evaluate whether the process should + be performed at all. It then goes on to detail how this can be done, adding bits of experience collected by different people. - - There are two important things to take into account when migrating. - First, moving the data from one database server to another can be trivial - or not, depending on your database schema. There are many tools to help - you with this process. The standard data conversions are listed in this - document. - - Second, you will need to migrate any stored procedures and triggers - manually. This is the tricky part. There are many differences, some minor, - some important; this document attempts to address most of them, giving - examples on the most frequent problems and how to solve them. - + There are two important things to take into account when migrating. First, moving the data + from one database server to another can be trivial or not, depending on your database schema. + There are many tools to help you with this process. The standard data conversions are listed in + this document. + Second, you will need to migrate any stored procedures and triggers manually. This is the + tricky part. There are many differences, some minor, some important; this document attempts to + address most of them, giving examples on the most frequent problems and how to solve + them. - This guide was written in 2003, when Firebird 1.0 was the current - version. Although it has been updated in a few places, the document as a - whole still awaits a thorough revision. That shouldn't stop you from - using it - just be aware that some of the content is outdated, and do - read the Release Notes of any Firebird versions greater than 1.0 up to - and including your own version. + This guide was written in 2003, when Firebird 1.0 was the current version. Although it + has been updated in a few places, the document as a whole still awaits a thorough revision. + That shouldn't stop you from using it - just be aware that some of the content is outdated, + and do read the Release Notes of any Firebird versions greater than 1.0 up to and including + your own version. - Pros and Cons - This section describes reasons to migrate an existing database to Firebird, and reasons not to. - Why migrate to <application>Firebird</application> - - This depends mostly on what version you are currently using and - what you are using MS SQL for. - - For example, if using MS SQL 6.5, it is a simple matter of - considering the features and ease of use. MS SQL 6.5 will work with - fixed devices rather than dynamically expanding files, which makes it - very difficult to balance ease of administration vrs. available space. - There are numerous bugs and annoying behaviours which - - If you are using MS SQL 7, you know a lot of the little quirks - have been removed, but you are still missing some great features, such - as updateable views, greater control over identity fields, user-defined - functions, and selectable stored procedures. You also don't get - cascading referential integrity until the 2000 version. Ditto for using - different collation orders in the same database. - - For UNIX-like environment, Firebird can have its security - integrated with the operating system's. However, this should be - discouraged for portability. - - MS SQL 2000 improved on MS SQL 7, but is still missing one of the - key pieces of Firebird: the multi-generational architecture, which - enabled long-running queries to work without getting in the way of - traditional short-lived operational transactions. MS SQL will instead - try to convince users to buy yet another server (hardware, operating - system and database server), set it up as a data warehouse, and use this - second server as a source for reports. One can only wonder about the - need for a data warehouse in an integrated environment with - cross-database query capabilities. - - Another reason to migrate is to avoid vendor lock-in. MS SQL will - only run on Windows NT/2000 (there are so-called personal editions, but - these are limited in available connections and features). This means you - are tied to Microsoft for your operating system and your database - server. Firebird will run on many platforms, - including Microsoft Windows, Linux, Solaris, MacOS X, and others. - - Yet another reason to consider is price. Firebird is free; MS SQL - will require a considerable amount of money on a per-processor basis. - For example, a database accessed through the Internet on a dual cpu - Intel Xeon/Opteron - machine will cost $54,990 (prices obtained from Microsoft's - site on 14 Sep 2010). - - Last, but certainly not least, is the fact that Firebird is open - source. This not only means that there are hundreds of developers - willing to help you use it, improve on it, find bugs, etc., but that you - can even modify it and rebuild it yourself to "scratch your itches". - Adding features such as an integrated e-mail system or logging is a - matter of understanding the source code and having the available - expertise to modify it. While this may not be a trivial task, it is - certainly doable, and brings an enormous degree of flexibility. + This depends mostly on what version you are currently using and what you are using MS + SQL for. + For example, if using MS SQL 6.5, it is a simple matter of considering the features and + ease of use. MS SQL 6.5 will work with fixed devices rather than dynamically expanding files, + which makes it very difficult to balance ease of administration vrs. available space. There + are numerous bugs and annoying behaviours which + If you are using MS SQL 7, you know a lot of the little quirks have been removed, but + you are still missing some great features, such as updateable views, greater control over + identity fields, user-defined functions, and selectable stored procedures. You also don't get + cascading referential integrity until the 2000 version. Ditto for using different collation + orders in the same database. + For UNIX-like environment, Firebird can have its security integrated with the operating + system's. However, this should be discouraged for portability. + MS SQL 2000 improved on MS SQL 7, but is still missing one of the key pieces of + Firebird: the multi-generational architecture, which enabled long-running queries to work + without getting in the way of traditional short-lived operational transactions. MS SQL will + instead try to convince users to buy yet another server (hardware, operating system and + database server), set it up as a data warehouse, and use this second server as a source for + reports. One can only wonder about the need for a data warehouse in an integrated environment + with cross-database query capabilities. + Another reason to migrate is to avoid vendor lock-in. MS SQL will only run on Windows + NT/2000 (there are so-called personal editions, but these are limited in available connections + and features). This means you are tied to Microsoft for your operating system and your + database server. Firebird will run on many platforms, including + Microsoft Windows, Linux, Solaris, MacOS X, and others. + Yet another reason to consider is price. Firebird is free; MS SQL will require a + considerable amount of money on a per-processor basis. For example, a database accessed + through the Internet on a dual cpu - Intel Xeon/Opteron machine will cost $54,990 (prices + obtained from + Microsoft's site on 14 Sep 2010). + Last, but certainly not least, is the fact that Firebird is open source. This not only + means that there are hundreds of developers willing to help you use it, improve on it, find + bugs, etc., but that you can even modify it and rebuild it yourself to "scratch your itches". + Adding features such as an integrated e-mail system or logging is a matter of understanding + the source code and having the available expertise to modify it. While this may not be a + trivial task, it is certainly doable, and brings an enormous degree of flexibility. - Why not migrate to Firebird - - The first, overriding reason should be because your system is - working fine as it is. If this is the case, consider Firebird for future - projects, but do not break what is currently working. - - There are a number of features MS SQL 7 has that you will not find - in Firebird, such as integrated replication - support (this is available as an add-on to - Firebird), temporary tables, and integration - with other database systems through OLE DB. It also has an OLAP Analysis - services built into it, and native full-text search (this is available - as an add-on to Firebird). - - On Microsoft environments, MS SQL 7 and above can have its - security integrated with the operating system's. However, this should be - discouraged for portability and performance issues. - - MS SQL 2000 also has the ability to work with XML directly, and - supports partitioned views for better performance on tables which span - several servers. - - In general, it would seem that MS SQL has better performance on - Windows than Firebird on Windows does. It - also has better integration with Microsoft Visual - Studio. + The first, overriding reason should be because your system is working fine as it is. If + this is the case, consider Firebird for future projects, but do not break what is currently + working. + There are a number of features MS SQL 7 has that you will not find in + Firebird, such as integrated replication support (this is available + as an add-on to Firebird), temporary tables, and integration with + other database systems through OLE DB. It also has an OLAP Analysis services built into it, + and native full-text search (this is available as an add-on to + Firebird). + On Microsoft environments, MS SQL 7 and above can have its security integrated with the + operating system's. However, this should be discouraged for portability and performance + issues. + MS SQL 2000 also has the ability to work with XML directly, and supports partitioned + views for better performance on tables which span several servers. + In general, it would seem that MS SQL has better performance on Windows than + Firebird on Windows does. It also has better integration with + Microsoft Visual Studio. - Database Server Setup - - This section describes differences when installing the database - server software. - - For users who have used MS SQL in the past and are new to Firebird, - they will be greatly surprised when they learn how easy it is to set up - Firebird. The setup process is straightforward, - and you can connect to your database server immediately after setup. Note - that the default system administration username is SYSDBA and the password - is masterkey; in MS SQL, the username is sa and the password is - empty. - - Note that you don't have to select the collation and character sets - when installing a Firebird server. In MS SQL, - you not only have to select this option up front, but must reinstall to - change it; in addition to this, many other software packages, such as - Microsoft's own Commerce Server, will refuse to use the server if you - select the wrong choices. - - For users coming from MS SQL 6.5, Firebird has no notion of devices. - All data are kept in files in the normal file system available. Note that - you cannot use a raw disk partition to hold your databases. - - Important Note: MS SQL uses a logging mechanism - to keep database consistent and survive crashes. - Firebird uses a multi-generation mechanism to - create copies in-place as they are required, but these are not written - immediately to disk. While this provides a considerable speed gain, you - can turn Forced Writes on a per-database basis to ensure that sudden - blackouts will not compromise data integrity. If your server has a - reliable environment such as a dedicated Linux box, and some form of UPS, - turning Forced Writes on can be ignored. + This section describes differences when installing the database server software. + For users who have used MS SQL in the past and are new to Firebird, they will be greatly + surprised when they learn how easy it is to set up Firebird. The + setup process is straightforward, and you can connect to your database server immediately after + setup. Note that the default system administration username is SYSDBA and the password is + masterkey; in MS SQL, the username is sa and the password is empty. + Note that you don't have to select the collation and character sets when installing a + Firebird server. In MS SQL, you not only have to select this option + up front, but must reinstall to change it; in addition to this, many other software packages, + such as Microsoft's own Commerce Server, will refuse to use the server if you select the wrong + choices. + For users coming from MS SQL 6.5, Firebird has no notion of devices. All data are kept in + files in the normal file system available. Note that you cannot use a raw disk partition to hold + your databases. + Important Note: MS SQL uses a logging mechanism to keep database + consistent and survive crashes. Firebird uses a multi-generation + mechanism to create copies in-place as they are required, but these are not written immediately + to disk. While this provides a considerable speed gain, you can turn Forced Writes on a + per-database basis to ensure that sudden blackouts will not compromise data integrity. If your + server has a reliable environment such as a dedicated Linux box, and some form of UPS, turning + Forced Writes on can be ignored. - Database Administration - This section describes differences in how database are managed in Firebird and MS SQL. - Database Files Administration - - MS SQL 6.5 uses devices, which can be files or raw partitions, to - manage data. This resulted in a hard-to-maintain system. MS SQL 7 and MS - SQL 2000 corrected this by using normal files in place of devices. For - each database, you will have at least two files: one with the database - information itself, and one with a log of transactions performed. - - Firebird does not rely on a log to keep track of transactions, and - therefore uses a single file to keep everything. - - The CREATE DATABASE statement in Firebird is simpler than the - CREATE DATABASE statement in MS SQL; see the SQL reference for a full - description of its capabilities. - - One significant difference between the file management model is - that MS SQL uses filegroups to partition a database over a set of files. - Firebird can also use different files, but the model is simpler. - - An additional consideration for Firebird is the use of shadow - files. Shadow files are an instant replica of the database itself. It is - typically used to have a hot backup readily available. MS SQL has no - such feature, although MS SQL 2000 has a similar capability by the use - of log shipping between database servers and replication. + MS SQL 6.5 uses devices, which can be files or raw partitions, to manage data. This + resulted in a hard-to-maintain system. MS SQL 7 and MS SQL 2000 corrected this by using normal + files in place of devices. For each database, you will have at least two files: one with the + database information itself, and one with a log of transactions performed. + Firebird does not rely on a log to keep track of transactions, and therefore uses a + single file to keep everything. + The CREATE DATABASE statement in Firebird is simpler than the CREATE DATABASE statement + in MS SQL; see the SQL reference for a full description of its capabilities. + One significant difference between the file management model is that MS SQL uses + filegroups to partition a database over a set of files. Firebird can also use different files, + but the model is simpler. + An additional consideration for Firebird is the use of shadow files. Shadow files are an + instant replica of the database itself. It is typically used to have a hot backup readily + available. MS SQL has no such feature, although MS SQL 2000 has a similar capability by the + use of log shipping between database servers and replication. - User Administration - - In MS SQL 6.5, there are two objects to manage: logins and users. - Logins specify a username/password combination used to access a database - server; users specify the access rights on each database. Logins are - then mapped to users in databases. - - In MS SQL 7, a new kind of object is added to manage groups of - users: roles. These simply security definition. Some roles are - system-defined, such as backup operators or database - administrators. - - Firebird has a security model similar to MS SQL's, but without - logins. Users supply a username, a password, and a role they wish to - work under. There is a single security database per database server, - which holds all information about permissions on every database, for + In MS SQL 6.5, there are two objects to manage: logins and users. Logins specify a + username/password combination used to access a database server; users specify the access + rights on each database. Logins are then mapped to users in databases. + In MS SQL 7, a new kind of object is added to manage groups of users: roles. These + simply security definition. Some roles are system-defined, such as backup operators or + database administrators. + Firebird has a security model similar to MS SQL's, but without logins. Users supply a + username, a password, and a role they wish to work under. There is a single security database + per database server, which holds all information about permissions on every database, for every user, for every role. - - Under both database systems, it is considered good practice to - access all resources through stored procedures, and grant access only to - stored procedures. Security can then be setup through the security - assigned to stored procedures (in Firebird; in MS SQL, the stored + Under both database systems, it is considered good practice to access all resources + through stored procedures, and grant access only to stored procedures. Security can then be + setup through the security assigned to stored procedures (in Firebird; in MS SQL, the stored procedure executes using the rights of its creator). - Backup and Restore Operations - - Firebird uses a backup and restore model which is much simpler - than MS SQL, although it sacrifices flexibility. Backups are performed - through command-line or GUI tools, and they backup a whole database at a - time. A restore operation will restore a whole database on a + Firebird uses a backup and restore model which is much simpler than MS SQL, although it + sacrifices flexibility. Backups are performed through command-line or GUI tools, and they + backup a whole database at a time. A restore operation will restore a whole database on a server. - - There is no operation to backup differences only, or to restore an - isolated set of transactions. - - Note that there is a very important option when backing up a - database in Firebird: platform dependant or portable. Performing a - portable backup allows the administrator to backup a database on an - operating system and restore that same database on another. This is - typically used when development is performed on Windows workstations, - and the operational database is then deployed on a more powerful Linux - server, for example. + There is no operation to backup differences only, or to restore an isolated set of + transactions. + Note that there is a very important option when backing up a database in Firebird: + platform dependant or portable. Performing a portable backup allows the administrator to + backup a database on an operating system and restore that same database on another. This is + typically used when development is performed on Windows workstations, and the operational + database is then deployed on a more powerful Linux server, for example. - Data Types - This section describes the different data types available in - Firebird and MS SQL, and how to translate types - from one system to another. - - MS SQL has different data types, depending on the version. The - following table lists the data types along with the version in which they - were introduced. - + Firebird and MS SQL, and how to translate types from one system to + another. + MS SQL has different data types, depending on the version. The following table lists the + data types along with the version in which they were introduced. + Data Types Conversion Table - - - - - MSSQL Ver - Data Type - Firebird - - MSSQL definition and - comments + MSSQL definition and comments - 6.5 - bigint - INT64 - 8-byte integer type. - 6.5 - binary - CHAR - - Fixed-length binary data with a maximum length of - 8,000 bytes. In 6.5, maximum was 255. + Fixed-length binary data with a maximum length of 8,000 bytes. In 6.5, + maximum was 255. - 6.5 - bit - CHAR(1) - - Integer data with either a 1 or 0 value. Typically, - replaced by constants 'T' and 'F'. + Integer data with either a 1 or 0 value. Typically, replaced by constants + 'T' and 'F'. - 6.5 - char - CHAR - - Fixed-length non-Unicode character data with a - maximum length of 8,000 characters. In 6.5, maximum was 255. - Firebird can hold up to 32,767 characters. + Fixed-length non-Unicode character data with a maximum length of 8,000 + characters. In 6.5, maximum was 255. Firebird can hold up to 32,767 + characters. - 6.5 - cursor - - - A reference to a cursor. This can only be used - inside stored procedure or triggers; it cannot be used on table - declarations. + A reference to a cursor. This can only be used inside stored procedure or + triggers; it cannot be used on table declarations. - 6.5 - datetime - TIMESTAMP - - Date and time data from January 1, 1753, to - December 31, 9999, with an accuracy of three-hundredths of a - second, or 3.33 milliseconds. + Date and time data from January 1, 1753, to December 31, 9999, with an + accuracy of three-hundredths of a second, or 3.33 milliseconds. - 6.5 - decimal - DECIMAL - Fixed precision and scale numeric data from - -1038 -1 through - 1038 -1. + -1038 -1 through 1038 + -1. - 6.5 - float - FLOAT - - Floating precision number data from -1.79E + 308 - through 1.79E + 308. + Floating precision number data from -1.79E + 308 through 1.79E + + 308. - 6.5 - image - BLOB - - Variable-length binary data with a maximum length - of 231 - 1 (2,147,483,647) - bytes. + Variable-length binary data with a maximum length of + 231 - 1 (2,147,483,647) bytes. - 6.5 - int - INTEGER - - Integer (whole number) data from - -231 (-2,147,483,648) through - 231 - 1 + Integer (whole number) data from -231 + (-2,147,483,648) through 231 - 1 (2,147,483,647). - 6.5 - money - DECIMAL(18, 4) - - Monetary data values from - -263 (-922,337,203,685,477.5808) - through 263 - 1 - (+922,337,203,685,477.5807), with accuracy to a ten-thousandth - of a monetary unit. + Monetary data values from -263 + (-922,337,203,685,477.5808) through 263 - 1 + (+922,337,203,685,477.5807), with accuracy to a ten-thousandth of a monetary + unit. - 7 - nchar - - CHAR(x) CHARACTER SET - UNICODE_FSS - - Fixed-length Unicode data with a maximum length of - 4,000 characters. + CHAR(x) CHARACTER SET UNICODE_FSS + Fixed-length Unicode data with a maximum length of 4,000 + characters. - 7 - ntext - BLOB SUB_TYPE TEXT - - Variable-length Unicode data with a maximum length - of 230 - 1 (1,073,741,823) - characters. + Variable-length Unicode data with a maximum length of + 230 - 1 (1,073,741,823) characters. - 6.5 - numeric - NUMERIC - - In MS SQL, decimal and numeric are - synonims. + In MS SQL, decimal and numeric are synonims. - 7 - nvarchar - - VARCHAR(x) CHARACTER SET - UNICODE_FSS - - Fixed-length Unicode data with a maximum length of - 4,000 characters. + VARCHAR(x) CHARACTER SET UNICODE_FSS + Fixed-length Unicode data with a maximum length of 4,000 + characters. - 6.5 - real - DOUBLE - - Floating precision number data from -3.40E + 38 - through 3.40E + 38. + Floating precision number data from -3.40E + 38 through 3.40E + + 38. - 6.5 - smalldatetime - TIMESTAMP - - Date and time data from January 1, 1900, through - June 6, 2079, with an accuracy of one minute. Firebird's has - greater range and accuracy. + Date and time data from January 1, 1900, through June 6, 2079, with an + accuracy of one minute. Firebird's has greater range and accuracy. - 6.5 - smallint - SMALLINT - - Integer data from -215 - (-32,768) through 215 - 1 - (32,767). + Integer data from -215 (-32,768) through + 215 - 1 (32,767). - 6.5 - smallmoney - DECIMAL(10, 4) - - Monetary data values from -214,748.3648 through - +214,748.3647, with accuracy to a ten-thousandth of a monetary - unit. Note that Firebird's range is greater with this - declaration. + Monetary data values from -214,748.3648 through +214,748.3647, with + accuracy to a ten-thousandth of a monetary unit. Note that Firebird's range is greater + with this declaration. - 2000 - sql_variant - BLOB - - Allows the storage of data values of different data - types. + Allows the storage of data values of different data types. - 2000 - table - none - - Stores results temporarily for later user. - + Stores results temporarily for later user. - 6.5 - text - BLOB SUB_TYPE TEXT - - Variable-length non-Unicode data with a maximum - length of 231 - 1 (2,147,483,647) - characters. + Variable-length non-Unicode data with a maximum length of + 231 - 1 (2,147,483,647) characters. - 6.5 - timestamp - INTEGER - - A database-wide unique number. In Firebird, you - will have to manage uniqueness through - generators. + A database-wide unique number. In Firebird, you will have to manage + uniqueness through generators. - 6.5 - tinyint - SMALLINT - - Integer data from 0 through 255. Firebird does not - have such a small data type. + Integer data from 0 through 255. Firebird does not have such a small data + type. - 6.5 - varbinary - CHAR - - Variable-length binary data with a maximum length - of 8,000 bytes. + Variable-length binary data with a maximum length of 8,000 + bytes. - 6.5 - varchar - VARCHAR - - Variable-length non-Unicode data with a maximum of - 8,000 characters. Firebird can hold up to 32,765 characters. In - 6.5, maximum was 255. + Variable-length non-Unicode data with a maximum of 8,000 characters. + Firebird can hold up to 32,765 characters. In 6.5, maximum was 255. - 7 - uniqueidentifier - CHAR(38) - - A globally unique identifier (GUID). In Firebird, - you will have to generate the values with User-Defined Functions - (UDFs). + A globally unique identifier (GUID). In Firebird, you will have to + generate the values with User-Defined Functions (UDFs).
- - A subtle difference in the way NUMERIC and - DECIMAL behave in Firebird to bear in mind is that the - NUMERIC definition means exactly the - precision requested (total number of digits), while DECIMAL - mean at least the request precision (the digits to - the right of the decimal symbol, however, are maintained exactly). In MS - SQL, on the other hand, numeric and decimal are - synonims. - - There is also a very common quasi-data type, identity, which can - only be used when defining tables. This is an int which is - automatically assigned a value on insertion and cannot be changed. - + A subtle difference in the way NUMERIC and DECIMAL behave in + Firebird to bear in mind is that the NUMERIC definition means + exactly the precision requested (total number of digits), while + DECIMAL mean at least the request precision (the digits to the + right of the decimal symbol, however, are maintained exactly). In MS SQL, on the other hand, + numeric and decimal are synonims. + There is also a very common quasi-data type, identity, which can only be used when + defining tables. This is an int which is automatically assigned a value on + insertion and cannot be changed. Converting the <type>bit</type> data type - - The bit data type is used to hold a single boolean - value, 0 or 1. MS SQL does not support assigning NULL to this fields. - InterBase can emulate this with an INTEGER or a - CHAR(1) data type. - - The acceptable values can be restricted using domains. For more - information on Firebird domains, see the Data Definition - documentation. + The bit data type is used to hold a single boolean value, 0 or 1. MS SQL + does not support assigning NULL to this fields. InterBase can emulate this with an + INTEGER or a CHAR(1) data type. + The acceptable values can be restricted using domains. For more information on Firebird + domains, see the Data Definition documentation. - Converting the identity data type - - There are many ways to perform the conversion. In general, - Firebird is more flexible and powerful in this respect. - - The most direct conversion is to create a BEFORE trigger on the - table, assigning to the previous column the value from a generator. This - ensures that the number is unique. - - For added flexibility, a single generator can be used for many - tables. In this case, the type would work in a similar way as a - timestamp would - by creating a database-wide unique identifier. - - Another common technique is to create a stored procedure to allow - access to the generator, and allow clients to pre-fetch the number. This - is particularly useful for tools such as Delphi which import the NOT - NULL constraint on primary keys and refuse to post records with NULL - values. - + There are many ways to perform the conversion. In general, Firebird is more flexible and + powerful in this respect. + The most direct conversion is to create a BEFORE trigger on the table, assigning to the + previous column the value from a generator. This ensures that the number is unique. + For added flexibility, a single generator can be used for many tables. In this case, the + type would work in a similar way as a timestamp would - by creating a database-wide unique + identifier. + Another common technique is to create a stored procedure to allow access to the + generator, and allow clients to pre-fetch the number. This is particularly useful for tools + such as Delphi which import the NOT NULL constraint on primary keys and refuse to post records + with NULL values. CREATE TABLE my_table ( my_number integer not null primary key ) - CREATE GENERATOR my_generator - CREATE TRIGGER my_before_trigger FOR my_table BEFORE INSERT AS @@ -675,7 +438,6 @@ BEGIN IF (NEW.my_number IS NULL) THEN NEW.my_number = GEN_ID(my_generator, 1); END - CREATE PROCEDURE get_my_generator RETURNS (new_value INTEGER) AS @@ -683,135 +445,92 @@ BEGIN new_value = GEN_ID(my_generator, 1); END - Converting the <type>uniqueidentifier</type> data type - - MS SQL depends on uniqueidentifier data types for - replication. It is also a handy way of creating a world-wide unique - identifier for a record. - - To use the field like this, create a BEFORE trigger on the table - with the field, and retrieve the value from a UDF. - + MS SQL depends on uniqueidentifier data types for replication. It is also a + handy way of creating a world-wide unique identifier for a record. + To use the field like this, create a BEFORE trigger on the table with the field, and + retrieve the value from a UDF. TODO: write the UDF and write the importing procedure - SQL Syntax - - This section describes differences in the SQL syntax used by - Firebird and MS SQL in general. - - Firebird and MS SQL can both use object - names (table names, field names, etc.) directly, when they have no - whitespace or other symbols. To include whitespace and otherwise escape - object names, MS SQL uses brackets, [ and ], while - Firebird uses double quotes, ". Another thing - to bear in mind is that MS SQL accepts a database.username.objectname - syntax to name objects, which Firebird does - not. - + This section describes differences in the SQL syntax used by Firebird and MS SQL in + general. + Firebird and MS SQL can both use object names (table names, + field names, etc.) directly, when they have no whitespace or other symbols. To include + whitespace and otherwise escape object names, MS SQL uses brackets, [ and ], while + Firebird uses double quotes, ". Another thing to bear in mind is that + MS SQL accepts a database.username.objectname syntax to name objects, which + Firebird does not. - Bear in mind that MS SQL is case-sensitive in its object naming if - it was installed with the case-sensitive option; otherwise it's case - insensitive. Fun. Not. + Bear in mind that MS SQL is case-sensitive in its object naming if it was installed with + the case-sensitive option; otherwise it's case insensitive. Fun. Not. - - MS SQL also accepts quoted identifiers, but by default it is set - only when accessed through OLE DB and ODBC, and not when accessed - through the DB-Library. In general, therefore, this practice is - discouraged. + MS SQL also accepts quoted identifiers, but by default it is set only when accessed + through OLE DB and ODBC, and not when accessed through the DB-Library. In general, therefore, + this practice is discouraged. - - MS SQL 7 and above supports modification on joins (update, delete, - insert). Firebird has no such syntax. - - Data types are, of course, different for the different database. - Both support a common subset with the most-used types; this is rarely an - issue. - - There are different built-in functions. Most of MS SQL functions can - be replaced and extended by UDFs in Firebird. - - There are different formats for specifying date constants. In - general, Firebird will accept different formats - independently of the underlying platform - MS SQL, on the other hand, uses - a mixture of server-independent, server-side platform and - per-client-connection formats. In addition to this, the MS SQL access - methods typically introduce one or two additional layers where a string - constant may be changed one way or another into a date. - - MS SQL has more environment variables than - Firebird does, but the most common ones - (identity retrieval and user name retrieval) can be found. The only - important variable missing is the row count of the latest - operation. - - An important difference is that Firebird - 1.0 does not support the MS SQL CASE statement. You - can sometimes use a stored procedure in its stead, which promotes - reusability and eases maintenance. Starting at 1.5, Firebird fully + MS SQL 7 and above supports modification on joins (update, delete, insert). + Firebird has no such syntax. + Data types are, of course, different for the different database. Both support a common + subset with the most-used types; this is rarely an issue. + There are different built-in functions. Most of MS SQL functions can be replaced and + extended by UDFs in Firebird. + There are different formats for specifying date constants. In general, + Firebird will accept different formats independently of the + underlying platform - MS SQL, on the other hand, uses a mixture of server-independent, + server-side platform and per-client-connection formats. In addition to this, the MS SQL access + methods typically introduce one or two additional layers where a string constant may be changed + one way or another into a date. + MS SQL has more environment variables than Firebird does, but + the most common ones (identity retrieval and user name retrieval) can be found. The only + important variable missing is the row count of the latest operation. + An important difference is that Firebird 1.0 does not support + the MS SQL CASE statement. You can sometimes use a stored procedure in its + stead, which promotes reusability and eases maintenance. Starting at 1.5, Firebird fully supports CASE. - - A minor difference is that MS SQL does not use a delimiter between - statement. This can be the source of some tricky bugs, specially when - using many parenthesis. Firebird requires that - every statement end in a semicolon ; so errors are easier to spot. - - Both MS SQL and Firebird support comments - using the /* and */ delimiters. MS SQL also supports the -- syntax to - comment a single line. Some client-side - Firebird tools also support this syntax, but it - is not supported in-line. - + A minor difference is that MS SQL does not use a delimiter between statement. This can be + the source of some tricky bugs, specially when using many parenthesis. + Firebird requires that every statement end in a semicolon ; so errors + are easier to spot. + Both MS SQL and Firebird support comments using the /* and */ + delimiters. MS SQL also supports the -- syntax to comment a single line. Some client-side + Firebird tools also support this syntax, but it is not supported + in-line. Using Database Basics - - MS SQL allows clients to use many databases from a single - connection. To do this, you can use the dbname.user.syntax, or execute - an explicit USE statement. - - Firebird does not allow you to use - different databases in the same SQL statement, but it does allow you to - perform transactions spanning multiple databases. - - There are many generic tools to enter SQL commands to your - database, in both platforms. Note that for - Firebird, you do not need to use - GO to delimit T-SQLbatches; rather, you manage - transactions explicitly. You can also use the default of - commit-every-statement on both servers. - + MS SQL allows clients to use many databases from a single connection. To do this, you + can use the dbname.user.syntax, or execute an explicit USE statement. + Firebird does not allow you to use different databases in the + same SQL statement, but it does allow you to perform transactions spanning multiple + databases. + There are many generic tools to enter SQL commands to your database, in both platforms. + Note that for Firebird, you do not need to use + GO to delimit T-SQLbatches; rather, you manage transactions explicitly. You + can also use the default of commit-every-statement on both servers. - If you MS SQL and Firebird setup on - the same computer, be careful with the isql - command. If you do not reference them by the full path, the one which - is first on your system path will be used, and both MS SQL and - Firebird have a command-line - isql program. + If you MS SQL and Firebird setup on the same computer, be + careful with the isql command. If you do not reference them by the full + path, the one which is first on your system path will be used, and both MS SQL and + Firebird have a command-line isql + program. - Using variables - - Variable handling is similar on both platforms. Variables must be - declared before being used, specifying their types. However, bear in - mind that variables names in Firebird need not be prefixed with a @ - character, and they do need to be declared before the procedure or + Variable handling is similar on both platforms. Variables must be declared before being + used, specifying their types. However, bear in mind that variables names in Firebird need not + be prefixed with a @ character, and they do need to be declared before the procedure or trigger body. - For example, compare the following code snippets. - /* MS-SQL */ CREATE PROCEDURE my_procedure AS DECLARE @my_variable int SET @my_variable = 5 - /* Firebird */ CREATE PROCEDURE my_procedure AS @@ -819,68 +538,46 @@ DECLARE VARIABLE my_variable int; BEGIN my_variable = 5; END - - Under both database servers, parameters are considered normal - variables, set to an initial value. + Under both database servers, parameters are considered normal variables, set to an + initial value. - Flow Control - <database>BEGIN ... END</database> - - Under both database servers, the BEGIN and - END keywords can be used to group multiple - statements, for example, inside an IF - branch. + Under both database servers, the BEGIN and END + keywords can be used to group multiple statements, for example, inside an + IF branch. - <database>GOTO</database> - - Firebird has no GOTO statement. However, this - usually turns for the better. GOTO statements are - usually used in MS SQL because errors do not roll back transactions by - default (the @@ERROR variable must be examined after every statement); - GOTO is used to group error handling statements. In - Firebird, there is a better error-handling mechanism: the - WHEN...DO statements. - - Of course, GOTO statements can be used for - other purposes. In these cases, using stored procedures correctly will - usually improve the database design. + Firebird has no GOTO statement. However, this usually turns for the + better. GOTO statements are usually used in MS SQL because errors do not + roll back transactions by default (the @@ERROR variable must be examined after every + statement); GOTO is used to group error handling statements. In Firebird, + there is a better error-handling mechanism: the WHEN...DO statements. + Of course, GOTO statements can be used for other purposes. In these + cases, using stored procedures correctly will usually improve the database design. - <database>IF</database> - - The IF..ELSE statement exists on Firebird - with the same semantics. However, Firebird syntax requires a THEN - after the IF condition clause. - + The IF..ELSE statement exists on Firebird with the same semantics. + However, Firebird syntax requires a THEN after the IF condition clause. IF (something = 'unknown') THEN something = 'uuhhh.....'; ELSE something = 'I know! I know!'; - <database>CASE</database> - - Firebird 1.0 doesn't have a CASE statement, - so you'll need to do some manual conversion work if it is used in your - MS-SQL database. - - You can skip - this section if you're using Firebird 1.5 or up, since these - versions fully support the CASE syntax. - - The CASE statement can be used as a - switch statement in C or a case statement in - Pascal to change one value for another. This can usually be translated - to Firebird 1.0 as a stored procedure + Firebird 1.0 doesn't have a CASE statement, so you'll need to do + some manual conversion work if it is used in your MS-SQL database. + You can skip this section if + you're using Firebird 1.5 or up, since these versions fully support the + CASE syntax. + The CASE statement can be used as a switch statement + in C or a case statement in Pascal to change one value for another. This can + usually be translated to Firebird 1.0 as a stored procedure returning some value. - /* This is the original MS SQL statement, using the * traditional pubs database. */ CREATE PROCEDURE list_states @@ -892,7 +589,6 @@ SELECT ELSE 'unknown' END FROM authors - /* This is how it can be converted to Firebird. */ /* Isolate the CASE statement. */ CREATE PROCEDURE get_state_name ( state_code char(2) ) @@ -917,42 +613,31 @@ BEGIN SUSPEND; END END - - - Three things should be noted from the example above. First, the - conversion is trivial. Second, it is however quite verbose. Third, - using a stored procedure allows for greater flexibility, and makes - maintenance easier. Suppose the CASE statement - for the state occurs in twelve different procedures, and a new state - was added; or that you misspelled a state name; or any other change. - It is clearly beneficial to abstract this conversion, trivial as it - may seem, into its own stored procedure. - - Again: as from version 1.5, Firebird fully supports the - CASE statement, so no conversion is needed - there. + Three things should be noted from the example above. First, the conversion is trivial. + Second, it is however quite verbose. Third, using a stored procedure allows for greater + flexibility, and makes maintenance easier. Suppose the CASE statement + for the state occurs in twelve different procedures, and a new state was added; or that you + misspelled a state name; or any other change. It is clearly beneficial to abstract this + conversion, trivial as it may seem, into its own stored procedure. + Again: as from version 1.5, Firebird fully supports the CASE + statement, so no conversion is needed there. - <database>WHILE</database> - - WHILE exists in - Firebird as it does in MS SQL, with some - differences. There are no BREAK or - CONTINUE statements, but these can be emulated with - additional controls and variables. There's also a small difference in - syntax; Firebird requires a DO keywords - after the WHILE condition. Compare the following - equivalent snips. - + WHILE exists in Firebird as it does in + MS SQL, with some differences. There are no BREAK or + CONTINUE statements, but these can be emulated with additional controls + and variables. There's also a small difference in syntax; + Firebird requires a DO keywords after the + WHILE condition. Compare the following equivalent snips. /* Firebird syntax. */ WHILE (i < 3) DO BEGIN i = i + 1; j = j * 2; END - /* MS SQL syntax. */ WHILE (i < 3) BEGIN @@ -960,125 +645,84 @@ BEGIN SET @j = @j * 2 END - <database>RETURN</database> - - The RETURN statement in MS SQL will return an - output integer variable and stop execution. Firebird supports the - EXIT statement, which will jump to the final - END in stored procedures. However, there is no - implicit output variable, so if you need to return a code (it's - optional in MS SQL), you will need to declare an output variable in - the procedure. + The RETURN statement in MS SQL will return an output integer + variable and stop execution. Firebird supports the EXIT statement, which + will jump to the final END in stored procedures. However, there is no + implicit output variable, so if you need to return a code (it's optional in MS SQL), you + will need to declare an output variable in the procedure. - <database>WAITFOR</database> - - The WAITFOR statement in MS SQL will suspend - execution for an amount of time, or until a specified time is reached. - Something like this could be done with a UDF; however, under both - database servers, an alternative would be very much preferred, as the - connection from the client remains suspended, too. + The WAITFOR statement in MS SQL will suspend execution for an + amount of time, or until a specified time is reached. Something like this could be done with + a UDF; however, under both database servers, an alternative would be very much preferred, as + the connection from the client remains suspended, too. - Standard Statements - The standard statements which can be found in all databases are - SELECT, INSERT, - UPDATE and DELETE. - Firebird and MS SQL support them, but there - are some non-standard MS SQL extension to consider if they are being - used. - - The SELECT statement in Firebird does not allow the INTO clause to - create a new table on the fly. Instead, it is used to bind a result into - a variable. - + SELECT, INSERT, UPDATE and + DELETE. Firebird and MS SQL support them, but + there are some non-standard MS SQL extension to consider if they are being used. + The SELECT statement in Firebird does not allow the INTO clause to create a new table on + the fly. Instead, it is used to bind a result into a variable. /* MS SQL syntax to get field values into a variable. */ SELECT @my_state = state FROM authors WHERE auth_name = 'John' - /* Firebird syntax. */ SELECT state INTO :state /* --> note the ":" before the name */ FROM authors WHERE auth_name = 'John' - - In MS SQL 7 and above, the SELECT clause can - take a TOP specifier to limit the number of rows - returned. This feature is currently under development for the - Firebird engine. - - Both MS SQL and Firebird support the - normal INSERT syntax and the - INSERT..SELECT syntax. - - Both MS SQL and Firebird support the - normal UPDATE. MS SQL also supports a form of - UPDATE in which a join is performed, and one side of - the join is updated. Think of this as a WHERE on - steroids. If this feature is absolutely required, it can be implemented - using views. - - Both MS SQL and Firebird support the normal DELETE. MS SQL also - supports the TRUNCATE TABLE statement, which is a more efficient (but - dangerous) form of DELETE. - + In MS SQL 7 and above, the SELECT clause can take a + TOP specifier to limit the number of rows returned. This feature is + currently under development for the Firebird engine. + Both MS SQL and Firebird support the normal + INSERT syntax and the INSERT..SELECT syntax. + Both MS SQL and Firebird support the normal + UPDATE. MS SQL also supports a form of UPDATE in which a + join is performed, and one side of the join is updated. Think of this as a + WHERE on steroids. If this feature is absolutely required, it can be + implemented using views. + Both MS SQL and Firebird support the normal DELETE. MS SQL also supports the TRUNCATE + TABLE statement, which is a more efficient (but dangerous) form of DELETE. /* MS SQL syntax to delete all records in my_table. */ TRUNCATE TABLE my_table /* ...or... */ DELETE FROM my_table - /* Firebird syntax. */ DELETE FROM my_table -
Jim Starkey - - The biggest threat are our fumbling fingers. More data has been - destroyed by "delete from xxx" "oops" than deliberate "delete - rdb$pages". + The biggest threat are our fumbling fingers. More data has been destroyed by "delete + from xxx" "oops" than deliberate "delete rdb$pages".
- Using Transactions - - Transactions are rarely used directly in - Firebird when using DSQL. Named transactions - are not supported in this case. Both syntaxes accept the + Transactions are rarely used directly in Firebird when using + DSQL. Named transactions are not supported in this case. Both syntaxes accept the WORK keyword for compatibility. - - This should not present a problem in most situations, as MS SQL's - explicit transaction control is usually in place because there no - support for using exception handlers. - + This should not present a problem in most situations, as MS SQL's explicit transaction + control is usually in place because there no support for using exception handlers. - MS SQL has a XACT_ABORT global variable, to - manage whether transactions are rolled back on run-time errors. - Otherwise, the @@ERROR variable must be examined - after each statement. + MS SQL has a XACT_ABORT global variable, to manage whether + transactions are rolled back on run-time errors. Otherwise, the @@ERROR + variable must be examined after each statement. - - In general, most discussions about isolation level problems found - in MS SQL environments are void when taken to a - Firebird database server. Contention between - readers and writers is minimal and is resolved by the multigeneration + In general, most discussions about isolation level problems found in MS SQL environments + are void when taken to a Firebird database server. Contention + between readers and writers is minimal and is resolved by the multigeneration architecture. - Using Cursors - - MS SQL uses cursors mostly to iterate over query results to - perform activities. Other than syntax, there is little difference in - what can be accomplished in either database. Although there are many - options for iterating backwards and forwards, in practice the only + MS SQL uses cursors mostly to iterate over query results to perform activities. Other + than syntax, there is little difference in what can be accomplished in either database. + Although there are many options for iterating backwards and forwards, in practice the only cursor used is the forward-only cursor. - /* MS SQL syntax. */ DECLARE my_cursor CURSOR FOR SELECT au_lname FROM authors ORDER BY au_lname @@ -1092,7 +736,6 @@ FOR SELECT au_lname FROM authors ORDER BY au_lname END CLOSE my_cursor DEALLOCATE my_cursor - /* Firebird syntax. */ DECLARE VARIABLE au_lname VARCHAR(40); ... @@ -1101,331 +744,252 @@ DECLARE VARIABLE au_lname VARCHAR(40); BEGIN /* Do something interesting with au_lname. */ END - - Note that MS SQL can place cursors in variables and pass them - around; this cannot be performed in - Firebird. - + Note that MS SQL can place cursors in variables and pass them around; this cannot be + performed in Firebird. - Different versions of MS SQL change the default scope for cursor - variables. Be careful with how you use them and bear this in mind when - reading code to convert it. + Different versions of MS SQL change the default scope for cursor variables. Be careful + with how you use them and bear this in mind when reading code to convert it. - Server-Side SQL - - This section goes beyond simple SQL syntax differences, and - describes the different tasks which can be accomplished server-side - through SQL. - + This section goes beyond simple SQL syntax differences, and describes the different tasks + which can be accomplished server-side through SQL. - SQL Tricks - - This section shows how to use some advanced - Firebird features to emulate MS SQL behaviour, - and avoid MS SQL workarounds. - + This section shows how to use some advanced Firebird features + to emulate MS SQL behaviour, and avoid MS SQL workarounds. Trick: Using Cascades - - Versions of MS SQL previous to 2000 will not support cascading - updates and deletes. Foreign keys will always roll back on - changes. - - In MS SQL, this is typically solved by a combination of stored - procedures and triggers, to avoid declaring the foreign key explicitly. - This, in turns, makes the relationships implicit rather than explicit, - which means that tools can't read the relationships directly and work on - them. - - During the migration process, all of the workaround procedures and - triggers can be ignored - Firebird supports - the cascading updates and deletes enforcing declaratively. + Versions of MS SQL previous to 2000 will not support cascading updates and deletes. + Foreign keys will always roll back on changes. + In MS SQL, this is typically solved by a combination of stored procedures and triggers, + to avoid declaring the foreign key explicitly. This, in turns, makes the relationships + implicit rather than explicit, which means that tools can't read the relationships directly + and work on them. + During the migration process, all of the workaround procedures and triggers can be + ignored - Firebird supports the cascading updates and deletes + enforcing declaratively. - Trick: Using Updateable Views - - Versions of MS SQL previous to 2000 will not support updates on - joined views fully. This is a major issue, since views are typically - considered read-only; there are numerous restrictions to have them being - updateable. - - In Firebird, there are also a number of - restrictions, but they are only meant for automatic - updating. If the engine cannot perform the updates by itself, you can - write triggers on the view to perform the required logic. + Versions of MS SQL previous to 2000 will not support updates on joined views fully. This + is a major issue, since views are typically considered read-only; there are numerous + restrictions to have them being updateable. + In Firebird, there are also a number of restrictions, but + they are only meant for automatic updating. If the engine cannot perform + the updates by itself, you can write triggers on the view to perform the required + logic. - Client Access - - This section describes the differences in how clients access a - Firebird and an MS SQL database. - + This section describes the differences in how clients access a Firebird and an MS SQL + database. Built-in Client Access Tools - - The standard command-line utility is isql. This - is used usually when executing large scripts, or when writing batch - files. - - When a graphical user interface (GUI) is available, the - administration tool will most probably be - IBConsole. This tool is similar to MS SQL's + The standard command-line utility is isql. This is used usually when + executing large scripts, or when writing batch files. + When a graphical user interface (GUI) is available, the administration tool will most + probably be IBConsole. This tool is similar to MS SQL's Enterprise Manager. - Client Access for Developers - - There are three basic mechanisms to get to a Firebird database. - You can either use the raw C API interface, an Open Database - Connectivity (ODBC) driver, or an OLE DB driver (the latter is used also - for ActiveX Data Objects, ADO, access). - - Using the raw C API allows developers to write portable code. All - platforms support this API. This is also the foundation for the popular - Delphi and C++ Builder component sets, such as InterBase Objects (IBO) - and InterBase Express (IBX). - - Using an ODBC driver lets developers write code that can be reused - with different databases, as long as they restrict themselves to a - common SQL subset. There are many tools which can use - Firebird through ODBC drivers. - - Using an OLE DB drivers lets developers use Microsoft's popular - ADO API. This allows the Firebird database to - be reached from tools such as Visual Basic or - ActiveX Server Pages (ASP). The most popular - driver is currently Microsoft's own OLE DB->ODBC bridge. + There are three basic mechanisms to get to a Firebird database. You can either use the + raw C API interface, an Open Database Connectivity (ODBC) driver, or an OLE DB driver (the + latter is used also for ActiveX Data Objects, ADO, access). + Using the raw C API allows developers to write portable code. All platforms support this + API. This is also the foundation for the popular Delphi and C++ Builder component sets, such + as InterBase Objects (IBO) and InterBase Express (IBX). + Using an ODBC driver lets developers write code that can be reused with different + databases, as long as they restrict themselves to a common SQL subset. There are many tools + which can use Firebird through ODBC drivers. + Using an OLE DB drivers lets developers use Microsoft's popular ADO API. This allows the + Firebird database to be reached from tools such as + Visual Basic or ActiveX Server Pages + (ASP). The most popular driver is currently Microsoft's own OLE DB->ODBC bridge. - Tools - - This section describes tools used to aid in migration, and to - replace standard tools found in MS SQL. - + This section describes tools used to aid in migration, and to replace standard tools found + in MS SQL. Migration Tools - - The following table lists tools which can be used to help you - migrate an MS SQL database to a Firebird database. - + The following table lists tools which can be used to help you migrate an MS SQL database + to a Firebird database. Migration Tools - - - Tool Name - Provided By - - Microsoft Access and Microsoft SQL Server to - InterBase Wizard - - Marcelo Lopez + Microsoft Access and Microsoft SQL Server to InterBase + Wizard + Marcelo Lopez Ruiz - IBDataPump - - Alex + Alex Poloziouk
- Replacing MS SQL Tools - - The following table lists tools which can be used to replace the - standard tools that come with MS SQL. - - Note that, in general, all applications that provide services - similar to Enterprise Manager also provide - query services. - + The following table lists tools which can be used to replace the standard tools that + come with MS SQL. + Note that, in general, all applications that provide services similar to + Enterprise Manager also provide query services. Replacement Tools - - - Tool Name - Replaced By - Books Online - Online PDF Documentation - Client Network Utility - - No need to; connection strings are fully - self-described. Test with IBConsole. + No need to; connection strings are fully self-described. Test with + IBConsole. - Enterprise Manager - IBConsole - Enterprise Manager - - IBExpert + IBExpert (commercial) - Enterprise Manager - - InterBase + InterBase Workbench (commercial) - Import and Export Data - - - Performance Monitor - - InterBase + InterBase Heartbeat (commercial) - Profiler - - InterBase Observer SQL + InterBase Observer SQL Profiler (commercial) - Query Analyzer - IBConsole - Server Network Utility - IBConsole - Service Manager - Control Panel Applet
- - These tools are just samples to help in replacement. For a better - and more up-to-date list, see IBPhoenix - Contributed Downloads + These tools are just samples to help in replacement. For a better and more up-to-date + list, see e.g. http://www.ibphoenix.com/download/tools/. - Document history - - The exact file history is recorded in the manual module in our CVS tree; see http://sourceforge.net/cvs/?group_id=9028 - + The exact file history is recorded in the manual + module in our CVS tree; see http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/migrationmssql.xml?view=log 1.0 - 2003 - MLR - - Written, published, and placed in the Public Domain by - Marcelo Lopez Ruiz. + Written, published, and placed in the Public Domain by Marcelo Lopez Ruiz. - 1.1 - 1 Oct 2005 - PV - - Added general warning about the document being - outdated. - - Divided the part on flow control into subsections. Made - clear that replacing CASE is only necessary - in pre-1.5 versions. - - Added document history and moved public domain notice to an - appendix. + Added general warning about the document being outdated. + Divided the part on flow control into subsections. Made clear that replacing + CASE is only necessary in pre-1.5 versions. + Added document history and moved public domain notice to an appendix. + + + + 1.2 + 14 Sep 2010 + MP + + Article's first sentence: three versions -> many versions, and added ulink to + MSSQL version history. + Pros and Cons :: Why migrate to + Firebird: Updated CPU + price info and + corresponding ulink (14 Sep 2010). + Pros and Cons :: Why not migrate to + Firebird: Removed para about incremental backups + (10 Mar 2011). + + + + 1.3 + 24 Jul 2011 + PV + + Edited article's first para and moved it into Introduction, + replacing its existing first para. Also edited beginning of Intro's second para. + Data types: Gave table a dbfo processing instruction so + that it won't get squeezed (and mutilated) on one PDF page. + Client Access :: Replacing MS SQL Tools: Updated link to + IBPhoenix tools download section. + Document history: Changed link to CVS source (now points + directly to document). Added info for document version 1.2. - Public Domain notice and disclaimer - - The author has placed this work in the Public Domain, thereby - relinquishing all copyrights. Everyone is free to use, modify, republish, - sell or give away this work without prior consent from anybody. - - This documentation is provided on an as is basis, - without warranty of any kind. Use at your own risk! Under no circumstances - shall the author(s) or contributor(s) be liable for damages resulting - directly or indirectly from the use or non-use of this + The author has placed this work in the Public Domain, thereby relinquishing all + copyrights. Everyone is free to use, modify, republish, sell or give away this work without + prior consent from anybody. + This documentation is provided on an as is basis, without warranty of any + kind. Use at your own risk! Under no circumstances shall the author(s) or contributor(s) be + liable for damages resulting directly or indirectly from the use or non-use of this documentation.
From ea314b19c8374196a11edf6430a9339f1a6c2505 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Mon, 19 Sep 2011 00:53:10 +0000 Subject: [PATCH 03/33] Du and En nbackup manuals v1.2 committed to release branch. --- src/docs/firebirddocs-nl/nbackup-nl.xml | 1368 ++++++++++++++--------- src/docs/firebirddocs/nbackup.xml | 1313 +++++++++++++--------- 2 files changed, 1616 insertions(+), 1065 deletions(-) diff --git a/src/docs/firebirddocs-nl/nbackup-nl.xml b/src/docs/firebirddocs-nl/nbackup-nl.xml index c9c597e4..fabd2b5a 100644 --- a/src/docs/firebirddocs-nl/nbackup-nl.xml +++ b/src/docs/firebirddocs-nl/nbackup-nl.xml @@ -6,870 +6,1170 @@
Firebirds nbackup-tool - Paul - Vinkenoog - - 5 januari 2007 — Documentversie 1.0-nl + 19 sep 2011 — Documentversie 1.2-nl -
Inleiding - - nbackup is een nieuwe backuptool die - meegeleverd wordt bij Firebird 2.0. Het biedt mogelijkheden die het al - langer bestaande gbak niet heeft, maar is geen - vervanging voor deze oudere tool. Beide programma's hebben hun sterke en - zwakke punten; vooralsnog zullen ze naast elkaar blijven bestaan. + Nbackup is een backupprogramma dat met Firebird wordt meegeleverd + sinds versie 2.0. Het biedt mogelijkheden die het al langer bestaande + gbak niet heeft, maar is geen vervanging voor deze oudere tool. Beide + programma's hebben hun sterke en zwakke punten; vooralsnog zullen ze naast elkaar blijven + bestaan.
-
- Kenmerken van nbackup — een overzicht - + Kenmerken van nbackup – een overzicht Kenmerken van nbackup - - Met nbackup kunnen twee verschillende soorten taken worden - uitgevoerd: - + Met nbackup kunnen twee verschillende soorten taken worden uitgevoerd: - Het maken en terugzetten van zowel volledige als aanvullende - backups. Een aanvullende backup (Engelse term: incremental - backup) bevat alleen de wijzigingen sinds een bepaalde - voorgaande backup. + Het maken en terugzetten van zowel volledige als aanvullende backups. Een aanvullende + backup (Engelse term: incremental backup) bevat alleen de wijzigingen + sinds een bepaalde voorgaande backup. - - Het vergrendelen van het databasebestand zodat het vervolgens - met kopieer- of backuptools naar keuze kan worden gebackupt. In deze - modus maakt nbackup dus géén backup; het zorgt alleen dat je er zelf - een kunt maken zonder risico op corruptie van de database. Ook hierbij - is er een voorziening voor terugzetten. + Het vergrendelen van het databasebestand zodat het vervolgens met kopieer- of + backuptools naar keuze kan worden gebackupt. In deze modus maakt nbackup dus géén backup; + het zorgt alleen dat je er zelf een kunt maken zonder risico op corruptie van de database. + Ook hierbij is er een voorziening voor terugzetten. - - Beide modi kunnen op een actieve database worden toegepast, zonder - hinder voor verbonden gebruikers. De gemaakte backup komt steeds overeen - met de toestand van de database aan het begin van de - operatie. Op deze punten is er dus geen verschil met - gbak. - + Beide modi kunnen op een actieve database worden toegepast, zonder hinder voor verbonden + gebruikers. De gemaakte backup komt steeds overeen met de toestand van de database aan + het begin van de operatie. Voorts geldt dat een backup alleen door de eigenaar en + SYSDBA (en soms ook door OS-admins) kan worden gemaakt, maar dat iedere + gebruiker een backup kan terugzetten naar een nieuwe database. Op deze punten is er dus geen + verschil met gbak.
Voordelen van nbackup - - Beide modi: een hoge snelheid (zo hoog - als hardware en besturingssysteem toelaten), want nbackup kijkt niet - naar de data zelf. In de backupmodus worden de gegevens min of meer - blindelings naar het backupbestand geschreven. + Beide modi: een hoge snelheid (zo hoog als hardware en + besturingssysteem toelaten), want nbackup kijkt niet naar de data zelf. In de backupmodus + worden de gegevens min of meer blindelings naar het backupbestand geschreven. - - Backup-restoremodus: tijd- en - ruimtewinst, want er is niet elke keer een volledige backup nodig. - Dit kan enorm schelen bij omvangrijke databases. + Backup-restoremodus: tijd- en ruimtewinst, want er is niet elke + keer een volledige backup nodig. Dit kan enorm schelen bij omvangrijke databases. - - Vergrendel-ontgrendelmodus: volledige - vrijheid in de keuze van de backup-, kopieer- en/of - compressietools. + Vergrendel-ontgrendelmodus: volledige vrijheid in de keuze van + de backup-, kopieer- en/of compressietools.
-
Beperkingen van nbackup - - nbackup zorgt niet voor het opschonen en inkrimpen van de - database zoals gbak dat doet. + Nbackup zorgt niet voor het opschonen en verdichten van de database zoals gbak dat + doet. - - Met een nbackup backup-restorecyclus kun je niet de eigenaar - van de database veranderen, zoals met gbak. + Met een nbackup backup-restorecyclus kun je niet de eigenaar van de database + veranderen, zoals met gbak. - - nbackup kan geen transporteerbare - backups maken, d.w.z. backups die je kunt terugzetten op - een ander platform of andere serverversie. + Nbackup kan geen transporteerbare backups maken, d.w.z. + backups die je kunt terugzetten op een ander platform of andere serverversie. - - nbackup is vooralsnog alleen bruikbaar voor databases die uit - een enkel bestand bestaan. + Nbackup is vooralsnog alleen bruikbaar voor databases die uit een enkel bestand + bestaan. + + + Nbackup zelf kan alleen lokale databases backuppen en terugzetten. Wel is het vanaf + Firebird 2.5 mogelijk om via de Services Manager deze functies ook op verre machines uit + te voeren. - - Met nbackup kun je alleen lokale databases backuppen. + Behalve bij gebruik van de Services Manager (in Firebird 2.5+) moet de gebruiker + voor het maken van een backup met nbackup rechtstreekse bestandstoegang tot de database + hebben. Met gbak is dit niet nodig. - - In de volgende secties zullen de diverse functies van nbackup - uitgebreid worden besproken.
- +
+ Functies en parameters + Hieronder volgt een overzicht van nbackups parameters. Als het veld Sinds + leeg is, bestaat de parameter al vanaf de eerste versie van nbackup, in Firebird 2.0. + + Parameters van nbackup + + + + + + + Parameter + Functie + Sinds + + + + + -B n <database> + [<bestand>] + Backup database naar bestand, niveau n + + + + -R <database> + [<bestand> ...] + Herstel database vanuit bestand(en) + + + + -L <database> + Vergrendel database + + + + -N <database> + Ontgrendel vergrendelde database + + + + -F <database> + Ontgrendel zelf teruggezette database + + + + -S + Geef grootte in pagina's (bij -L) + 2.1 + + + -T + Onderdruk databasetriggers (bij -B, -L, -N) + 2.1 + + + -D on|off + Rechtstreekse I/O aan/uit (bij -B) + 2.1.4 + + + -U <naam> + Geef gebruikersnaam op (bij -B, -L, -N) + + + + -P <wachtwoord> + Geef wachtwoord op (bij -B, -L, -N) + + + + -FE <bestand> + Lees wachtwoord uit bestand (bij -B, -L, -N) + 2.5 + + + -Z + Toon versie-info (los of bij -B, -R, -L, -N, -F) + 2.5 + + + -? + Help (schakelt alle andere opties uit) + 2.5 + + + +
+ Parameters van nbackup zijn niet hoofdlettergevoelig. Alle parameters zullen uitgebreid + worden besproken in het vervolg van deze handleiding. + Afhankelijk van de gebruikte hoofdfunctie (-B, + -R, -L, -N of + -F) kan nbackup verschillende typen toegang tot de database nodig hebben: + een verbinding via de Firebirdserver, rechtstreekse bestandstoegang, of beide. Hieronder een + overzicht: + + Benodigde toegang + + + + + + + Parameter + Functie + Toegang + + + + + -B + Backup + server + bestand + + + -R + Herstel + bestand + + + -L + Vergrendel + server + + + -N + Ontgrendel na -L + server + + + -F + Ontgrendel na zelf terugzetten + bestand + + + +
+ Waar servertoegang nodig is (bij -B, -L en + -N), moet de gebruiker ofwel een naam en wachtwoord opgeven (met + -U en -P/-FE of via de + omgevingsvariabelen ISC_USER en ISC_PASSWORD), ofwel op andere + gronden door de server worden toegelaten (bijv. als root onder Posix of door trusted + authentication onder Windows). + Waar bestandstoegang nodig is (bij -B, -R en + -F), moet de gebruiker voldoende lees- en/of schrijfrechten hebben op het + databasebestand. + Waar alléén bestandstoegang nodig is (bij -R en + -F), hoeft de gebruiker niet over een Firebird-inlog te beschikken en + hoeft zelfs geen server te draaien. + NB: In het bovenstaande gaat het telkens om toegang tot de database. + De toegang tot de backup is natuurlijk altijd puur op bestandsniveau. + +
Backups maken en terugzetten - - Vooraf: nbackup.exe bevindt zich in de - bin subdirectory van je - Firebird-map. Typische locaties zijn bijvoorbeeld C:\Program Files\Firebird\Firebird_2_0\bin - (Windows) of /opt/firebird/bin - (Linux). Net als de meeste meegeleverde tools heeft - nbackup geen grafische interface; je start het - vanaf de opdrachtregel (of vanuit een batchbestand of programma). - + Vooraf: nbackup.exe bevindt zich in de bin-subdirectory van je Firebird-map. Typische locaties zijn + bijvoorbeeld C:\Program Files\Firebird\Firebird_2_0\bin + (Windows) of /opt/firebird/bin (Linux). Net als de meeste + meegeleverde tools heeft nbackup geen grafische interface; je start + het vanaf de opdrachtregel of roept het aan vanuit een batchbestand of programma. + + Bij zware belasting kunnen nbackup 2.0.3 en lager soms problemen veroorzaken die leiden + tot vastlopers of zelfs beschadigde databases. Hoewel deze problemen niet vaak voorkomen, zijn + ze toch ernstig genoeg om upgraden naar Firebird 2.0.4 of hoger te rechtvaardigen als je + nbackup met een gerust hart wilt gebruiken. Bij grote databases op Posix-systemen kan ook het + al dan niet toepassen van rechtstreekse invoer/uitvoer een rol spelen. Zie hiervoor de + paragraaf Rechtstreekse + I/O. + +
Volledige backups - -
+
Een volledige backup maken - Om een volledige backup te maken luidt de opdracht: -
nbackup [-U <gebr> -P <wachtw>] -B 0 <database> [<backupbestand>]
- Voorbeeld: -
C:\Data> nbackup -B 0 inventaris.fdb inventaris_1-mrt-2006.nbk
- Opmerkingen: - - De parameter -B staat voor backup - (goh!). Het backupniveau 0 betekent dat er - een volledige backup wordt gemaakt. Backupniveaus hoger dan 0 - worden gebruikt voor aanvullende backups; deze worden verderop - besproken. + De parameter -B staat voor backup (goh!). Het + backupniveau 0 betekent dat er een volledige backup wordt + gemaakt. Backupniveaus hoger dan 0 worden gebruikt voor aanvullende backups; deze worden + verderop besproken. - - In plaats van een databasebestandsnaam mag ook een alias - worden opgegeven. + In plaats van een databasebestandsnaam mag ook een alias worden opgegeven. - - In plaats van een backupbestandsnaam mag ook - stdout worden opgegeven. De backup wordt - dan naar de standaarduitvoer gestuurd en kan vandaar worden - doorgeleid naar bijvoorbeeld een bandarchief of een - compressieprogramma. + In plaats van een backupbestandsnaam mag ook stdout + worden opgegeven. De backup wordt dan naar de standaarduitvoer gestuurd en kan vandaar + worden doorgeleid naar bijvoorbeeld een bandarchief of een compressieprogramma. - - - De parameters -U (user) en - -P (password) kunnen worden - weggelaten: - + + De parameters -U (user) en -P + (password) kunnen worden weggelaten als aan minstens één van de volgende voorwaarden is + voldaan: - als je als superuser (root, Administrator...) bent ingelogd, - of + De omgevingsvariabelen ISC_USER en ISC_PASSWORD + zijn ingesteld, ofwel op SYSDBA, ofwel op de eigenaar van de + database. + + + Je bent als root ingelogd op een Posixsysteem. Dit maakt je automatisch + SYSDBA. + + + + Onder Windows: trusted authentication (vertrouwde + inlog) is aangezet in firebird.conf, en het Windows-account + waaronder je bent aangemeld is eigenaar van de database. Dit is mogelijk vanaf + Firebird 2.1. - - als de omgevingsvariabelen ISC_USER en - ISC_PASSWORD zijn ingesteld. + Onder Windows: je bent lid van de Administrators-groep èn trusted + authentication staat aan in firebird.conf. In Firebird 2.1 heb + je dan automatisch SYSDBA-rechten. Vanaf Firebird 2.5 geldt als + aanvullende eis dat AUTO ADMIN MAPPING aangezet moet zijn in de + database. - - Voor de overzichtelijkheid laten we deze twee parameters in - de voorbeelden telkens weg. + Voor de overzichtelijkheid laten we de parameters -U en + -P in de voorbeelden telkens weg. - - De verschillende parameters (-B, - -U en -P) mogen in - elke gewenste volgorde voorkomen. Wel moet elke parameter direct - worden gevolgd door zijn eigen bijbehorende argument(en). Voor - -B zijn dat er drie: niveaugetal, database - en backupbestand — in die volgorde! + Met ingang van Firebird 2.5 kan in plaats van -P + <wachtwoord> ook -FE + <bestandsnaam> worden opgegeven. In dat geval wordt het + wachtwoord uit het opgegeven bestand gelezen. Voordeel is dat het wachtwoord zo beter + afgeschermd kan worden; het komt niet op de opdrachtregel terecht of in een + script/batchbestand waar mogelijk allerlei mensen bij kunnen. + (-FE staat voor fetch, haal op.) + + + In Firebird 2.1 en hoger kan met de parameter -T worden + voorkomen dat databasetriggers worden afgevuurd bij het maken van de backup. Voor meer + info zie Databasetriggers + onderdrukken. + + + Met ingang van Firebird 2.1.4 kan de gebruiker zelf bepalen of nbackup + rechtstreekse I/O toepast bij het maken van de backup. Dit gebeurt met de opties + -D on en -D + off. Meer details en achtergronden in de paragraaf Rechtstreekse I/O, + elders in deze handleiding. + + + De verschillende parameters (-B, -U + enz.) mogen in elke gewenste volgorde voorkomen. Wel moet elke parameter direct worden + gevolgd door zijn eigen bijbehorende argument(en). Voor -B zijn + dat er drie: niveaugetal, database en backupbestand — in die volgorde! - Als de -B-parameter als laatste komt, - mag de naam van het backupbestand worden - weggelaten. nbackup stelt dan zelf een naam samen, gebaseerd op de - naam van de database, het backupniveau, de datum en de tijd. Dit - kan overigens tot een botsing leiden (en tot een mislukte backup) - als twee backupopdrachten van hetzelfde niveau in dezelfde minuut - worden gegeven. + mag de naam van het backupbestand worden weggelaten. nbackup stelt + dan zelf een naam samen, gebaseerd op de naam van de database, het backupniveau, de + datum en de tijd. Dit kan overigens tot een botsing leiden (en tot een mislukte backup) + als twee backupopdrachten van hetzelfde niveau in dezelfde minuut worden gegeven. - - Gebruik nbackup niet voor databases die - uit meerdere bestanden bestaan. Dit kan leiden tot corruptie en - gegevensverlies, ondanks het feit dat nbackup niet zal protesteren - tegen een dergelijke opdracht. + Gebruik nbackup niet voor databases die uit meerdere bestanden + bestaan. Dit kan leiden tot corruptie en gegevensverlies, ondanks het feit dat nbackup + niet zal protesteren tegen een dergelijke opdracht. -
Iets over de werking - - NB: Wat onder dit kopje volgt is géén noodzakelijke kennis - voor het gebruik van nbackup. Het geeft alleen een globaal (en - onvolledig) beeld van wat er onder de motorkap gebeurt tijdens de - uitvoering van nbackup -B: - + NB: Wat onder dit kopje volgt is géén noodzakelijke kennis voor het gebruik van + nbackup. Het geeft alleen een globaal (en onvolledig) beeld van wat er onder de motorkap + gebeurt tijdens de uitvoering van nbackup -B: - Om te beginnen wordt het databasebestand vergrendeld door - het wijzigen van een interne toestandsvlag. Vanaf dit moment - worden alle wijzigingen in de database weggeschreven naar een - tijdelijk bestand — het verschilbestand oftewel + Om te beginnen wordt het databasebestand vergrendeld door het wijzigen van een + interne toestandsvlag. Vanaf dit moment worden alle wijzigingen in de database + weggeschreven naar een tijdelijk bestand — het verschilbestand oftewel deltabestand. - - Daarna wordt de feitelijke backup gemaakt. Dit is geen - rechttoe-rechtane bestandskopie; terugzetten moet dus ook weer - met nbackup gebeuren. + Daarna wordt de feitelijke backup gemaakt. Dit is geen rechttoe-rechtane + bestandskopie; terugzetten moet dus ook weer met nbackup gebeuren. - - Nadat de backup gemaakt is, wordt de inhoud van het - deltabestand geïntegreerd met het hoofdbestand. Vervolgens wordt - het hoofdbestand ontgrendeld (vlag gaat weer op + Nadat de backup gemaakt is, wordt de inhoud van het deltabestand geïntegreerd + met het hoofdbestand. Vervolgens wordt het hoofdbestand ontgrendeld (vlag gaat weer op normaal) en de delta verwijderd. - - De functionaliteit van de stappen 1 en 3 wordt verzorgd door - twee nieuwe SQL-opdrachten: ALTER DATABASE BEGIN - BACKUP en ALTER DATABASE END BACKUP. - In tegenstelling tot hetgeen de namen suggereren, zorgen deze - opdrachten niet voor het maken van de backup - zelf; ze scheppen alleen de noodzakelijke voorwaarden waaronder het - hoofdbestand veilig kan worden gebackupt. En voor alle - duidelijkheid: je hoeft deze SQL-opdrachten niet zelf te geven; + De functionaliteit van de stappen 1 en 3 wordt verzorgd door twee nieuwe + SQL-opdrachten: ALTER DATABASE BEGIN BACKUP en ALTER + DATABASE END BACKUP. In tegenstelling tot hetgeen de namen suggereren, zorgen + deze opdrachten niet voor het maken van de backup zelf; ze scheppen + alleen de noodzakelijke voorwaarden waaronder het hoofdbestand veilig kan worden + gebackupt. En voor alle duidelijkheid: je hoeft deze SQL-opdrachten niet zelf te geven; nbackup zorgt hiervoor, op de juiste momenten.
- -
+
Een volledige backup terugzetten - Een volledige backup wordt als volgt teruggezet: -
- nbackup [-U <gebr> -P <wachtw>] -R <database> [<backupbestand>] + nbackup -R <database> [<backupbestand>]
- Voorbeeld: -
C:\Data> nbackup -R inventaris.fdb inventaris_1-mrt-2006.nbk
- Opmerkingen: - Bij het terugzetten wordt geen niveau aangegeven. - Bij het terugzetten moet de parameter - -R (restore) de laatste zijn; dit om - redenen die later duidelijk zullen worden. + -R (restore) de laatste zijn; dit om redenen die later duidelijk + zullen worden. - - Als de opgegeven database al bestaat en er is niemand mee - verbonden, dan zal zij zonder enige waarschuwing worden - overschreven! Zijn er wel gebruikers verbonden, dan mislukt het - terugzetten en krijg je een foutmelding. + In plaats van een databasebestandsnaam mag ook een alias worden opgegeven. + + + Als de opgegeven database al bestaat, mislukt het terugzetten en krijg je een + foutmelding. + + + Ook bij het terugzetten mag de naam van het backupbestand worden weggelaten. + Nbackup vraagt je dan om de naam alsnog op te geven. (Let op: In Firebird 2.0 + is deze interactieve terugzetvoorziening defect; je krijgt dan een foutmelding en het + terugzetten mislukt. Hersteld in 2.0.1.) - - Ook bij het terugzetten mag de naam van het backupbestand - worden weggelaten. Nbackup vraagt je dan om de naam alsnog op te - geven. Deze voorziening is momenteel echter defect (in - elk geval onder Windows). Als je de backupbestandsnaam op deze - manier doorgeeft, krijg je een foutmelding en mislukt het - terugzetten. + Het terugzetten werkt puur op bestandsniveau en kan dus ook worden uitgevoerd + zonder dat er een Firebirdserver draait. Eventuele met -U en + -P meegegeven inloggegevens worden genegeerd. Ook als de + -FE-optie is gegeven, wordt het uit het bestand gelezen + wachtwoord niet gebruikt. Het wordt echter in eerste instantie wel ingelezen; treedt + daarbij een probleem op, dan mislukt het terugzetten.
-
Aanvullende backups - -
+ + De aanvullende-backupsvoorziening was compleet defect in Firebird 2.1, en weer + hersteld in 2.1.1. + + +
Aanvullende backups maken - - Om een aanvullende backup te maken geven we een niveau hoger dan - 0 aan. Een aanvullende backup van niveau N - bevat telkens de wijzigingen in de database sinds de meest recente - backup van niveau N-1. - + Om een aanvullende backup te maken geven we een niveau hoger dan 0 aan. Een + aanvullende backup van niveau N bevat telkens de wijzigingen in + de database sinds de meest recente backup van niveau N-1. Voorbeelden: - - Een dag na het maken van de volledige backup (met niveau 0) maak - je er een met niveau 1: - + Een dag na het maken van de volledige backup (met niveau 0) maak je er een met niveau + 1:
C:\Data> nbackup -B 1 inventaris.fdb inventaris_2-mrt-2006.nbk
- - Deze backup bevat dus alleen de wijzigingen van de laatste - dag. - + Deze backup bevat dus alleen de wijzigingen van de laatste dag. Weer een dag later maak je er nog eentje van niveau 1: -
C:\Data> nbackup -B 1 inventaris.fdb inventaris_3-mrt-2006.nbk
- - Deze backup bevat de wijzigingen van de laatste - twee dagen, sinds de volledige backup, dus niet - alleen die sinds de vorige niveau-1-backup. - + Deze backup bevat de wijzigingen van de laatste twee dagen, sinds + de volledige backup, dus niet alleen die sinds de vorige niveau-1-backup. Een paar uur later maken we een backup van niveau 2: -
C:\Data> nbackup -B 2 inventaris.fdb inventaris_3-mrt-2006_2.nbk
- - Deze jongste backup bevat alleen de wijzigingen sinds de meest - recente niveau-1-backup, dus die van de laatste paar uren. - + Deze jongste backup bevat alleen de wijzigingen sinds de meest recente + niveau-1-backup, dus die van de laatste paar uren. - Alle opmerkingen - die gemaakt zijn bij het maken van volledige backups, gelden ook - voor aanvullende backups. + Alle opmerkingen die gemaakt zijn bij + het maken van volledige backups, gelden ook voor aanvullende backups. - - Nogmaals: gebruik nbackup niet voor databases die uit meerdere - bestanden bestaan. + Nogmaals: gebruik nbackup niet voor databases die uit meerdere bestanden + bestaan.
- -
+
Aanvullende backups terugzetten - - Bij het terugzetten van aanvullende backups moet de hele reeks - backupbestanden worden gespecificeerd vanaf niveau 0 tot en met het - gewenste niveau. De database wordt daarbij altijd vanaf de grond - opnieuw opgebouwd, in stappen (dit stapsgewijs aanvullen tot een - volledig herstelde database verklaart de Engelse term - incremental backup). - + Bij het terugzetten van aanvullende backups moet de hele reeks backupbestanden worden + gespecificeerd vanaf niveau 0 tot en met het gewenste niveau. De database wordt daarbij + altijd vanaf de grond opnieuw opgebouwd, in stappen (dit stapsgewijs aanvullen tot een + volledig herstelde database verklaart de Engelse term incremental + backup). De formele syntaxis luidt: -
- nbackup [-U <gebruiker> -P <wachtwoord>] - -R <database> [<backup0> [<backup1> [...] ] ] + nbackup -R <database> [<backup0> [<backup1> [...] ] ]
- - Het terugzetten van de niveau-2-backup uit het voorgaande - voorbeeld gaat dus als volgt: - + Het terugzetten van de niveau-2-backup uit het voorgaande voorbeeld gaat dus als + volgt:
C:\Data> nbackup -R inventaris.fdb inventaris_1-mrt-2006.nbk inventaris_3-mrt-2006.nbk inventaris_3-mrt-2006_2.nbk
- - Uiteraard is de regel hier alleen gesplitst voor de - overzichtelijkheid — in de praktijk typ je alles achter elkaar en - drukt dan pas op Enter. - + Uiteraard is de regel hier alleen gesplitst voor de overzichtelijkheid — in de + praktijk typ je alles achter elkaar en drukt dan pas op Enter. Opmerkingen (in aanvulling op de opmerkingen bij het terugzetten - van een volledige backup): - + linkend="nbackup-nl-terugzetten-opm">opmerkingen bij het terugzetten van een volledige + backup): - Omdat bij de -R-optie niet van - tevoren bekend is hoeveel bestandsnamen er zullen volgen (bij - terugzetten geven we immers geen niveaugetal op), gaat nbackup - ervan uit dat alle argumenten na de -R - namen van backupbestanden zijn. Het is hierom dat er na de lijst - met bestandsnamen geen andere parameter (-U - of -P) meer mag volgen. + Omdat bij de -R-optie niet van tevoren bekend is hoeveel + bestandsnamen er zullen volgen (bij terugzetten geven we immers geen niveaugetal op), + gaat nbackup ervan uit dat alle argumenten na de -R namen van + backupbestanden zijn. Het is hierom dat er na de lijst met bestandsnamen geen andere + parameter meer mag volgen. - - Er is geen formele limiet aan het aantal backupniveaus, maar - verder gaan dan niveau 3 of 4 zal in de praktijk zelden nut - hebben. + Er is geen formele limiet aan het aantal backupniveaus, maar verder gaan dan + niveau 3 of 4 zal in de praktijk zelden nut hebben. - -
+
Niet-passende schakels - - Wat gebeurt er als je per ongeluk een bestand weglaat, of een - reeks bestanden opgeeft die niet allemaal bij elkaar passen? Je zou - je voor kunnen stellen dat je in het bovenstaande voorbeeld bij - vergissing inventaris_2-mrt-2006.nbk opgeeft in - plaats van inventaris_3-mrt-2006.nbk. Beide - zijn backupbestanden van niveau 1; in beide gevallen krijgen we dus - een keurige niveaureeks 0, 1, 2. Maar het niveau-2-bestand is - aanvullend ten opzichte van de niveau-1-backup van 3 maart, niet - t.o.v. die van 2 maart. - - Gelukkig kan een dergelijke vergissing nooit tot een foutief - teruggezette database leiden. Elk backupbestand bevat namelijk een - unieke ID. Voorts is in elke backup van niveau 1 of hoger de ID - opgeslagen van de backup waarop hij gebaseerd is. Bij het - terugzetten controleert nbackup deze gegevens; als er ergens in de - keten iets niet klopt, wordt de operatie geannuleerd en krijg je een - foutmelding. + Wat gebeurt er als je per ongeluk een bestand weglaat, of een reeks bestanden + opgeeft die niet allemaal bij elkaar passen? Je zou je voor kunnen stellen dat je in het + bovenstaande voorbeeld bij vergissing inventaris_2-mrt-2006.nbk + opgeeft in plaats van inventaris_3-mrt-2006.nbk. Beide zijn + backupbestanden van niveau 1; in beide gevallen krijgen we dus een keurige niveaureeks 0, + 1, 2. Maar het niveau-2-bestand is aanvullend ten opzichte van de niveau-1-backup van 3 + maart, niet t.o.v. die van 2 maart. + Gelukkig kan een dergelijke vergissing nooit tot een foutief teruggezette database + leiden. Elk backupbestand bevat namelijk een unieke ID. Voorts is in elke backup van + niveau 1 of hoger de ID opgeslagen van de backup waarop hij gebaseerd is. Bij het + terugzetten controleert nbackup deze gegevens; als er ergens in de keten iets niet klopt, + wordt de operatie geannuleerd en krijg je een foutmelding.
- +
+ Databases op kale apparaten backuppen + Een Firebird-database hoeft geen bestand te zijn, maar kan zich ook op een zogeheten + kaal apparaat, bijvoorbeeld een schijfpartitie zonder bestandssysteem, + bevinden. De vraag waar de delta dan + geplaatst moet worden, is bij het ontwikkelen van nbackup in eerste + instantie over het hoofd gezien. Op Posix-systemen kon het zo gebeuren dat als de database + zich op /dev/hdb5 bevond, een deltabestand + /dev/hdb5.delta werd aangemaakt. Dat is onwenselijk gezien aard en doel + van de /dev-map en de meestal geringe beschikbare ruimte. + Vanaf Firebird 2.1 weigert nbackup dan ook te werken met databases op kale apparaten als + niet expliciet een locatie voor het deltabestand is ingesteld. Hoe dit moet, wordt besproken + in Het deltabestand + instellen, verderop in deze handleiding. +
+
+ Databasetriggers onderdrukken (Firebird 2.1+) + Sinds versie 2.1 ondersteunt Firebird het gebruik van + databasetriggers. Deze kunnen o.a. worden afgevuurd bij het maken en + verbreken van een verbinding. Rond het uitvoeren van een backup maakt nbackup via de server + verbinding met de database (in sommige versies zelfs meermalen). Om nu te voorkomen dat + hierbij onbedoeld databasetriggers afgevuurd worden, kan de optie -T + worden meegegeven. NB: de overeenkomstige optie in gbak en + isql heet -nodbtriggers (we zijn dol op + variatie, hier bij Firebird). +
+
+ Rechtstreekse I/O (Firebird 2.1.4+) + Oorspronkelijk gebruikte nbackup bij het maken van de backup onder Windows NT (en + afgeleiden zoals 2000, 2003 enz.) rechtstreekse invoer/uitvoer, en in alle andere gevallen + niet. Omdat dit op sommige Linuxsystemen voor problemen zorgde, werd in Firebird 2.0.6 en + 2.1.3 ook onder Linux voor rechtstreekse I/O gekozen. Maar dit leidde weer tot problemen op + andere Linuxsystemen. Daarom is in 2.1.4 en 2.5 het standaardgedrag weer zoals voorheen, en is + een parameter -D toegevoegd waarmee de gebruiker zelf de rechtstreekse + I/O aan of uit kan zetten. Het gebruik is als volgt: +
+ nbackup -B 0 glazen.fdb glazen.nbk -D on -- rechtstreekse I/O aan +nbackup -B 0 bekers.fdb bekers.nbk -D off -- rechtstreekse I/O uit +
+ De argumenten ON en OFF zijn niet hoofdlettergevoelig, evenmin als de parameterletters + zelf. + Rechtstreekse I/O wordt alléén toegepast bij het maken van een backup, niet bij het + terugzetten. Onder Windows wordt hiertoe FILE_FLAG_NO_BUFFERING aangezet. + Op andere systemen worden O_DIRECT en + POSIX_FADV_NOREUSE gebruikt. Deze laatste twee vlaggen zijn soms niet + beschikbaar; in zo'n geval worden ze (of wordt er één) stilzwijgend weggelaten. Ook als de + gebruiker expliciet -D on heeft meegegeven, + leidt dit niet tot een waarschuwing of foutmelding. +
+
+ Informatieve opties (Firebird 2.5+) + Behalve de al genoemde parameters -FE en + -D zijn in Firebird 2.5 ook nog de volgende twee toegevoegd: + + + -Z + + Toont éénregelige versie-informatie. Deze optie kan los worden gebruikt, maar ook + in combinatie met andere parameters zoals -B, + -R, -L enz. + + + + -? + + Geeft een beknopt overzicht van het gebruik van nbackup en de diverse parameters. + NB: als deze optie aanwezig is, worden alle andere parameters genegeerd! + + + +
+
+ Backups op verre machines (Firebird 2.5+) + Nbackup zelf werkt alleen op lokale databases. Maar vanaf Firebird 2.5 kunnen via de + Service Manager ook op verre machines backups en restores van het nbackup-type worden + uitgevoerd. Hiervoor gebruik je op de lokale machine het programma + fbsvcmgr.exe, dat in dezelfde map staat als + nbackup.exe en de overige Firebird-hulpprogramma's. Als eerste argument + geef je hostnaam:service_mgr op, waarbij je + hostnaam natuurlijk vervangt door de naam van de verre server. + Overige parameters zijn: +
+ -user gebrnaam +-password wachtwoord +-action_nbak +-action_nrest +-nbk_level n +-dbname database +-nbk_file bestnaam +-nbk_no_triggers +-nbk_direct on|off +
+ Het maken van een volledige backup op de verre machine frodo gaat dan bijvoorbeeld zo: +
+ fbsvcmgr frodo:service_mgr -user sysdba -password masterke + -action_nbak -nbk_level 0 + -dbname C:\databases\landen.fdb -nbk_file C:\databases\landen.nbk +
+ En van een latere aanvullende backup: +
+ fbsvcmgr frodo:service_mgr -user sysdba -password masterke + -action_nbak -nbk_level 1 + -dbname C:\databases\landen.fdb -nbk_file C:\databases\landen_1.nbk +
+ Terugzetten van de hele zwikzwak gaat als volgt: +
+ fbsvcmgr frodo:service_mgr -user sysdba -password masterke + -action_nrest -dbname C:\databases\landen_hersteld.fdb + -nbk_file C:\databases\landen.nbk -nbk_file C:\databases\landen_1.nbk +
+ Let op: in werkelijkheid moet elk van de bovenstaande opdrachten als één zin worden + getypt, zonder regeleinden. Verder mogen de streepjes voor de parameternamen worden + weggelaten, maar juist bij dit soort lange opdrachten is het meestal prettiger om ze wel te + gebruiken: je ziet dan duidelijk de afzonderlijke parameters (de argumenten krijgen geen + streepje). + Opmerkingen: + + + De Services Manager verlangt altijd authenticatie, hetzij automatisch (root onder + Posix, trusted onder Windows), hetzij expliciet via de parameters + -user en -password. De omgevingsvariabelen + ISC_USER en ISC_PASSWORD worden echter niet ingelezen. + AUTO ADMIN MAPPING in de database heeft geen effect als je vanaf een + andere machine verbinding maakt (maar misschien is dit afhankelijk van de configuratie van + het netwerk). + NB: Bij Windows trusted krijgt de Services Manager op de verre machine de + gebruikersnaam doorgegeven van de aanroeper op de lokale machine. Is de eigenaar van de + database een Windows-account (bijv. FRODO\PAUL) + i.p.v. een Firebirdaccount, en komt de Windows-accountnaam van de aanroeper op de lokale + machine overeen met het eigenaar-account op de verre machine, dan wordt de aanroeper als + eigenaar erkend en kan de backup gemaakt worden. Dit kan een veiligheidsrisico opleveren, + want ook binnen een lokaal netwerk hoeft gebruiker PAUL op de ene machine niet dezelfde persoon te zijn als + PAUL op de andere. + + + Ook bij terugzetten (-action_nrest) is authenticatie vereist, + maar de inloggegevens worden dan verder niet gebruikt. De gebruiker hoeft dus geen + eigenaar, SYSDBA of superuser te zijn. In geval van Windows trusted + authentication hoeft de gebruiker op de verre machine (waar de database zich bevindt) + zelfs helemaal niet te bestaan. + Deze zwakke authenticatie levert ook weer een potentieel veiligheidsrisico op. Stel + dat er van een gevoelige database nbackups worden gemaakt, en dat deze op bestandsniveau + goed worden beveiligd. Een willekeurige gebruiker kan dan niet met nbackup de database + herstellen, want nbackup draait in de procesruimte van de gebruiker. Maar diezelfde + gebruiker kan – als hij locatie en bestandsnaam weet, of deze op grond van analogie kan + raden – wellicht met fbsvcmgr de database naar een publieke map + terugzetten en hem aldus te pakken krijgen. Immers, fbsvcmgr roept de Firebirdserver aan + en die heeft mogelijk wèl bestandstoegang tot de backup. Natuurlijk zijn hier oplossingen + voor te bedenken, maar het is wel zaak om je van dit risico bewust te zijn. + + + + De Services Manager kan ook lokaal worden gebruikt; het eerste argument wordt dan + service_mgr, zonder hostnaam. Bij lokaal gebruik heeft + AUTO ADMIN MAPPING wel het normale effect; dit geldt ook als je + bijvoorbeeld localhost: of de naam van de lokale machine voorvoegt. + Lokaal gebruik van de Services Manager kan van nut zijn als je zelf geen bestandstoegang + hebt tot database en/of backup, en het Firebirdproces wel. Heb je wel voldoende + bestandsrechten, dan kun je beter nbackup zelf gebruiken, met zijn veel kortere + opdrachtregels. + + + Gebruik van -nbk_no_triggers of + -nbk_direct bij -action_nrest leidt tot een + foutmelding. Nbackup zelf is hier soepeler in: die negeert de parameters + -T en -D gewoon als je ze gebruikt waar ze + niet van toepassing zijn. + + + In plaats van een databasenaam mag ook een alias worden gebruikt. + + +
Toepassing in de praktijk - - Een backupschema met gebruik van nbackup zou er als volgt uit - kunnen zien: - + Een backupschema met gebruik van nbackup zou er als volgt uit kunnen zien: Elke maand een volledige backup (niveau 0); - Elke week een niveau 1; - Dagelijks een niveau 2; - Elk uur een niveau 3. - - Zolang alle backups bewaard worden, kun je met dit schema de - database herstellen tot de toestand van elk gewenst uur in het verleden. - Hierbij worden voor elke herstelactie maximaal vier backupbestanden - gebruikt. Natuurlijk regel je e.e.a. zo dat de grotere, tijdrovende - backups op rustige uren gepland worden. In dit geval zouden de backups - van de niveaus 0 en 1 in de weekeinden gemaakt kunnen worden, en die van - niveau 2 's nachts. - - Wil je niet alles voor de eeuwigheid bewaren, dan kun je er een - wisschema aan koppelen: - + Zolang alle backups bewaard worden, kun je met dit schema de database herstellen tot de + toestand van elk gewenst uur in het verleden. Hierbij worden voor elke herstelactie maximaal + vier backupbestanden gebruikt. Natuurlijk regel je e.e.a. zo dat de grotere, tijdrovende + backups op rustige uren gepland worden. In dit geval zouden de backups van de niveaus 0 en 1 + in de weekeinden gemaakt kunnen worden, en die van niveau 2 's nachts. + Wil je niet alles voor de eeuwigheid bewaren, dan kun je er een wisschema aan + koppelen: - Niveau-3-backups worden gewist als ze ouder zijn dan acht - dagen; + Niveau-3-backups worden gewist als ze ouder zijn dan acht dagen; - Backups van niveau 2 na een maand; - Niveau 1 na zes maanden; - - Niveau 0 na twee jaar, behalve bijvoorbeeld de eerste van elk - jaar. + Niveau 0 na twee jaar, behalve bijvoorbeeld de eerste van elk jaar. - - Dit is uiteraard maar een voorbeeld. Wat in een bepaald geval - nuttig is, hangt af van de toepassing, de databasegrootte, de - activiteit, enzovoort. + Dit is uiteraard maar een voorbeeld. Wat in een bepaald geval nuttig is, hangt af van de + toepassing, de databasegrootte, de activiteit, enzovoort.
-
Verder lezen? - - Je weet nu alles wat nodig is om met nbackup volledige en/of - aanvullende backups te maken en terug te zetten. Je hoeft alleen verder - te lezen als je backuptools naar keuze wilt gebruiken voor je - Firebird-databases (zie Vergrendelen en - ontgrendelen), of als je de standaardnaam of -locatie - van het deltabestand wilt aanpassen (zie Je weet nu alles wat nodig is om met nbackup volledige en/of aanvullende backups te + maken en terug te zetten. Je hoeft alleen verder te lezen als je backuptools naar keuze wilt + gebruiken voor je Firebird-databases (zie Vergrendelen en ontgrendelen), + of als je de standaardnaam of -locatie van het deltabestand wilt aanpassen (zie Het deltabestand instellen). - - Heb je daar allemaal geen behoefte aan, dan wensen we je veel - succes toe bij het werken met nbackup! + Heb je daar allemaal geen behoefte aan, dan wensen we je veel succes toe bij het werken + met nbackup!
-
Vergrendelen en ontgrendelen - - Wil je liever met je eigen backupgereedschap een veiligheidskopie - maken, of gewoon een bestandskopie maken, dan komt modus 2, de - ver/ontgrendeltaak, in beeld. Vergrendelen houdt hier in - dat het hoofdbestand van de database tijdelijk wordt bevroren, - niet dat er geen wijzigingen in de database mogen - plaatsvinden. Net als bij modus 1 worden wijzigingen naar een tijdelijk - bestand geschreven en na ontgrendelen alsnog opgenomen in het - hoofdbestand. - - Ter herinnering: nbackup.exe bevindt zich in de - bin subdirectory van je - Firebird-map. Typische locaties zijn bijvoorbeeld C:\Program Files\Firebird\Firebird_2_0\bin - (Windows) of /opt/firebird/bin - (Linux). Er is geen grafische interface; je start het vanaf de - opdrachtregel (of vanuit een batchbestand of programma). - + Wil je liever met je eigen backupgereedschap een veiligheidskopie maken, of gewoon een + bestandskopie maken, dan komt modus 2, de ver/ontgrendeltaak, in beeld. + Vergrendelen houdt hier in dat het hoofdbestand van de database tijdelijk wordt + bevroren, niet dat er geen wijzigingen in de database mogen plaatsvinden. + Net als bij modus 1 worden wijzigingen naar een tijdelijk bestand geschreven en na ontgrendelen + alsnog opgenomen in het hoofdbestand. + Ter herinnering: nbackup.exe bevindt zich in de bin-subdirectory van je Firebird-map. Typische locaties zijn + bijvoorbeeld C:\Program Files\Firebird\Firebird_2_0\bin + (Windows) of /opt/firebird/bin (Linux). Er is geen + grafische interface; je start het vanaf de opdrachtregel of roept het aan vanuit een + batchbestand of programma.
Database vergrendelen en zelf backuppen - - Een typische sessie waarbij je zelf de backup maakt, verloopt als - volgt. - + Een typische sessie waarbij je zelf de backup maakt, verloopt als volgt. - Vergrendel de database met de optie -L - (lock): - + Vergrendel de database met de optie -L (lock):
nbackup [-U <gebruiker> -P <wachtwoord>] -L <database>
- - Kopieer/backup/zip het databasebestand nu naar hartelust met - gereedschap van je eigen keuze. Een simpele bestandskopie is ook - mogelijk. + Kopieer/backup/zip het databasebestand nu naar hartelust met gereedschap van je + eigen keuze. Een simpele bestandskopie is ook mogelijk. - - Ontgrendel de database met -N - (uNlock): - + Ontgrendel de database met -N (uNlock):
nbackup [-U <gebruiker> -P <wachtwoord>] -N <database>
- - Door de laatste opdracht worden ook eventuele wijzigingen – die - naar een tijdelijk bestand zijn weggeschreven – weer in het hoofdbestand - verwerkt. - - De gemaakte backup/kopie bevat de gegevens zoals die op het moment - van vergrendelen in de database aanwezig waren, ongeacht hoe lang de - vergrendeling heeft geduurd en ongeacht hoelang je hebt gewacht met het - maken van de feitelijke backup. - + Door de laatste opdracht worden ook eventuele wijzigingen – die naar een tijdelijk + bestand zijn weggeschreven – weer in het hoofdbestand verwerkt. + De gemaakte backup/kopie bevat de gegevens zoals die op het moment van vergrendelen in + de database aanwezig waren, ongeacht hoe lang de vergrendeling heeft geduurd en ongeacht + hoelang je hebt gewacht met het maken van de feitelijke backup. + Opmerkingen: + + + In plaats van een databasebestandsnaam mag ook een alias worden opgegeven. + + + De parameters -U en -P kunnen worden + weggelaten als ISC_USER en ISC_PASSWORD zijn ingesteld, als + je root bent op een Posixsysteem, of als trusted authentication onder + Windows dit mogelijk maakt. Zie voor een uitgebreidere beschrijving de opmerkingen onder Een volledige + backup maken. + + + Met ingang van Firebird 2.5 kan in plaats van -P + <wachtwoord> ook -FE + <bestandsnaam> worden opgegeven. + + + Zowel -L als -N maken verbinding met + de database, dus in Firebird 2.1 en hoger kan het verstandig zijn om de optie + -T toe te voegen (zie Databasetriggers + onderdrukken). + + + Bij het vergrendelen van een database op een kaal apparaat kan de + -S-optie van groot nut zijn; zie Databases op kale apparaten + vergrendelen. + + + Eventueel kun je -Z toevoegen om éénregelige + versie-informatie te laten tonen. + + - Ook voor de ver- en ontgrendelfuncties van nbackup geldt dat ze - niet gebruikt moeten worden op databases die uit meerdere bestanden - bestaan. Zolang er op dit punt niets veranderd is, moet nbackup op - geen enkele wijze op dit soort databases worden losgelaten! + Ook voor de ver- en ontgrendelfuncties van nbackup geldt dat ze niet gebruikt moeten + worden op databases die uit meerdere bestanden bestaan. Zolang er op dit punt niets + veranderd is, moet nbackup op geen enkele wijze op dit soort databases worden + losgelaten!
-
- Terugzetten van een na <quote>nbackup -L</quote> gemaakte - backup - - Een kopie van een vergrendelde database is natuurlijk zelf ook een - vergrendelde database, en daarom niet meteen klaar voor normaal gebruik. - Mocht je oorspronkelijke database verloren gaan of beschadigd raken, en - de zelfgemaakte kopie moet worden teruggezet (of mocht je de kopie op - een andere computer willen installeren), ga dan als volgt te - werk: - + Terugzetten van een na <quote>nbackup -L</quote> gemaakte backup + Een kopie van een vergrendelde database is natuurlijk zelf ook een vergrendelde + database, en daarom niet meteen klaar voor normaal gebruik. Mocht je oorspronkelijke database + verloren gaan of beschadigd raken, en de zelfgemaakte kopie moet worden teruggezet (of mocht + je de kopie op een andere computer willen installeren), ga dan als volgt te werk: - Kopieer/herstel/ontzip zelf de databasebackup met het daarvoor - benodigde gereedschap. + Kopieer/herstel/ontzip zelf de databasebackup met het daarvoor benodigde + gereedschap. - - Ontgrendel vervolgens de teruggezette database - niet met de -N-optie, - maar met -F (fixup): - + Ontgrendel vervolgens de teruggezette database niet met de + -N-optie, maar met -F (fixup):
nbackup -F <database>
+ Ook hier weer kun je eventueel een alias gebruiken in plaats van een bestandsnaam, + en kan -Z toegevoegd worden voor versie-info. Andere opties hebben + geen zin. - Waarom zijn er twee ontgrendelopties, -N en -F? - - -N zorgt er eerst voor dat eventuele - wijzigingen, gemaakt sinds het vergrendelen door - -L, worden verwerkt in het hoofdbestand van - de database. Vervolgens wordt de database weer volledig vrijgegeven - voor lezen en schrijven, en het tijdelijke bestand wordt - gewist. + -N zorgt er eerst voor dat eventuele wijzigingen, gemaakt + sinds het vergrendelen door -L, worden verwerkt in het hoofdbestand + van de database. Vervolgens wordt de database weer volledig vrijgegeven voor lezen en + schrijven, en het tijdelijke bestand wordt gewist. - - -F zet alleen maar de statusvlag van de - zelf teruggezette database weer op normaal. + -F zet alleen maar de statusvlag van de zelf teruggezette + database weer op normaal. - Je gebruikt dus: - - -N na het zelf - maken van een kopie/backup (om de eerder - gegeven -L weer ongedaan te maken); + -N na het zelf maken van een + kopie/backup (om de eerder gegeven -L weer ongedaan te + maken); - - -F na het zelf - terugzetten van een dergelijke backup. + -F na het zelf terugzetten van een + dergelijke backup. - - Het is een beetje ongelukkig dat de laatste optie - -F (van Fixup) is genoemd. Er wordt immers - niets gerepareerd; de database wordt alleen - ontgrendeld. De optie -N - (uNlock, ontgrendel) daarentegen voert niet alleen een ontgrendeling - uit, maar maakt ook de database weer in orde - (fikst de database) door de tussentijdse mutaties - te integreren. Maar hier zullen we mee moeten leven. + Het is een beetje ongelukkig dat de laatste optie -F (van + Fixup) is genoemd. Er wordt immers niets gerepareerd; de database wordt alleen + ontgrendeld. De optie -N (uNlock, ontgrendel) + daarentegen voert niet alleen een ontgrendeling uit, maar maakt ook de database weer in orde + (fikst de database) door de tussentijdse mutaties te integreren. Maar + hier zullen we mee moeten leven. Overigens: je zou + -F op kunnen vatten als Flag-only (alleen + vlag).
-
Onder de motorkap - - NB: Deze paragraaf bevat geen noodzakelijke kennis, maar biedt wat - extra informatie die je inzicht in de verschillende schakelopties kan - verdiepen. - + NB: Deze paragraaf bevat geen noodzakelijke kennis, maar biedt wat extra informatie die + je inzicht in de verschillende schakelopties kan verdiepen. - - nbackup -L doet het - volgende: - + nbackup -L doet het volgende: Verbinden met de database; - Transactie starten; - - ALTER DATABASE BEGIN BACKUP aanroepen (de werking hiervan is - besproken in de extra - informatie bij nbackup -B); + ALTER DATABASE BEGIN BACKUP aanroepen (de werking hiervan is besproken in de extra informatie bij nbackup -B); - - Transactie bekrachtigen met - COMMIT; + Transactie bekrachtigen met COMMIT; - Verbinding met database verbreken. - - nbackup -N doorloopt - dezelfde stappen, maar uiteraard met ...END - BACKUP in stap 3. - - nbackup -F werkt als - volgt: - + nbackup -N doorloopt dezelfde stappen, maar + uiteraard met ...END BACKUP in stap 3. + nbackup -F werkt als volgt: Het teruggezette databasebestand wordt geopend; - - In het bestand wordt de toestandsvlag gewijzigd van - vergrendeld (nbak_state_stalled) naar normaal + In het bestand wordt de toestandsvlag gewijzigd van vergrendeld + (nbak_state_stalled) naar normaal (nbak_state_normal); - Het bestand wordt weer gesloten. - - nbackup -F werkt puur op bestandsniveau en kan dus zelfs worden - uitgevoerd zonder dat er een Firebirdserver draait. Eventuele bij de - aanroep meegegeven -U- of - -P-parameters worden dan ook compleet - genegeerd. + nbackup -F werkt puur op bestandsniveau en kan dus ook worden + uitgevoerd zonder dat er een Firebirdserver draait. Eventuele via -U, + -P en/of -FE aangeleverde inloggegevens worden + dan ook genegeerd, net als bij nbackup -R.
+
+ Databases op kale apparaten vergrendelen + Zoals al besproken in Databases + op kale apparaten backuppen kunnen er problemen ontstaan als een + deltabestand moet worden gemaakt voor een database op een kaal apparaat. Ook bij het + vergrendelen geldt daarom vanaf Firebird 2.1 dat nbackup weigert te werken met databases op + kale apparaten, tenzij vooraf een expliciete locatie voor het deltabestand is ingesteld. Zie + hiervoor Het deltabestand + instellen, even verderop. + Bij het vergrendelen en zelf kopiëren van een kaal apparaat doet zich ook nog het + volgende probleem voor: je weet niet hoe groot de database is! Misschien is het kale apparaat + 10 GB, maar neemt de database daarop nog maar 200 MB in. Om te voorkomen dat je voor de + zekerheid het hele apparaat zou moeten kopiëren, met alle tijd- en ruimteverspilling van dien, + is in Firebird 2.1 een nieuwe schakeloptie toegevoegd: -S. Deze optie + is alleen geldig in combinatie met -L en zorgt ervoor dat nbackup na + het vergrendelen de omvang van de database naar de standaarduitvoer schrijft. De omvang wordt + opgegeven in databasepagina's en moet dus met de paginagrootte van de database worden + vermenigvuldigd om de te kopiëren hoeveelheid bytes te verkrijgen. Bij gebruik van het + kopieerprogramma dd kun je ook als (i)bs de + paginagrootte opgeven en als count de uitvoer van + nbackup -L -S. +
-
Het deltabestand instellen - - Het deltabestand wordt standaard aangelegd in dezelfde map als de - database zelf. De bestandsnaam is ook gelijk aan die van de database, maar - met .delta erachter. Normaal - gesproken is er geen reden om dit te veranderen, maar zo nodig kan het wel - – alleen niet met nbackup zelf. Maak verbinding - met de database vanuit een programma waarin je je eigen SQL-opdrachten + Het deltabestand wordt standaard aangelegd in dezelfde map als de database. De + bestandsnaam is ook dezelfde, maar dan met .delta + erachter. Normaal gesproken is dit geen probleem, maar soms is het wenselijk of zelfs + noodzakelijk om de locatie te veranderen, bijvoorbeeld als de database zich op een kaal apparaat + bevindt. Het instellen van de locatie kan niet met nbackup zelf, maar moet met een SQL-opdracht + gebeuren. + Maak verbinding met de database vanuit een programma waarin je je eigen SQL-opdrachten kunt invoeren en geef het commando: -
alter database add difference file 'pad-en-bestandsnaam'
- - De aangepaste delta-instelling blijft behouden in de database; ze - wordt opgeslagen in de systeemtabel RDB$FILES. Met de - onderstaande opdracht keer je desgewenst terug naar de - standaardroutine: - + De aangepaste delta-instelling blijft behouden in de database; ze wordt opgeslagen in de + systeemtabel RDB$FILES. Met de onderstaande opdracht keer je desgewenst + terug naar de standaardroutine:
alter database drop difference file
- + Je kunt ook meteen bij het maken van een nieuwe database een aangepaste locatie voor het + deltabestand opgeven: +
+ create database 'pad-en-dbnaam' difference file 'pad-en-deltanaam' +
Opmerkingen - - Als je bij ADD DIFFERENCE FILE een kale - bestandsnaam zonder padinfo opgeeft, zal de delta doorgaans - niet aangelegd worden in dezelfde map als de - database, maar in de huidige directory gezien vanuit de server. - Onder Windows kan dit bijv. de systeemdirectory zijn. Hetzelfde - geldt voor relatieve paden. + Als je bij [ADD] DIFFERENCE FILE een kale bestandsnaam zonder + padinfo opgeeft, zal de delta doorgaans niet aangelegd worden in + dezelfde map als de database, maar in de huidige directory zoals gezien vanuit de server. + Onder Windows kan dit bijv. de systeemdirectory zijn. Hetzelfde geldt voor relatieve + paden. - - Het volledige directorypad moet al bestaan. Firebird probeert - geen ontbrekende mappen aan te leggen. + Het volledige directorypad moet al bestaan. Firebird probeert geen ontbrekende + mappen aan te leggen. - - Als je de ene aangepaste delta-instelling wilt vervangen door - de andere, moet je eerst de bestaande verwijderen - (DROP) en vervolgens de nieuwe toevoegen - (ADD). + Als je de ene aangepaste delta-instelling wilt vervangen door de andere, moet je + eerst de bestaande verwijderen (DROP) en vervolgens de nieuwe + toevoegen (ADD).
- Documenthistorie - - De exacte geschiedenis van dit document is na te gaan in de module - manual van het Firebird - CVS-archief; zie http://sourceforge.net/cvs/?group_id=9028 - + De exacte geschiedenis van dit document is na te gaan in de module manual van het Firebird CVS-archief; zie http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs-nl/nbackup-nl.xml?view=log 0.1 - 21 okt 2005 - PV - - Eerste editie, gelijktijdig uitgebracht in het Nederlands en - het Engels. + Eerste editie, gelijktijdig uitgebracht in het Nederlands en het Engels. - 1.0 - 1 dec 2006 - PV - Vernieuwde Engelse editie. - 1.0-nl - 5 jan 2007 - PV - - Nederlandse editie weer gelijkgetrokken met de Engelse - d.m.v. de volgende wijzigingen: - - Bèta-verwijzing verwijderd uit editie-info. - Waarschuwing tegen interactief opgeven van backupbestandsnamen bij - nbackup -R aangepast. - - C:\Databases overal in de voorbeelden - door C:\Data vervangen, zodat de regels niet - doorlopen tot buiten de afwijkend gekleurde screen-gebieden in de PDF's. Om + Nederlandse editie weer gelijkgetrokken met de Engelse d.m.v. de volgende + wijzigingen: + Bèta-verwijzing verwijderd uit editie-info. Waarschuwing tegen + interactief opgeven van backupbestandsnamen bij nbackup -R aangepast. + C:\Databases overal in de voorbeelden door + C:\Data vervangen, zodat de regels niet doorlopen tot buiten de + afwijkend gekleurde screen-gebieden in de PDF's. Om dezelfde reden tweemaal gebruiker ingekort tot gebr. - - Sectie Het deltabestand instellen - toegevoegd, en sectie Verder lezen? - dienovereenkomstig gewijzigd. - - Tevens hier en daar formuleringen en/of spelling + Sectie Het deltabestand instellen toegevoegd, en sectie + Verder lezen? dienovereenkomstig gewijzigd. + Tevens hier en daar formuleringen en/of spelling aangepast. + + + + 1.1-nl +   +   + + Een Nederlandse editie 1.1 is er nooit geweest. De volgende editie heet 1.2-nl en + komt overeen met de Engelse editie 1.2. + + + + 1.2-nl + 19 sep 2011 + PV + + Opmaak van de brontekst: maximale regellengte op 100 gezet, zonder + witregels. + Alle secties en subsecties hebben nu een id. + Inleiding: eerste zin aangepast. + Kenmerken van nbackup — een overzicht: Laatste para voor + eerste subsectie bewerkt: vermeld dat alleen SYSDBA, eigenaar en + soms OS-admins een backup kunnen maken. + Kenmerken van nbackup — een overzicht :: Beperkingen van + nbackup: Voormalig laatste listitem bewerkt: toegang via Services Manager + vermeld. Listitem toegevoegd inz. rechtstreekse bestandstoegang. Laatste para + verwijderd. + Functies en parameters: Nieuwe sectie. + Backups maken en terugzetten: Laatste zin van eerste alinea + licht gewijzigd. Waarschuwing toegevoegd inz. risico's met nbackup 2.0.0–2.0.3 onder + zware belasting, en de invloed van rechtstreekse I/O bij grote databases onder + Posix. + Backups maken en terugzetten :: Volledige backups :: Een volledige + backup maken: Listitem over -U en + -P sterk uitgebreid en gecorrigeerd. Listitems toegevoegd over + -FE-optie (nieuw in 2.5), -T-optie (nieuw + in 2.1) en -D-optie (nieuw in 2.5, backport naar 2.1.4). In + listitem dat begint met De verschillende parameters staat tussen de + haakjes nu: (-B, -U enz.), omdat er vele + parameters zijn bijgekomen. + Backups maken en terugzetten :: Volledige backups :: Een volledige + backup terugzetten: Parameters -U en + -P verwijderd uit specificatie. Listitem toegevoegd over alias. + Foutieve bewering gecorrigeerd dat nbackup een bestaande database overschrijft als er + geen actieve verbindingen zijn. Cursieve tekst over falen interactief terugzetten + gewijzigd en reparatie in 2.0.1 vermeld. Listitem toegevoegd over niet-noodzaak + draaiende server en negeren inloggegevens. + Backups maken en terugzetten :: Aanvullende backups: + Waarschuwing ingevoegd dat deze voorziening totaal gebroken is in 2.1, en weer hersteld + in 2.1.1. + Backups maken en terugzetten :: Aanvullende backups :: Aanvullende + backups terugzetten: Parameters -U en + -P verwijderd uit formele syntaxis en 1e listitem. + Backups maken en terugzetten :: Databases op kale apparaten + backuppen: Nieuwe sectie. + Backups maken en terugzetten :: Databasetriggers onderdrukken (Firebird + 2.1+): Nieuwe sectie. + Backups maken en terugzetten :: Rechtstreekse I/O (Firebird + 2.1.4+): Nieuwe sectie. + Backups maken en terugzetten :: Informatieve opties (Firebird + 2.5+): Nieuwe sectie. + Backups maken en terugzetten :: Backups op verre machines (Firebird + 2.5+): Nieuwe sectie. + Vergrendelen en ontgrendelen: Laatste zin van tweede alinea + licht gewijzigd. + Vergrendelen en ontgrendelen :: Database vergrendelen en zelf + backuppen: Opmerkingen toegevoegd (para + itemizedlist). + Vergrendelen en ontgrendelen :: Terugzetten van een na nbackup + -L gemaakte backup: Info over gebruik alias en + -Z toegevoegd aan stap 2 van procedure. Zin aan Noot toegevoegd + over opvatten -F als Flag-only (alleen + vlag). + Vergrendelen en ontgrendelen :: Databases op kale apparaten + vergrendelen: Nieuwe sectie. + Vergrendelen en ontgrendelen :: Onder de motorkap: Noot aangepast. + Het deltabestand instellen: 1e alinea deels herschreven, + met o.a. verwijzing naar databases op kale apparaten. Laatste zin afgesplitst; is nu + zelfstandige alinea. Info toegevoegd (para + programlisting) over opgeven delta bij + CREATE DATABASE. 1e listitem in Opmerkingen: + ADD -> [ADD]. + Documenthistorie: Ulink naar CVS gewijzigd (zowel tekst als + url); wijst nu rechtstreeks naar document. + Licentie: Eindjaar auteursrechtvermelding nu 2011. - - + Licentie - - De inhoud van deze Documentatie valt onder de Public - Documentation License, Version 1.0 (hierna te noemen de - Licentie); gebruik van deze Documentatie is alleen - toegestaan als voldaan wordt aan de voorwaarden van de Licentie. + De inhoud van deze Documentatie valt onder de Public Documentation License, + Version 1.0 (hierna te noemen de Licentie); gebruik van deze + Documentatie is alleen toegestaan als voldaan wordt aan de voorwaarden van de Licentie. Exemplaren van de Licentie zijn verkrijgbaar op http://www.firebirdsql.org/pdfmanual/pdl.pdf (PDF) en http://www.firebirdsql.org/manual/pdl.html (HTML). - De Oorspronkelijke Documentatie is getiteld Firebirds nbackup-tool. - - De Oorspronkelijke Schrijver van de Oorspronkelijke Documentatie is: - Paul Vinkenoog. - - Copyright (C) 2005–2007. Alle rechten voorbehouden. Contactadres - Oorspronkelijke Schrijver: paul (op) vinkenoog (punt) nl. + De Oorspronkelijke Schrijver van de Oorspronkelijke Documentatie is: Paul + Vinkenoog. + Copyright (C) 2005–2011. Alle rechten voorbehouden. Contactadres Oorspronkelijke + Schrijver: <voornaam> op <achternaam> punt nl. -
\ No newline at end of file + diff --git a/src/docs/firebirddocs/nbackup.xml b/src/docs/firebirddocs/nbackup.xml index 7595bb0f..c2ecf9fd 100644 --- a/src/docs/firebirddocs/nbackup.xml +++ b/src/docs/firebirddocs/nbackup.xml @@ -1,876 +1,1127 @@
Firebird's nbackup tool - Paul - Vinkenoog - - 5 May 2008 – Document version 1.1 + 19 Sep 2011 — Document version 1.2 -
Introduction - - nbackup is a new backup utility that comes - with Firebird 2.0. It offers possibilities not present in - gbak - Firebird's pre-existing backup tool - but - doesn't replace the latter. Both programmes have their strengths and - weaknesses; they will likely coexist for some time to come. + Nbackup is a backup utility included in the Firebird download + packages since version 2.0. It offers possibilities not present in gbak – + Firebird's pre-existing backup tool – but doesn't replace the latter. Both programmes have their + strengths and weaknesses; they will likely coexist for some time to come.
-
- nbackup features - an overview - - With nbackup, you can perform two different groups of tasks: - + Nbackup features – an overview + With nbackup, you can perform two different kinds of tasks: - Making and restoring of both full and - incremental backups. An incremental - backup only contains the mutations since some specific + Making and restoring of both full and incremental backups. An + incremental backup only contains the mutations since some specific previous backup. - - Locking the main database file so you can subsequently back it - up yourself with copying or backup tools of your own choice. In this - mode, nbackup doesn't back up anything; it just creates the conditions - under which you can safely make the backup yourself. There's a - provision for restoring here, too. + Locking the main database file so you can subsequently back it up yourself with + copying or backup tools of your own choice. In this mode, nbackup doesn't back up anything; + it just creates the conditions under which you can safely make the backup yourself. There's + a provision for restoring here, too. - - Both modes can operate on an active database, without hindering - connected users. The backup created will always reflect the state of the - database at the beginning of the operation. In these - respects nbackup doesn't differ from gbak. - + Both modes can operate on an active database, without hindering connected users. The + backup created will always reflect the state of the database at the beginning of the + operation. Furthermore, only SYSDBA and the database owner (and + sometimes OS admins) can make a backup, but every user can restore a backup to a new database. + In these respects nbackup doesn't differ from gbak.
Advantages of nbackup - - Both modes: high speed (as high as - hardware and OS will allow), because nbackup doesn't look at the - actual data. In backup mode the contents are written more or less - blindly to the backup file. + Both modes: high speed (as high as hardware and OS will allow), + because nbackup doesn't look at the actual data. In backup mode the contents are written + more or less blindly to the backup file. - - Backup/restore mode: time and disk space - savings, because you don't need to make a full backup every time. - This can make a huge difference with databases in the gigabyte - range. + Backup/restore mode: time and disk space savings, because you + don't need to make a full backup every time. This can make a huge difference with + databases in the gigabyte range. - - Lock/unlock mode: total freedom in your - choice of backup, copy, and/or compression tools. + Lock/unlock mode: total freedom in your choice of backup, copy, + and/or compression tools.
-
Limitations of nbackup - - nbackup will not sweep and compact your database the way gbak - does. + Nbackup will not sweep and compact your database the way gbak does. - - You can't change the database owner with an nbackup - backup/restore cycle, like you can with gbak. + You can't change the database owner with an nbackup backup/restore cycle, like you + can with gbak. - - nbackup can't make transportable - backups, that is: backups you can restore on an - incompatible platform or under another server version. + Nbackup can't make transportable backups, that is: backups + you can restore on an incompatible platform or under another server version. - - At this moment, nbackup should not be used on multi-file - databases. + At this moment, nbackup should not be used on multi-file databases. - - nbackup can only back up local databases. + Nbackup itself can only back up local databases. However, in Firebird 2.5 and above + its backup and restore tasks can also be performed remotely through the Services + Manager. + + + Except when the Services Manager is used (in Firebird 2.5+) backing up with nbackup + requires direct access to the database file. With gbak this is not the case. - - We'll discuss nbackup's various functions extensively in the - following sections.
- +
+ Functions and parameters + The following table gives an overview of nbackup's parameters. If the field + Added is empty, the parameter has existed since nbackup's introduction in + Firebird 2.0. + + Nbackup parameters + + + + + + + Parameter + Function + Added + + + + + -B n <database> + [<filename>] + Make level-n backup of database to file + + + + -R <database> + [<filename> ...] + Restore database from backup file(s) + + + + -L <database> + Lock database + + + + -N <database> + Unlock locked database + + + + -F <database> + Unlock self-restored database + + + + -S + Give size in database pages (with -L) + 2.1 + + + -T + Suppress database triggers (with -B, -L, -N) + 2.1 + + + -D on|off + Direct I/O on/off (with -B) + 2.1.4 + + + -U <username> + Supply user name (with -B, -L, -N) + + + + -P <password> + Supply password (with -B, -L, -N) + + + + -FE <filename> + Fetch password from file (with -B, -L, -N) + 2.5 + + + -Z + Version info (by itself or with -B, -R, -L, -N, -F) + 2.5 + + + -? + Help (switches off all other parameters) + 2.5 + + + +
+ Depending on the chosen main function (-B, + -R, -L, -N or + -F), nbackup may require different types of access to the database: a + Firebird server connection, direct file access, or both. The following table gives the + details: + + Access required + + + + + + + Parameter + Function + Access + + + + + -B + Backup + server + file + + + -R + Restore + file + + + -L + Lock + server + + + -N + Unlock (undo -L) + server + + + -F + Unlock after self-restore + file + + + +
+ Where server access is required (with -B, -L + and -N), the user must either provide a Firebird username and password + (with -U and -P/-FE or + through the environment variables ISC_USER and ISC_PASSWORD), or + be admitted by the server on other grounds (e.g. as root under Posix or by trusted + authentication under Windows). + Where filesystem access is required (with -B, + -R and -F), the user must have sufficient read + and/or write privileges to the database file. + Where filesystem access is required exclusively (with -R and + -F), the user need not have a Firebird login and a running Firebird + server need not be present. + Please notice: The above table and text concern access to the + database. Access to the backup file is – obviously – always on the + filesystem level. +
Making and restoring backups - - To begin with: nbackup.exe is located in the - bin subdirectory of your Firebird - folder. Typical locations are e.g. C:\Program - Files\Firebird\Firebird_2_0\bin (Windows) or /opt/firebird/bin (Linux). Just like most of - the tools that come with Firebird, nbackup has no graphical interface; you - launch it from the command prompt (or from within a batch file or - application). - + To begin with: nbackup.exe is located in the bin subdirectory of your Firebird folder. Typical locations are + e.g. C:\Program Files\Firebird\Firebird_2_0\bin (Windows) + or /opt/firebird/bin (Linux). Just like most of the tools + that come with Firebird, nbackup has no graphical interface; you launch it from the command + prompt or call it from within a batch file or application. - Under heavy-load circumstances in some environments, nbackup 2.0.3 - and below may cause problems that will lead to deadlocks or even - corrupted databases. While these problems aren't common, they are - serious enough to warrant upgrading to Firebird 2.0.4 or higher if you - want to use nbackup comfortably. + Under heavy-load circumstances in some environments, nbackup 2.0.3 and below may cause + problems that will lead to deadlocks or even corrupted databases. While these problems aren't + common, they are serious enough to warrant upgrading to Firebird 2.0.4 or higher if you want + to use nbackup comfortably. If it concerns large databases under Posix, the use of direct I/O + may also make a difference. More about this in the section Direct I/O. + -
Full backups - -
+
Making full backups - To make a full database backup, the command syntax is: -
nbackup [-U <user> -P <password>] -B 0 <database> [<backupfile>]
- For instance: -
C:\Data> nbackup -B 0 inventory.fdb inventory_1-Mar-2006.nbk
- Comments: - - The parameter -B stands for backup - (gee!). The backup level 0 indicates a full - backup. Backup levels greater than 0 are used for incremental - backups; we'll discuss those later on. + The parameter -B stands for backup (gee!). The + backup level 0 indicates a full backup. Backup levels greater + than 0 are used for incremental backups; we'll discuss those later on. - - Instead of a database filename you may also specify an - alias. + Instead of a database filename you may also use an alias. - - Instead of a backup filename you may also specify - stdout. This will send the backup to - standard output, from where you can redirect it to e.g. a tape - archiver or a compression tool. + Instead of a backup filename you may also specify stdout. + This will send the backup to standard output, from where you can redirect it to e.g. a + tape archiver or a compression tool. - - - The -U (user) and - -P (password) parameters may be - omitted: - + + The -U (user) and -P (password) + parameters may be omitted if at least one of the following condtions is met: - if you're logged on as superuser (root, Administrator...), or + The environment variables ISC_USER and + ISC_PASSWORD have been set, either to SYSDBA or + to the owner of the database. + + + You are logged on as root on a Posix system. This makes you + SYSDBA by default. + + + Under Windows: Trusted authentication is enabled in + firebird.conf, and you are logged on to the Windows account + that owns the database. This is possible in Firebird 2.1 and above. - - if the environment variables ISC_USER and - ISC_PASSWORD are set. + Under Windows: Trusted authentication is enabled in + firebird.conf, and you are logged on as a Windows + administrator. In Firebird 2.1, this automatically gives you + SYSDBA rights. In Firebird 2.5 and above, there is the + additional condition that AUTO ADMIN MAPPING has been set in + the database. - - For clarity and brevity, these parameters are not used in - the examples. + For clarity and brevity, the -U and + -P parameters are not used in the examples. - - The different parameters (-B, - -U and -P) may occur - in any order. Of course each parameter should be immediately - followed by its own argument(s). In the case of - -B there are three of them: backup level, - database, and backup file - in that order! + Starting with Firebird 2.5, instead of -P + <password> you may also use -FE + <filename>. This will cause nbackup to fetch the + password from the given file. With -FE, the password itself + doesn't appear in the command and will thus be better shielded against people who might + otherwise pick it up via the command history, the w command on Unix + or from a script or batchfile. + + + In Firebird 2.1 and up, the firing of database triggers can be prevented by + specifying the -T option. For more information, see Suppressing database + triggers. + + + Starting with Firebird 2.1.4, it is possible to force direct I/O on or off by + specifying -D on or + -D off. For details and background see + Direct I/O, + elsewhere in this manual. + + + The different parameters (-B, -U + etc.) may occur in any order. Of course each parameter should be immediately followed by + its own argument(s). In the case of -B there are three of them: + backup level, database, and backup file - in that order! - If the -B parameter comes last, you - may leave out the name of the backup file. In - that case nbackup will compose a filename based on the database - name, the backup level, and the current date and time. This can - lead to a name clash (and a failed backup) if two backup commands - of the same level are issued in the same minute. + may leave out the name of the backup file. In that case nbackup + will compose a filename based on the database name, the backup level, and the current + date and time. This can lead to a name clash (and a failed backup) if two backup + commands of the same level are issued in the same minute. - - Do not use nbackup for multi-file - databases. This can lead to corruption and loss of data, despite the - fact that nbackup will not complain about such a command. + Do not use nbackup for multi-file databases. This can lead to + corruption and loss of data, despite the fact that nbackup will not complain about such a + command. -
A word on the inner workings - - Note: What follows here is not necessary knowledge to use - nbackup. It just gives a rough (and incomplete) image of what - happens under the hood during execution of nbackup - -B: - + Note: What follows here is not necessary knowledge to use nbackup. It just gives a + rough (and incomplete) impression of what happens under the hood during execution of + nbackup -B: - First of all, the main database file is locked by changing - an internal state flag. From this moment on, any and all - mutations in the database are written to a temporary file - the - difference file or delta file. + First of all, the main database file is locked by changing an internal state + flag. From this moment on, any and all mutations in the database are written to a + temporary file - the difference file or delta file. - - Then the actual backup is made. This isn't a straight file - copy; restoring must be done by nbackup as well. + Then the actual backup is made. This isn't a straight file copy; restoring must + be done by nbackup as well. - - Upon completion of the backup, the contents of the delta - file are integrated with the main database file. After that, the - database is unlocked (flag goes back to normal) - and the delta is removed. + Upon completion of the backup, the contents of the delta file are integrated + with the main database file. After that, the database is unlocked (flag goes back to + normal) and the delta is removed. - - The functionality of steps 1 and 3 is provided by two new SQL - statements: ALTER DATABASE BEGIN BACKUP and - ALTER DATABASE END BACKUP. Contrary to what the - names suggest, these statements do not take - care of making the actual backup; rather, they create the conditions - under which the main database file can be safely backed up. And to - be clear: you don't need to issue these commands yourself; nbackup - will do that for you, at the right moments. + The functionality of steps 1 and 3 is provided by two new SQL statements: + ALTER DATABASE BEGIN BACKUP and ALTER DATABASE END + BACKUP. Contrary to what the names suggest, these statements do + not take care of making the actual backup; rather, they create the + conditions under which the main database file can be safely backed up. And to be clear: + you don't need to issue these commands yourself; nbackup will do that for you, at the + right moments.
- -
+
Restoring a full backup - A full backup is restored as follows: -
- nbackup [-U <user> -P <password>] -R <database> [<backupfile>] + nbackup -R <database> [<backupfile>]
- For instance: -
C:\Data> nbackup -R inventory.fdb inventory_1-Mar-2006.nbk
- Comments: - You don't specify a level for a restore. - - When restoring, the -R parameter - must come last, for reasons that will become - clear later. + When restoring, the -R parameter must + come last, for reasons that will become clear later. + + + Instead of a database filename you may also use an alias. - - If the specified database file already exists, the restore - fails and you get an error message. + If the specified database file already exists, the restore fails and you get an + error message. - - Here too, you may omit the name of the backup file. If you - do, nbackup will prompt you for it. - - - Bug - - In Firebird 2.0.0, this interactive restore - feature is broken, leaving you with an error message and a - failed restore. Fixed in 2.0.1. - + Here too, you may omit the name of the backup file. If you do, nbackup will prompt + you for it. (Attention! In Firebird 2.0 this interactive + restore feature is broken, leaving you with an error message and a failed + restore. Fixed in 2.0.1.) + + + Restoring works purely on the filesystem level and can even be done without a + Firebird server running. Any credentials supplied via the -U and + -P parameters are ignored. The same goes for passwords read from + a file. However, nbackup does try to read the password from the + file if the -FE parameter is present, and if an error occurs, the + entire operation is abandoned.
-
Incremental backups - - The incremental backup facility is entirely broken in Firebird - 2.1. A fix is foreseen for version 2.1.1. + The incremental backup facility was entirely broken in Firebird 2.1, and fixed again + in 2.1.1. + - -
+
Making incremental backups - - To make an incremental (differential) backup we - specify a backup level greater than 0. An incremental backup of level - N always contains the database mutations - since the most recent level N-1 + To make an incremental (differential) backup we specify a backup level + greater than 0. An incremental backup of level N always contains + the database mutations since the most recent level N-1 backup. - Examples: - - One day after the full backup (level 0), you make one with level - 1: - + One day after the full backup (level 0), you make one with level 1:
C:\Data> nbackup -B 1 inventory.fdb inventory_2-Mar-2006.nbk
- - This backup will only contain the mutations of the last - day. - + This backup will only contain the mutations of the last day. One day later again, you make another one with level 1: -
C:\Data> nbackup -B 1 inventory.fdb inventory_3-Mar-2006.nbk
- - This one contains the mutations of the last - two days, since the full backup, not only those - since the previous level-1 backup. - + This one contains the mutations of the last two days, since the + full backup, not only those since the previous level-1 backup. A couple of hours on we go for a level-2 backup: -
C:\Data> nbackup -B 2 inventory.fdb inventory_3-Mar-2006_2.nbk
- - This youngest backup only contains the mutations since the most - recent level-1 backup, that is: of the last few hours. - + This youngest backup only contains the mutations since the most recent level-1 backup, + that is: of the last few hours. - All the comments that have been - made about full backups also apply to incremental backups. + All the comments that have been made + about full backups also apply to incremental backups. - Again: do not use nbackup for multi-file databases.
- -
+
Restoring incremental backups - - When restoring incremental backups you must specify the entire - chain of backup files, from level 0 through the one you wish to - restore. The database is always built up from the ground, step by - step. (It is this stepwise adding until the database is restored that - gave rise to the term incremental backup.) - + When restoring incremental backups you must specify the entire chain of backup files, + from level 0 through the one you wish to restore. The database is always built up from the + ground, step by step. (It is this stepwise adding until the database is restored that gave + rise to the term incremental backup.) The formal syntax is: -
- nbackup [-U <user> -P <password>] - -R <database> [<backup0> [<backup1> [...] ] ] + nbackup -R <database> [<backup0> [<backup1> [...] ] ]
- - So restoring the level-2 backup from the previous example goes - as follows: - + So restoring the level-2 backup from the previous example goes as follows:
C:\Data> nbackup -R inventory.fdb inventory_1-Mar-2006.nbk inventory_3-Mar-2006.nbk inventory_3-Mar-2006_2.nbk
- - Of course the line has been split here for layout reasons only - - in reality you type the entire command and only hit - Enter at the end. - - Comments (in addition to the comments with restoring a full - backup): - + Of course the line has been split here for layout reasons only - in reality you type + the entire command and only hit Enter at the end. + Comments (in addition to the comments with + restoring a full backup): - Because it is not known beforehand how many filenames will - follow the -R switch (as we don't specify a - level when restoring), nbackup considers all arguments after the - -R to be names of backup files. It is for - this reason that no other parameter (-U or - -P) may follow the list of - filenames. + Because it is not known beforehand how many filenames will follow the + -R switch (as we don't specify a level when restoring), nbackup + considers all arguments after the -R to be names of backup files. + It is for this reason that no other parameter may follow the list of filenames. - - There is no formal limit to the number of backup levels, but - in practice it will rarely make sense to go beyond 3 or 4. + There is no formal limit to the number of backup levels, but in practice it will + rarely make sense to go beyond 3 or 4. - -
+
Non-connecting links - - What happens if you accidentally leave out a file, or specify - a series of files that don't all belong together? You could imagine - that you specify inventory_2-Mar-2006.nbk by - mistake instead of inventory_3-Mar-2006.nbk in - the above example. Both are level-1 backup files, so in both cases - we get a nice 0, 1, 2 level series. But our level-2 - file is incremental to the level-1 backup of 3 March, not to the one - of 2 March. - - Fortunately such a mistake can never lead to an incorrectly - restored database. Each backup file has its own unique ID. - Furthermore, each backup file of level 1 or above contains the ID of - the backup on which it is based. When restoring, nbackup checks - these IDs; if somewhere in the chain the links don't connect, the - operation is cancelled and you get an error message. + What happens if you accidentally leave out a file, or specify a series of files that + don't all belong together? You could imagine that you specify + inventory_2-Mar-2006.nbk by mistake instead of + inventory_3-Mar-2006.nbk in the above example. Both are level-1 + backup files, so in both cases we get a nice 0, 1, 2 level series. But our + level-2 file is incremental to the level-1 backup of 3 March, not to the one of 2 + March. + Fortunately such a mistake can never lead to an incorrectly restored database. Each + backup file has its own unique ID. Furthermore, each backup file of level 1 or above + contains the ID of the backup on which it is based. When restoring, nbackup checks these + IDs; if somewhere in the chain the links don't connect, the operation is cancelled and you + get an error message.
- +
+ Backing up raw-device databases + Firebird databases need not be files; they can also be placed on a so-called + raw device, for instance a disk partition without a file system. The + question where the delta has to be placed in + such cases was at first overlooked during the development of + nbackup. On Posix systems, if the database was located at e.g. + /dev/hdb5, it could happen that the delta was created + as /dev/hdb5.delta. In light of the nature and purpose of the + /dev directory and its often limited available space, this is + undesirable. + As of Firebird 2.1, nbackup refuses to operate on raw-device databases unless an + explicit location for the delta file has been set. The way to do this is discussed in Setting the delta file, later on in + this manual. +
Suppressing database triggers (Firebird 2.1+) - - Firebird 2.1 introduced the concept of database - triggers. To keep these database triggers from firing during - an nbackup run, a new switch was added to nbackup: - -T. It can only be used by the database owner and - SYSDBA. Notice that the corresponding switches in - gbak and isql are - called -nodbtriggers (we love diversity). + Firebird 2.1 introduced the concept of database triggers. Certain + types of these triggers can fire upon making or breaking a database connection. As part of the + backup process, nbackup opens a regular connection to the database (in some versions even more + than once). To prevent database triggers from firing inadvertently, the new + -T switch can be used. Notice that the corresponding switches in + gbak and isql are called + -nodbtriggers (we love diversity, here at Firebird). +
+
+ Direct I/O (Firebird 2.1.4+) + Originally, nbackup used direct I/O only when making a backup under Windows NT (and + successors like 2000, 2003 etc.) On all other OS'es, direct I/O was off. This caused problems + on some Linux systems, so in versions 2.0.6 and 2.1.3 direct I/O was switched on under Linux + as well. However, this turned out to be problematic for certain other Linux configurations. In + 2.1.4 and 2.5 the original behaviour was restored, but this time as a default that was + overridable by a newly added parameter: -D. Its use is as + follows: +
+ nbackup -B 0 cups.fdb cups.nbk -D on -- direct I/O on +nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off +
+ Just like the option letters themselves, the arguments ON and OFF are + case-insensitive. + Direct I/O is only applied when making a backup, not during a restore. Under Windows it + is realized by setting FILE_FLAG_NO_BUFFERING. On other systems, + O_DIRECT and POSIX_FADV_NOREUSE are used. The latter + two are sometimes unavailable; in such cases, they are (or one of them is) silently left out. + Even if the user specified -D on explicitly, + this doesn't lead to a warning or error message. +
+
+ Informational options (Firebird 2.5+) + Apart from the already mentioned -FE and + -D parameters, Firebird 2.5 also saw the introduction of the following + two: + + + -Z + + Shows single-line version information. This option can be used independently, but + also in combination with other parameters, such as -B, + -R, -L etc. + + + + -? + + Shows a summary of nbackup's usage and command-line parameters. Attention: If this + option is present, all the other parameters are ignored! + + + +
+
+ Backups on remote machines (Firebird 2.5+) + Nbackup itself only operates on local databases. But in Firebird 2.5 and up, + nbackup-type backups and restores can also be performed remotely via the Services Manager. For + this, the program fbsvcmgr.exe on the local machine is used; it is + located in the same folder as nbackup.exe and the other Firebird + command-line tools. The first argument is always + hostname:service_mgr, with hostname + being the name of the remote server. Other available parameters are: +
+ -user username +-password password +-action_nbak +-action_nrest +-nbk_level n +-dbname database +-nbk_file filename +-nbk_no_triggers +-nbk_direct on|off +
+ Making a full backup on the remote machine frodo goes like this: +
+ fbsvcmgr frodo:service_mgr -user sysdba -password masterke + -action_nbak -nbk_level 0 + -dbname C:\databases\countries.fdb -nbk_file C:\databases\countries.nbk +
+ And a subsequent incremental backup: +
+ fbsvcmgr frodo:service_mgr -user sysdba -password masterke + -action_nbak -nbk_level 1 + -dbname C:\databases\countries.fdb -nbk_file C:\databases\countries_1.nbk +
+ To restore the whole shebang: +
+ fbsvcmgr frodo:service_mgr -user sysdba -password masterke + -action_nrest -dbname C:\databases\countries_restored.fdb + -nbk_file C:\databases\countries.nbk -nbk_file C:\databases\countries_1.nbk +
+ Notice: Each of the above commands should be typed as a single + sentence, without line breaks. The hyphens before the parameter names may be omitted, but + especially with long commands like these it may be helpful to leave them in, so you can easily + identify the individual parameters (the arguments don't get a hyphen). + Comments: + + + The Services Manager always requires authentication, be it automatic (root under + Posix, trusted under Windows) or explicit through the parameters + -user and -password. The environment + variables ISC_USER and ISC_PASSWORD are not used. + AUTO ADMIN MAPPING in the database has no effect when connecting + remotely (though this may also depend on the configuration of the network). + Note: When Windows trusted authentication is in effect, the account name of the user + on the local machine is passed to the Services Manager on the remote machine. If the owner + of the remote database is a Windows account (e.g. FRODO\PAUL) rather than a Firebird account, + and the Windows account name on the local machine is the same as the + owner account name on the remote machine, the caller is acknowledged as the database owner + and allowed to make a backup. This could pose a security risk, because even on local + networks user PAUL on one machine is not + necessarily the same person as user PAUL on + another machine. + + + Restoring (-action_nrest) also requires authentication, but + once verified the credentials are not used in any way. Hence, the user need not be the + database owner, SYSDBA or superuser. In the case of Windows trusted + authentication, the user need not exist at all on the remote machine (where the database + is located). + This weak authentication implies another potential security risk. Suppose a + sensitive database is nbackupped, and the backups are well protected on the filesystem + level. An average user can't restore the database with nbackup then, because nbackup runs + in the user process space. But that same user, if he knows name and location of the + backup, or can guess them by analogy, might be able to get hold of the database by having + fbsvcmgr restore it to a public folder. After all, fbsvcmgr + calls the Firebird server, which may have file-level access to the backup. Of course there + are solutions to this, but it's important to be aware of the risk. + + + The Services Manager can also be used locally; in that case the first argument + becomes service_mgr, without hostname. When used locally, + AUTO ADMIN MAPPING has the intended effect; this is still true if you + prepend localhost: or the name of the local machine. Local use of the + Services Manager can be beneficial if you don't have filesystem access to the database + and/or backup files, but the Firebird server process does. If you do have sufficient + rights, then it's more practical to use nbackup itself, with its much shorter + commands. + + + Specifying -nbk_no_triggers or + -nbk_direct with -action_nrest leads to an + error message. Nbackup itself is more lenient here: it simply ignores the + -T and -D parameters if they are used in the + wrong context. + + + Instead of a database filename you may also use an alias. + +
-
A practical application - - An nbackup-based incremental backup scheme could look like - this: - + An nbackup-based incremental backup scheme could look like this: Each month a full backup (level 0) is made; - Each week a level-1; - A level-2 backup daily; - A level-3 backup hourly. - - As long as all backups are preserved, you can restore the database - to its state at any hour in the past. For each restore action, a maximum - of four backup files is used. Of course you schedule things in such a - way that the bigger, time-consuming backups are made during off-peak - hours. In this case the levels 0 and 1 could be made at weekends, and - level 2 at night. - - If you don't want to keep everything for eternity, you can add a - deletion schedule: - + As long as all backups are preserved, you can restore the database to its state at any + hour in the past. For each restore action, a maximum of four backup files is used. Of course + you schedule things in such a way that the bigger, time-consuming backups are made during + off-peak hours. In this case the levels 0 and 1 could be made at weekends, and level 2 at + night. + If you don't want to keep everything for eternity, you can add a deletion + schedule: Level-3 backups are deleted after 8 days; - Level-2s after a month; - Level-1s after six months; - - Full backups after two years, but the first one of each year - is kept. + Full backups after two years, but the first one of each year is kept. - - This is only an example of course. What's useful in an individual - case depends on the application, the size of the database, its activity, - etc. + This is only an example of course. What's useful in an individual case depends on the + application, the size of the database, its activity, etc.
-
Read on? - - At this point you know everything you need in order to make and - restore full and/or incremental backups with nbackup. You only need to - read any further if you want to use backup tools of your own choice for - your Firebird databases (see Locking and - unlocking), or if you want to override the default - name or location of the delta file (see Setting the delta - file). - - If you have no craving for any of that: good luck in your work - with nbackup! + At this point you know everything you need in order to make and restore full and/or + incremental backups with nbackup. You only need to read any further if you want to use backup + tools of your own choice for your Firebird databases (see Locking and unlocking), or if you + want to override the default name or location of the delta file (see Setting the delta file). + If you have no craving for any of that: good luck in your work with nbackup!
-
Locking and unlocking - - If you prefer to use your own backup tools or just make a file copy, - nbackup's lock-unlock mode comes into view. Locking means - here that the main database file is frozen temporarily, not that no - changes can be made to the database. Just like in backup mode, mutations - are directed to a temporary delta file; upon unlocking, the delta file is - merged with the main file. - - As a reminder: nbackup.exe lives in the - bin subdir of your Firebird folder. - Typical locations are e.g. C:\Program - Files\Firebird\Firebird_2_0\bin (Windows) or /opt/firebird/bin (Linux). There's no GUI; - you launch it from the command prompt (or from within a batch file or - application). - + If you prefer to use your own backup tools or just make a file copy, nbackup's lock-unlock + mode comes into view. Locking means here that the main database file is frozen + temporarily, not that no changes can be made to the database. Just like in backup mode, + mutations are directed to a temporary delta file; upon unlocking, the delta file is merged with + the main file. + As a reminder: nbackup.exe lives in the bin subdir of your Firebird folder. Typical locations are e.g. + C:\Program Files\Firebird\Firebird_2_0\bin (Windows) or + /opt/firebird/bin (Linux). There's no GUI; you launch it + from the command prompt or call it from within a batch file or application.
Locking the database and backing up yourself - - A typical session in which you make your own backup goes as - follows: - + A typical session in which you make your own backup goes as follows: - Lock the database with the -L (lock) - switch: - + Lock the database with the -L (lock) switch:
nbackup [-U <user> -P <password>] -L <database>
- - Now copy/backup/zip the database file to your heart's content, - with your own choice of tools. A simple file copy is also - possible. + Now copy/backup/zip the database file to your heart's content, with your own choice + of tools. A simple file copy is also possible. - - Unlock the database with -N - (uNlock): - + Unlock the database with -N (uNlock):
nbackup [-U <user> -P <password>] -N <database>
- - The last command will also cause any mutations - which have been - written to the delta file - to be merged into the main file. - - The backup you made contains the data as they were at the moment - the database was locked, regardless how long the locked state has - lasted, and regardless how long you may have waited before making the - actual backup. - + The last command will also cause any mutations - which have been written to the delta + file - to be merged into the main file. + The backup you made contains the data as they were at the moment the database was + locked, regardless how long the locked state has lasted, and regardless how long you may have + waited before making the actual backup. + Comments: + + + Instead of a database filename you may also specify an alias. + + + The -U and -P parameters may be + omitted if the envars ISC_USER and ISC_PASSWORD are set, if + you are root on a Posix system, or if trusted authentication under Windows permits it. For + a detailed description see the comments under + Making full backups. + + + Starting with Firebird 2.5, instead of -P + <password> you may also use -FE + <filename>. + + + Both -L and -N make a regular + connection to the database, so in Firebird 2.1 and above it may be wise to add the + -T parameter (see Suppressing database + triggers). + + + If you're locking a raw-device database with Firebird 2.1 or above, the + -S option can be very helpful; see Locking raw-device + databases. + + + You can optionally add -Z to have version information printed + on the first line of the output. + + - What goes for backup/restore also applies to the lock/unlock - switches: do not use them on multi-file databases. Until things have - changed, don't let nbackup loose on multi-file databases at - all! + What goes for backup/restore also applies to the lock/unlock switches: do not use them + on multi-file databases. Until things have changed, don't let nbackup loose on multi-file + databases at all!
-
Restoring a backup made after <quote>nbackup -L</quote> - - An copy of a locked database is itself a locked database too, so - you can't just copy it back and start using it. Should your original - database get lost or damaged and the self-made copy needs to be restored - (or should you wish to install the copy on another machine), proceed + An copy of a locked database is itself a locked database too, so you can't just copy it + back and start using it. Should your original database get lost or damaged and the self-made + copy needs to be restored (or should you wish to install the copy on another machine), proceed like this: - - Copy/restore/unzip the backed-up database file yourself with - the necessary tools. + Copy/restore/unzip the backed-up database file yourself with the necessary + tools. - - Now unlock the database, not with the - -N switch, but with -F - (fixup): - + Now unlock the database, not with the -N + switch, but with -F (fixup):
nbackup -F <database>
+ Here too, you can optionally use an alias instead of a filename, and add + -Z for version info. Other options make no sense. - - Why are there two unlock switches, -N en + Why are there two unlock switches, -N and -F? - - -N first sees that any changes made - since the locking by -L are merged into the - main database file. After that, the database goes back into normal - read/write mode and the temporary file is deleted. + -N first sees that any changes made since the locking by + -L are merged into the main database file. After that, the database + goes back into normal read/write mode and the temporary file is deleted. - - -F only changes the state flag of the - self-restored database to normal. + -F only changes the state flag of the self-restored database + to normal. - So you use: - - -N after having - made a copy/backup yourself (to reverse the - -L issued earlier); + -N after having made a copy/backup + yourself (to reverse the -L issued earlier); - - -F after having - restored such a backup yourself. + -F after having restored such a backup + yourself. - It is a bit unfortunate that the last switch should be called - -F for Fixup. After all, it doesn't fix - anything; it only unlocks the database. The - -N (uNlock) flag on the other hand performs not - only an unlock, but also a fixup (integration of mutations into the - main file). But we'll have to live with that. + -F for Fixup. After all, it doesn't fix anything; it only + unlocks the database. The -N (uNlock) flag on + the other hand performs not only an unlock, but also a fixup (integration of mutations into + the main file). But we'll have to live with that. Come to think of it: you + can read -F as + Flag-only.
-
Under the hood - - Note: This section doesn't contain any necessary knowledge, but - provides some extra information which could deepen your understanding of - the various switches. - + Note: This section doesn't contain any necessary knowledge, but provides some extra + information which could deepen your understanding of the various switches. - - nbackup -L does the - following: - + nbackup -L does the following: Connect to the database; - Start a transaction; - - Call ALTER DATABASE BEGIN BACKUP (this statement has been - discussed in the extra - information on nbackup -B); + Call ALTER DATABASE BEGIN BACKUP (this statement has been discussed in the extra information on nbackup -B); - Commit the transaction; - Disconnect from the database. - - nbackup -N follows the - same steps, but with ...END BACKUP - in step 3. - - nbackup -F works as - follows: - + nbackup -N follows the same steps, but with + ...END BACKUP in step 3. + nbackup -F works as follows: The restored database file is opened; - Within the file, the state flag is changed from locked (nbak_state_stalled) to normal (nbak_state_normal); - The file is closed again. - - nbackup -F operates purely on file level and can therefore even - be performed without a Firebird server running. Any - -U or -P parameters - added to the command will be completely ignored. + nbackup -F operates purely on file level and can therefore also + be performed without a Firebird server running. Any credentials supplied via the + -U, -P or -FE + parameters are ignored, just as with nbackup -R.
+
+ Locking raw-device databases + As discussed in Backing up + raw-device databases, problems can arise if a delta has to be created for a + database located on a raw device. Therefore, in Firebird 2.1 and up, nbackup refuses to + operate on raw-device databases unless an explicit location for the delta file has been set + previously. For the procedure, see Setting the + delta file, a little further down. + There's also another problem if you lock and copy a raw device: you don't know the + actual size of the database! The raw device may be 10 GB, but the database might only take up + 200 MB of that space. To prevent having to copy the entire device just to be on the safe side + – possibly wasting huge amounts of time and space – Firebird 2.1 has introduced a new + parameter for nbackup: -S. This parameter is only valid in combination + with -L and when it is present, nbackup writes the database size in + pages to stdout after locking the database. Because the size is given + in pages, it has to be multiplied by the database page size in order to get the actual number + of bytes to be copied. Or, if you use the dd copy utility, you could + specify the page size as (i)bs and the output of + nbackup -L -S as + count. +
-
Setting the delta file - - By default, the delta file lives in the same directory as the - database itself. It also has the same name as the database file, but with - .delta appended. There is usually - no reason to change this, but it can be done if need be – though not via - nbackup itself. Make a connection to the - database with any client that allows you to enter your own SQL statements - and give the command: - + By default, the delta file lives in the same directory as the database itself. The file + name is also the same, but with .delta appended. This is + usually not a problem, but sometimes it is desirable or even necessary to change the location, + e.g. when the database is stored on a raw device. Nbackup itself has no provision for setting + the location; this must be done through SQL. + Make a connection to the database with any client that allows you to enter your own SQL + statements and give the command:
alter database add difference file 'path-and-filename'
- - The custom delta file specification is persistent in the database; - it is stored in the system table RDB$FILES. To revert - to the default behaviour, issue the following statement: - + The custom delta file specification is persistent in the database; it is stored in the + system table RDB$FILES. To revert to the default behaviour, issue the + following statement:
alter database drop difference file
- + You can also specify a custom delta location while creating a new database: +
+ create database 'path-and-dbname' difference file 'path-and-deltaname' +
Notes - - If you specify a bare file name with ADD DIFFERENCE - FILE, the delta will likely not be - created in the same directory as the database, but in the current - directory as seen from the server. On Windows this may e.g. be the - system directory. The same logic applies to relative paths. + If you specify a bare file name with [ADD] DIFFERENCE FILE, the + delta will likely not be created in the same directory as the + database, but in the current directory as seen from the server. On Windows this may e.g. + be the system directory. The same logic applies to relative paths. - - The entire directory path must already exist. Firebird doesn't - attempt to create any missing directories. + The entire directory path must already exist. Firebird doesn't attempt to create any + missing directories. - - If you want to change your custom delta specification, you - must first DROP the old one and then - ADD the new one. + If you want to change your custom delta specification, you must first + DROP the old one and then ADD the new + one.
- Document history - - The exact file history is recorded in the manual module in our CVS tree; see http://sourceforge.net/cvs/?group_id=9028 - + The exact file history is recorded in the manual + module in our CVS tree; see http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/nbackup.xml?view=log 0.1 - 21 Oct 2005 - PV - First edition. - 1.0 - 1 Dec 2006 - PV - - Removed beta reference in edition info. - Changed warning against specifying backup file names interactively - with nbackup -R. Removed (or will be) from first - sentence in Document History. - - Changed C:\Databases to - C:\Data in the examples, just to keep the lines - from running out of the shaded Removed beta reference in edition info. Changed warning against + specifying backup file names interactively with nbackup -R. Removed (or will + be) from first sentence in Document History. + Changed C:\Databases to C:\Data in the + examples, just to keep the lines from running out of the shaded screen areas in the PDF. - - Added section Setting the delta file, - and changed section Read on? - accordingly. + Added section Setting the delta file, and changed section + Read on? accordingly. - 1.1 - 5 May 2008 - PV - - Making and restoring backups: Added - warning about heavy-load risks with nbackup 2.0.0–2.0.3. - - Restoring a full backup: Corrected - wrong statement that nbackup will overwrite an existing database - if there are no active connections. Changed italic text about - interactive restore failure to a Note and mentioned its fix in + Making and restoring backups: Added warning about + heavy-load risks with nbackup 2.0.0–2.0.3. + Restoring a full backup: Corrected wrong statement that + nbackup will overwrite an existing database if there are no active connections. Changed + italic text about interactive restore failure to a Note and mentioned its fix in 2.0.1. - - Incremental backups: Inserted warning - that incremental backups are broken in 2.1. - - Suppressing database triggers (Firebird - 2.1+): New section. - - Read on?: Fixed typo (you -> - your). + Incremental backups: Inserted warning that incremental + backups are broken in 2.1. + Suppressing database triggers (Firebird 2.1+): New + section. + Read on?: Fixed typo (you -> your). + + + + 1.2 + 19 Sep 2011 + PV + + Document source formatting: Changed max. line length to 100, without open + lines. + All sections and subsections now have an id. + Introduction: Edited first sentence. + Nbackup features - an overview: First sentence: groups + -> kinds. Edited last para before first subsection: mentioned that only + SYSDBA, owner and sometimes OS admins can make a backup. + Nbackup features - an overview :: Limitations of nbackup: + Edited previously last listitem to mention Services Manager. Added listitem about direct + file access. Removed last para. + Functions and parameters: New section. + Making and restoring backups: Slightly altered last + sentence of first para. Extended warning: added info on the role of direct I/O with + large databases under Posix. + Making and restoring backups :: Full backups :: Making full + backups: Corrected and extended listitem on -U and + -P parameters. Added listitems on -FE + parameter (new in 2.5), -T parameter (new in 2.1) and + -D parameter (new in 2.5, backport to 2.1.4). In listitem + starting with The different parameters, the parenthesized text now reads + (-B, -U etc.), because many new parameters + have been added. + Making and restoring backups :: A word on the inner + workings: Small edit (image -> impression). + Making and restoring backups :: Full backups :: Restoring a full + backup: Removed parameters -U and + -P from specification. Added listitem on aliases. Changed + separate Note about interactive restore failure back to italic text inside the listitem + itself. Added listitem about non-necessity of running server and ignoring + credentials. + Making and restoring backups :: Incremental backups: Edited + Warning: mentioned fix in 2.1.1. + Making and restoring backups :: Incremental backups :: Restoring + incremental backups: Removed parameters -U and + -P from formal syntax and 1st listitem. + Making and restoring backups :: Backing up raw-device + databases: New section. + Making and restoring backups :: Suppressing database + triggers: Edited and extended this section, but removed the + SYSDBA and owner only remark. + Making and restoring backups :: Direct I/O (Firebird + 2.1.4+): New section. + Making and restoring backups :: Informational options (Firebird + 2.5+): New section. + Making and restoring backups :: Backups on remote machines (Firebird + 2.5+): New section. + Locking and unlocking: Slightly altered last sentence of + second para. + Locking and unlocking :: Locking the database and backing up + yourself: Added Comments (para + itemizedlist). + Locking and unlocking :: Restoring a backup made after nbackup + -L: Added info on use of alias and -Z to step + 2 of procedure. In next para, translated en (leftover from Dutch + original) -> and. Added sentence to Note about reading + -F as Flag-only. + Locking and unlocking :: Locking raw-device databases: New + section. + Locking and unlocking :: Under the hood: Edited + Note. + Setting the delta file: 1st para largely rewritten; now + refers to raw-device databases. Split off last sentence into a para of its own. Added + info (para + programlisting) about setting delta with CREATE + DATABASE. 1st listitem in Notes: ADD -> + [ADD]. + Document history: Changed ulink to CVS (both text and url); + now points directly to document. + License notice: End year in copryright mention now + 2011. - License notice - - The contents of this Documentation are subject to the Public - Documentation License Version 1.0 (the License); you may - only use this Documentation if you comply with the terms of this License. - Copies of the License are available at The contents of this Documentation are subject to the Public Documentation License Version + 1.0 (the License); you may only use this Documentation if you comply with the + terms of this License. Copies of the License are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf (PDF) and http://www.firebirdsql.org/manual/pdl.html (HTML). - The Original Documentation is titled Firebird's nbackup tool. - - The Initial Writer of the Original Documentation is: Paul - Vinkenoog. - - Copyright (C) 2005–2008. All Rights Reserved. Initial Writer - contact: paulvink at users dot sourceforge dot net. + The Initial Writer of the Original Documentation is: Paul Vinkenoog. + Copyright (C) 2005–2011. All Rights Reserved. Initial Writer contact: <firstname> at + <lastname> dot nl. -
\ No newline at end of file + From 432a75495364db9f15ea90ee38eb497da95e42b8 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Mon, 26 Sep 2011 13:40:34 +0000 Subject: [PATCH 04/33] Some minor changes. This is version 4.4, for inclusion with the Firebird 2.5.1 packages. --- src/docs/firebirddocs/quickstartguide-2.5.xml | 49 ++++++++++++++----- 1 file changed, 36 insertions(+), 13 deletions(-) diff --git a/src/docs/firebirddocs/quickstartguide-2.5.xml b/src/docs/firebirddocs/quickstartguide-2.5.xml index b2a177ac..e488a3dc 100644 --- a/src/docs/firebirddocs/quickstartguide-2.5.xml +++ b/src/docs/firebirddocs/quickstartguide-2.5.xml @@ -12,7 +12,7 @@ IBPhoenix Editors Firebird Project members - 8 July 2011, document version 4.3 — covers Firebird 2.5 + 26 September 2011, document version 4.4 — covers Firebird 2.5 and 2.5.1 project. Before you read on, verify that this guide matches your Firebird version. This guide - covers version 2.5. For all other Firebird versions, get the corresponding Quick Start Guide - at http://www.firebirdsql.org/en/documentation/. @@ -94,7 +94,7 @@ verified bij the Windows Domain Whatchamacallit.--> Server architectures Classic, SuperClassic or Superserver? Firebird servers come in two flavours, called architectures: - Classic Server and Superserver. Since Firebid 2.5, Classic Server can operate in two modes: + Classic Server and Superserver. Since Firebird 2.5, Classic Server can operate in two modes: traditional Classic and SuperClassic, giving a total of 3 models. Which one should you choose? The most important differences are listed below. In the vast majority of cases, all three models perform equally well and offer (almost) the same possibilities. @@ -1112,9 +1112,9 @@ alter user littlejohn grant admin role in regular databases Co-admins who want to use the SQL user management commands must specify the RDB$ADMIN role when connecting. However, since nobody can - connect to the security database, this requires a little trickery: the co-admin is - granted the RDB$ADMIN role in at least one regular database as - well. This is done in the usual way: + connect to the security database, this requires a little trickery. First, the co-admin + has to be granted the RDB$ADMIN role in at least one regular + database as well. This is done in the usual way:
grant rdb$admin to bigbill
@@ -1435,7 +1435,7 @@ shown by isql after a connect just copies what the user has specified, regardles The range of excellent GUI tools available for use with a Windows client machine is too numerous to describe here. A few GUI tools written in Borland Kylix, for use on Linux client machines, are also in various stages of completion. - Inspect the Downloads > + Explore the Download > Tools > Administration page at http://www.ibphoenix.com for all of the options. @@ -2005,7 +2005,7 @@ else
- The DISTINCT keyword comes to the rescue! + The <database>DISTINCT</database> keyword comes to the rescue! Firebird 2 and above implement a new use of the DISTINCT keyword allowing you to perform (in)equality tests that take NULL into account. The semantics are as follows: @@ -2016,7 +2016,7 @@ else They are NOT DISTINCT if they have the same value or if - both are NULL. + they are both NULL. Notice that if neither operand is NULL, @@ -2788,7 +2788,7 @@ to turn FW on themselves. This must be in the general forced writes section (not Creation of 2.5 Quick Start Guide, still equal to previous revision except for some version numbers, XML ids etc. Also removed erroneous id from primary index term in - Document History title. + Document History title. @@ -2822,7 +2822,6 @@ to turn FW on themselves. This must be in the general forced writes section (not 8 Jul 2011 PV - General: Added IDs to all sections that lacked one. About this guide: Changed ulink to Firebird Doc Index. @@ -2835,7 +2834,9 @@ to turn FW on themselves. This must be in the general forced writes section (not Classic, SuperClassic or Superserver? :: Installation packages: Added instruction on switching to SuperClassic on Linux. What is in the kit? now comes after the Classic, - SuperClassic or Superserver section. + SuperClassic or Superserver section. Itemized list now has compact spacing; + words essential reading now wrapped in emphasis element instead of written in all-caps. Default disk locations :: Linux: Added that default install dir may vary per distribution. Installing Firebird :: Testing your installation :: Note: @@ -2875,6 +2876,28 @@ to turn FW on themselves. This must be in the general forced writes section (not License notice: Copyright end year now 2011. + + 4.4 + 26 Sep 2011 + PV + + articleinfo, About this + guide: Added 2.5.1 to covered versions. + Classic, SuperClassic or Superserver?: Fixed typo in first + para: Firebid -> Firebird. + Server configuration and management :: User management: gsec :: + Appointing co-administrators :: Differences between co-administrators and + SYSDBA: Slightly changed wording of 2nd + listitem. + Server configuration and management :: Administration + tools: Inspect -> Explore. In ulink text: Downloads -> + Download. + Working with databases :: Firebird SQL :: Expressions involving + NULL :: The DISTINCT keyword comes to the + rescue!: Wrapped DISTINCT in title in + database element. Slightly altered wording in 2nd listitem. + + From cc6dbdc8a4f81c12277076935c9b4a1f92131b3b Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Mon, 26 Sep 2011 16:39:50 +0000 Subject: [PATCH 05/33] Added Xerces library and changed build.xml to enable the use of xincludes. --- lib/_readme_libs.txt | 13 ++++++++++--- src/build/build.xml | 26 ++++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/lib/_readme_libs.txt b/lib/_readme_libs.txt index 728870e6..9577ecc7 100644 --- a/lib/_readme_libs.txt +++ b/lib/_readme_libs.txt @@ -9,17 +9,24 @@ downloaded ALLJARS.ZIP, unzip it here. Don't use "Unzip to..." because that may create a subfolder and make the jars untraceable for the build program. -NOTE: Tools.jar has been left out of ALLJARS.ZIP because it's +LATEST (26 September 2011): + xercesImpl.jar has been added to the libraries. We need + this to be able to use xincludes. + You can download xercesImpl.jar separately from the server + or download and unzip the latest ALLJARS.ZIP + +OLDER NOTES: + - Tools.jar has been left out of ALLJARS.ZIP because it's rather big and not everybody needs it. Download it only if your PDF builds fail with a message about tools.jar not being found. -NOTE: If you have downloaded ALLJARS.ZIP, look at the timestamps + - If you have downloaded ALLJARS.ZIP, look at the timestamps of the JAR files on the server. If some JARs are newer than ALLJARS.ZIP, download them and install them over the versions extracted from the ZIP. -NOTE: If you still find the file "optional.jar" in the lib folder, + - If you still find the file "optional.jar" in the lib folder, delete it! Don't forget: you may also need to download files for manual/tools. diff --git a/src/build/build.xml b/src/build/build.xml index 4d98ac1a..9ad4681a 100644 --- a/src/build/build.xml +++ b/src/build/build.xml @@ -16,10 +16,23 @@ - + + + + + + + + + + + + @@ -389,6 +402,9 @@ --> + + + @@ -459,6 +475,9 @@ --> + + + @@ -625,6 +644,9 @@ --> + + + From 6fa21abf86539a43acff37c4bb1902712596f8fc Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Sat, 8 Oct 2011 22:20:29 +0000 Subject: [PATCH 06/33] Firebird 2.5 LangRef Update v1.1 committed to release branch. --- src/docs/refdocs/langref/langrefupd25.xml | 330 ++++++++++++++++++---- 1 file changed, 271 insertions(+), 59 deletions(-) diff --git a/src/docs/refdocs/langref/langrefupd25.xml b/src/docs/refdocs/langref/langrefupd25.xml index d57c7ad3..12049be8 100644 --- a/src/docs/refdocs/langref/langrefupd25.xml +++ b/src/docs/refdocs/langref/langrefupd25.xml @@ -1,8 +1,6 @@ - +"../../../../tools/docbook-dtd/docbookx.dtd"> Firebird 2.5 Language Reference Update @@ -12,7 +10,7 @@ Paul Vinkenoog et al. - 12 June 2011, document version 1.0 — covers Firebird 2.5 + 8 Oct 2011, document version 1.1 — covers Firebird 2.5 and 2.5.1 Introduction @@ -20,7 +18,7 @@ Subject matter What's this book about? This guide documents the changes made in the Firebird - SQL language between InterBase 6 and Firebird 2.5. It covers the following areas: + SQL language between InterBase 6 and Firebird 2.5.1. It covers the following areas: Reserved words @@ -103,7 +101,7 @@
Versions covered - This document covers all Firebird versions up to and including 2.5. + This document covers all Firebird versions up to and including 2.5.1.
Authorship @@ -151,19 +149,19 @@ New in Firebird 2.5 For users upgrading from Firebird 2.1, this chapter lists the SQL additions and changes in - Firebird 2.5, with links to the corresponding sections. If you come from an earlier version or - are new to Firebird, you may want to skip this - chapter. - + Firebird 2.5 and 2.5.1, with links to the corresponding sections. If you come from an earlier + version or are new to Firebird, you may want to skip + this chapter.
Reserved words and keywords + Changed since Firebird 2.1: - Newly reserved word: - SIMILAR. + Newly reserved words: + SIMILAR, SQLSTATE (2.5.1). - New keywords: + New non-reserved keywords: AUTONOMOUS, BIN_NOT, CALLER, CHAR_TO_UUID, COMMON, DATA, FIRSTNAME, @@ -230,6 +228,7 @@
Miscellany + Changed since Firebird 2.1: Hexadecimal notation for @@ -243,6 +242,7 @@
Data types and subtypes + Changed since Firebird 2.1: SQL_NULL data @@ -261,6 +261,7 @@
Data Definition Language (DDL) + Changed since Firebird 2.1: ALTER CHARACTER @@ -310,6 +311,7 @@
Data Manipulation Language (DML) + Changed since Firebird 2.1: UPDATE @@ -319,6 +321,7 @@
PSQL statements + Changed since Firebird 2.1: TYPE OF @@ -368,6 +371,7 @@
Security and access control + Changed since Firebird 2.1: ALTER @@ -409,8 +413,23 @@
+
+ Context variables + Changed since Firebird 2.1: + + + SQLCODE deprecated + (2.5.1) + + + SQLSTATE context variable + (2.5.1) + + +
Operators and predicates + Changed since Firebird 2.1: SIMLAR TO: Regular @@ -420,6 +439,7 @@
Aggregate functions + Changed since Firebird 2.1: LIST() separator may @@ -429,6 +449,7 @@
Internal functions + Changed since Firebird 2.1: CAST() as @@ -518,6 +539,7 @@ SAVEPOINT SENSITIVE SIMILAR + SQLSTATE (2.5.1) START TRAILING TRIM @@ -527,7 +549,7 @@
- New keywords + New non-reserved keywords The following words have been added to Firebird as non-reserved keywords. More than half of them are names of internal functions added between 2.0 and 2.1.
@@ -1002,7 +1024,7 @@ select _utf8 x'53C3A46765' from rdb$database
- Shorthand casts + Shorthand datetime casts Available in DSQL, ESQL, PSQL @@ -1037,6 +1059,14 @@ values new.lastmod = timestamp 'now'; + + Note + Please be advised that these shorthand expressions are evaluated immediately at parse + time and stay the same as long as the statement remains prepared. Thus, even if a query is + executed multiple times, the value for e.g. timestamp 'now' won't change, no + matter how much time passes. If you need the value to progress (i.e. be evaluated upon every + call), use a full cast. + See also CAST @@ -2083,7 +2113,8 @@ RDB$COLLATION_ATTRIBUTES = 4--> sets using 1 byte per character (so-called narrow character sets). UNI stands for UNICODE collations. - + Specific collation attributes @@ -3218,7 +3249,7 @@ END <inparam> ::= <param_decl> [{= | DEFAULT} value] <outparam> ::= <param_decl><param_decl> ::= paramname<type> [NOT NULL] [COLLATE collation] -<type> ::= sql_datatype | [TYPE OF] domain | TYPE OF COLUMN relname.colname +<type> ::= sql_datatype | [TYPE OF] domain | TYPE OF COLUMN rel.col<declarations> ::= See PSQL::DECLARE for the exact syntax /* If sql_datatype is a string type, it may include a character set */ @@ -3274,8 +3305,8 @@ select res from equalphrases('Appel', 'appèl'); + Warnings - Warnings For text types, character set and collation are included by TYPE OF COLUMN – just as when [TYPE OF] @@ -7370,7 +7401,7 @@ order by Men.age, Women.age
- Order by colum alias + Order by column alias Added in 2.0 @@ -9637,12 +9668,12 @@ be enclosed in single-quote characters. via a so-called external provider, even if the connection is to the current database. One of the consequences is that you can't catch exceptions the way you are used to. Every exception caused by the statement is wrapped in either an - isc_eds_connection or an isc_eds_statement - error. In order to catch them in your PSQL code, you have to use WHEN - GDSCODE isc_eds_connection, WHEN - GDSCODE isc_eds_statement or WHEN - ANY. (Without ON EXTERNAL, exceptions are caught in the - usual way, even if an extra connection is made to the current database.) + eds_connection or an eds_statement error. In + order to catch them in your PSQL code, you have to use WHEN GDSCODE + eds_connection, WHEN GDSCODE + eds_statement or WHEN ANY. (Without + ON EXTERNAL, exceptions are caught in the usual way, even if an extra + connection is made to the current database.) Miscellaneous notes @@ -11035,9 +11066,10 @@ else Within a PSQL module (procedure, trigger or executable block), the value of CURRENT_TIME will remain constant every time it is read. If multiple modules call or trigger each other, the value will remain constant throughout - the duration of the outermost module. If you need a progressing value in PSQL (e.g. to - measure time intervals), use 'NOW'. + the duration of the outermost module. If you need a progressing value in PSQL – e.g. + to measure time intervals – use 'NOW' with a full cast (not + shorthand syntax). @@ -11097,9 +11129,10 @@ else Within a PSQL module (procedure, trigger or executable block), the value of CURRENT_TIMESTAMP will remain constant every time it is read. If multiple modules call or trigger each other, the value will remain constant throughout - the duration of the outermost module. If you need a progressing value in PSQL (e.g. to - measure time intervals), use 'NOW'. + the duration of the outermost module. If you need a progressing value in PSQL – e.g. + to measure time intervals – use 'NOW' with a full cast (not + shorthand syntax). @@ -11210,12 +11243,14 @@ end Description - In a WHEN GDSCODE handling block, the GDSCODE - context variable contains a numerical representation of the current Firebird error code. - Starting with Firebird 2.0, the same is true in a WHEN ANY block if its - execution was triggered by a Firebird error; otherwise it contains 0. - GDSCODE is also 0 in WHEN SQLCODE and WHEN - EXCEPTION handlers, as well as everywhere else in PSQL. + In a WHEN ... DO error handling block, the + GDSCODE context variable contains the numerical representation of the + current Firebird error code. Prior to Firebird 2.0, GDSCODE was only set + in WHEN GDSCODE handlers. Now it may also be non-zero in WHEN + ANY, WHEN SQLCODE and WHEN EXCEPTION + blocks, provided that the condition raising the error corresponds with a Firebird error + code. Outside error handlers, GDSCODE is always 0. Outside PSQL it + doesn't exist at all. Type @@ -11224,8 +11259,8 @@ end Example
- when gdscode 335544551, gdscode 335544552, - gdscode 335544553, gdscode 335544707 + when gdscode grant_obj_notfound, gdscode grant_fld_notfound, + gdscode grant_nopriv, gdscode grant_nopriv_on_base do begin execute procedure log_grant_error(gdscode); @@ -11233,6 +11268,11 @@ begin end
+ Please notice: After WHEN GDSCODE, you must use symbolic names like + grant_obj_notfound etc. But the GDSCODE context + variable is an INTEGER. If you want to compare it against a certain + error, you have to use the numeric value, e.g. 335544551 for + grant_obj_notfound.
<varname>INSERTING</varname> @@ -11338,8 +11378,9 @@ select timestamp 'NOW' from rdb$database Notes - 'NOW' always returns the actual date/time, even in PSQL - modules, where CURRENT_DATE, When used with CAST(), 'NOW' always + returns the actual date/time, even in PSQL modules, where + CURRENT_DATE, CURRENT_TIME and CURRENT_TIMESTAMP return the same value throughout the duration of the outermost routine. This makes @@ -11347,11 +11388,16 @@ select timestamp 'NOW' from rdb$database and executable blocks. - Except in the situation mentioned above, reading - CURRENT_DATE, CURRENT_TIME and CURRENT_TIMESTAMP - is generally preferable to casting 'NOW'. Be aware though that + When used with the shorthand syntax, 'NOW' is evaluated at + parse time and the value is frozen for as long as the statement stays prepared – even + across multiple executions of the prepared statement! This is something to be aware + of. + + + Unless you really need progressing values in PSQL, or frozen values during + multiple executions, reading CURRENT_DATE, + CURRENT_TIME and CURRENT_TIMESTAMP is generally + preferable to using 'NOW'. Be aware though that CURRENT_TIME defaults to seconds precision; to get milliseconds precision, use CURRENT_TIME(3). @@ -11457,13 +11503,23 @@ if (row_count = 0) then Added in 1.5 + + Changed in + 2.0 + + + Deprecated in + 2.5.1 + Description - In a WHEN SQLCODE handling block, the SQLCODE - context variable contains the current SQL error code. The same is true in a WHEN - ANY block if its execution was triggered by an SQL error; otherwise it contains - 0. SQLCODE is also 0 in WHEN GDSCODE and - WHEN EXCEPTION handlers, as well as everywhere else in PSQL. + In a WHEN ... DO error handling block, the + SQLCODE context variable contains the current SQL error code. Prior to + Firebird 2.0, SQLCODE was only set in WHEN SQLCODE + and WHEN ANY handlers. Now it may also be non-zero in WHEN + GDSCODE and WHEN EXCEPTION blocks, provided that the + condition raising the error corresponds with an SQL error code. Outside error handlers, + SQLCODE is always 0. Outside PSQL it doesn't exist at all. Type @@ -11483,6 +11539,82 @@ begin end + + Important notice + SQLCODE is now deprecated in favour of the SQL-2003-compliant SQLSTATE + status code. Support for SQLCODE and WHEN SQLCODE + will be discontinued in some future version of Firebird. + +
+
+ <varname>SQLSTATE</varname> + + Available in + PSQL + + + Added in + 2.5.1 + + + Description + In a WHEN ... DO error handler, the + SQLSTATE context variable contains the 5-character, SQL-2003-compliant + status code resulting from the statement that raised the error. Outside error handlers, + SQLSTATE is always '00000'. Outside PSQL it is not available at + all. + + + Type + CHAR(5) + + + Example +
+ when any +do +begin + Msg = case sqlstate + when '22003' then 'Numeric value out of range.' + when '22012' then 'Division by zero.' + when '23000' then 'Integrity constraint violation.' + else 'Something bad happened! SQLSTATE = ' || sqlstate + end; + exception ex_custom Msg; +end +
+ + + Notes + + + SQLSTATE is destined to replace + SQLCODE. The latter is now deprecated in Firebird and will + disappear in some future version. + + + Firebird does not (yet) support the syntax WHEN SQLSTATE ... + DO. You have to use WHEN ANY and test the + SQLSTATE variable within the handler. + + + + Each SQLSTATE code is the concatenation of a 2-character + class and a 3-character subclass. Classes 00 (successful completion), 01 (warning) and + 02 (no data) represent completion conditions. Every status code + outside these classes is an exception. Because classes 00, 01 + and 02 don't raise an error, they won't ever show up in the + SQLSTATE variable. + + + For a complete listing of SQLSTATE codes, consult the + Appendix + to the Firebird 2.5 Release Notes. + + +
<varname>UPDATING</varname> @@ -11934,8 +12066,10 @@ above in the PDF version:--> <predefined class name> ::= ALPHA | UPPER | LOWER | DIGIT | ALNUM | SPACE | WHITESPACE - +
Building regular expressions @@ -11992,7 +12126,9 @@ above in the PDF version:--> 'Datte' similar to 'Dat[bcg-km-pwz]e' -- false +(which is illegal) but also treats it as a "_" wildcard: it matches any single character! + +CORE-3523 - Fixed by Adriano for 2.5.1--> The following predefined character classes can also be used in a class definition: @@ -12986,8 +13122,14 @@ from rdb$database DATE, TIME or TIMESTAMP: datatype 'date/timestring' - This syntax was already available in InterBase, but was never properly - documented. + This syntax was already available in InterBase, but was never properly documented. + Please notice: The shorthand syntax is evaluated immediately at + parse time, causing the value to stay the same until the statement is unprepared. For + datetime literals like '12-Oct-2012' this doesn't make any + difference. But for the pseudo-variables 'NOW', + 'YESTERDAY', 'TODAY' and + 'TOMORROW' this may not be what you want. If you need the value to be + evaluated at every call, use CAST(). @@ -15811,7 +15953,7 @@ rpad ('Hello', 2, '') -- returns 'He' char_length(str) – or a sufficiently high integer – as the third argument, unless you are sure that the requested substring fits within 32767 characters. - This bug has been fixed for version 2.5.1; the fix was also backported to + This bug has been fixed in version 2.5.1; the fix was also backported to 2.1.5. @@ -19534,6 +19676,7 @@ where exists SMALLINT SOME SQLCODE + SQLSTATE (2.5.1) START SUM TABLE @@ -19568,7 +19711,7 @@ where exists Keywords The following terms have a special meaning in Firebird 2.5 DSQL. Some of them are also reserved words, others aren't. - +
!< @@ -19880,6 +20023,7 @@ where exists SOURCE SPACE SQLCODE + SQLSTATE (2.5.1) SQRT STABILITY START @@ -20008,7 +20152,7 @@ where exists database. DDL statements :: DATABASE :: ALTER DATABASE :: END BACKUP: Updated URL of - Firebid Documentation Index in Tip. + Firebird Documentation Index in Tip. DDL statements :: DOMAIN :: ALTER DOMAIN: Replaced contents of Warning with reference to RDB$VALID_BLR note. @@ -20230,6 +20374,74 @@ where exists size). + + 1.1 + 8 Oct 2011 + PV + + articleinfo and Introduction :: + Versions covered: Added 2.5.1 to covered versions. + New in Firebird 2.5: Edited first para (mentioned + 2.5.1). + New in Firebird 2.5: Started all 10 subsections with + Changed since Firebird 2.1, for clarity. + New in Firebird 2.5 :: Reserved words and keywords: Added + SQLSTATE to Newly reserved words. Changed New + keywords to New non-reserved keywords. + New in Firebird 2.5 :: Context variables: New + subsection. + Reserved words and keywords :: Added since InterBase 6 :: Newly + reserved words: Added SQLSTATE. + Reserved words and keywords :: Added since InterBase 6 :: New + keywords: Renamed this section to New non-reserved + keywords. + Miscellaneous language elements :: Shorthand casts: Renamed + Shorthand datetime casts. + Miscellaneous language elements :: Shorthand datetime + casts: Added Note warning that value stays the same as long as the statement + remains prepared. + DDL statements :: PROCEDURE :: CREATE + PROCEDURE: Shortened + relname.colname to + rel.col in Syntax, to keep line + length within bounds for PDF. + DDL statements :: PROCEDURE :: CREATE + PROCEDURE :: TYPE OF COLUMN in parameter and + variable declarations: Moved title Warnings from + itemizedlist to parent warning, where it belongs. + DML statements :: SELECT :: ORDER + BY :: Order by colum alias: Corrected section title: + Order by column alias. + PSQL statements :: EXECUTE STATEMENT :: + ON EXTERNAL [DATA SOURCE] :: Exception + handling: isc_eds_connection, + isc_eds_statement -> eds_connection, + eds_statement. + Context variables :: CURRENT_TIME: + Edited second Note to warn against shorthand syntax. + Context variables :: CURRENT_TIMESTAMP: + Edited second Note to warn against shorthand syntax. + Context variables :: GDSCODE: Rewrote + Description in light of new, so far undocumented behaviour since Firebird 2.0 (!). + Corrected Example: after WHEN GDSCODE a symbolic name must follow, + not a number. Added notice after Example to explain same. + Context variables :: 'NOW': Edited the + two existing Notes and inserted one about the freeze effect of the shorthand syntax. In + the last Note, removed the link elements from around CURRENT_TIME and + CURRENT_TIMESTAMP. + Context variables :: SQLCODE: Added + Changed in and Deprecated in formalparas. Rewrote + Description in light of new, so far undocumented behaviour since Firebird 2.0 (!). Added + Notice at the end (also about the deprecation). + Context variables :: SQLSTATE: New + section (variable implemented in 2.5.1). + Internal functions :: CAST(): Added + notice that when using the shorthand syntax, the value stays the same as long as the + statement remains prepared. + Reserved words and keywords – full lists: Added + SQLSTATE to both Reserved words and Keywords. + + From 32df5de2ba31772642319221feb16d0f252bef55 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Sat, 8 Oct 2011 23:00:11 +0000 Subject: [PATCH 07/33] Replaced entity refs with xincludes. --- src/docs/refdocs/refdocs.xml | 44 +++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/src/docs/refdocs/refdocs.xml b/src/docs/refdocs/refdocs.xml index 1c15a920..f87c2880 100644 --- a/src/docs/refdocs/refdocs.xml +++ b/src/docs/refdocs/refdocs.xml @@ -1,37 +1,45 @@ - - - - -]> +"../../../tools/docbook-dtd/docbookx.dtd"> Firebird Reference Documentation Firebird RefDocs 2007, 2008, 2009, 2010, 2011 - : All contributions are Copyright of their individual authors, except where otherwise noted. + : All contributions are Copyright of their individual authors, except where otherwise + noted. Overview - This is the index to the English Firebird Reference documentation. For the full Firebird documentation index, visit: + This is the index to the English Firebird Reference documentation. For the full Firebird + documentation index, visit:
- http://www.firebirdsql.org/en/documentation/ + http://www.firebirdsql.org/en/documentation/
The Firebird Documentation Subproject homepage is here:
- http://www.firebirdsql.org/en/development-documentation/ + http://www.firebirdsql.org/en/development-documentation/
- - &langrefupd15; - &langrefupd20; - &langrefupd21; - &langrefupd25; - - &langreftempl; + + + + + + + + + From 0520679ee6d5a8aec6ae44497206044d84a97ecb Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Wed, 12 Oct 2011 07:55:29 +0000 Subject: [PATCH 08/33] Command line utilities updated for Firebird 2.5 --- src/docs/firebirddocs/fbutil_fbmgr.xml | 1342 +++++------ src/docs/firebirddocs/fbutil_gbak.xml | 232 +- src/docs/firebirddocs/fbutil_gfix.xml | 2852 ++++++++++++------------ src/docs/firebirddocs/fbutil_gsec.xml | 1546 +++++++------ src/docs/firebirddocs/fbutil_gstat.xml | 63 +- 5 files changed, 3292 insertions(+), 2743 deletions(-) diff --git a/src/docs/firebirddocs/fbutil_fbmgr.xml b/src/docs/firebirddocs/fbutil_fbmgr.xml index ea0f2c00..68dd1962 100644 --- a/src/docs/firebirddocs/fbutil_fbmgr.xml +++ b/src/docs/firebirddocs/fbutil_fbmgr.xml @@ -2,254 +2,261 @@ + -->
- Firebird Superserver Manager + Firebird Superserver Manager + + + 19 October 2009 + + + Norman + + Dunbar + + + 11 October 2011 – Document version 1.5 + + +
+ Introduction. + + Fbmgr is used to start and stop your + Firebird Superserver. This is different from starting and stopping a + database - as explained in the gfix manual - as + the running databases rely on the Firebird service/daemon. This daemon is + the Firebird engine - without it, nothing will run + under Superserver. - + + If you are using Firebird Classic, this chapter does not apply and + it is entirely possible that the executables mentioned in this chapter + may not even exist in your installation directory. + - - 19 October 2009 + On Windows systems, the engine runs as a service and is slightly + different. Windows will be discussed separately in this manual for that + reason. - - Norman + In the remainder of this manual, we will discuss the + following: - Dunbar - + + + Differences between Windows and Linux systems. + - 26 October 2009 – Document version 1.4 - + + Command-line options for + fbmgr. + -
- Introduction. + + Fbmgr commands and their + parameters. + - Fbmgr is used to start and stop your Firebird - Superserver. This is different from starting and stopping a database - as - explained in the gfix manual - as the running databases - rely on the Firebird service/daemon. This daemon is the Firebird - engine - without it, nothing will run under - Superserver. + + Running fbmgr in interactive or batch + modes. + - - If you are using Firebird Classic, this chapter does not apply and it is - entirely possible that the executables mentioned in this chapter may not even - exist in your installation directory. - - - On Windows systems, the engine runs as a service and is slightly different. - Windows will be discussed separately in this manual for that reason. - - In the remainder of this manual, we will discuss the following: - - - - Differences between Windows and Linux systems. - - - - Command-line options for fbmgr. - - - - Fbmgr commands and their - parameters. - - - - Running fbmgr in interactive or batch - modes. - - - - Some caveats, gotchas and foibles of - fbmgr. - - -
+ + Some caveats, gotchas and foibles of + fbmgr. + + +
-
- Linux Systems. +
+ Linux Systems. - On Linux, the Firebird engine is started whenever you carry out an install - - from an RPM or via a script - and at system boot time. This means that Firebird is - available whenever your system is running once you have Firebird installed. + On Linux, the Firebird engine is started whenever you carry out an + install - from an RPM or via a script - and at system boot time. This + means that Firebird is available whenever your system is running once you + have Firebird installed. - At boot time, the script /etc/init.d/firebird is - executed to start up the Firebird engine on Suse servers, other Linux servers use - the script /etc/rc.d/init.d/firebird instead. The same script - is executed just before the server shuts down to stop the Firebird engine. The - engine runs as the firebird user and not as root. + At boot time, the script /etc/init.d/firebird + is executed to start up the Firebird engine on Suse servers, other Linux + servers use the script /etc/rc.d/init.d/firebird + instead. The same script is executed just before the server shuts down to + stop the Firebird engine. The engine runs as the firebird user and not as + root. - The script is installed to the location described above, and a symbolic link - is created to /usr/sbin/rcfirebird and the script can - therefore be called in both ways, whichever you find easiest, but you must be the - root user: + The script is installed to the location described above, and a + symbolic link is created to /usr/sbin/rcfirebird and + the script can therefore be called in both ways, whichever you find + easiest, but you must be the root user: - tux> /etc/init.d/firebird <parameter>or + tux> /etc/init.d/firebird <parameter>or - tux> rcfirebird <parameter> + tux> rcfirebird <parameter> - This script can take one of the following parameters: + This script can take one of the following parameters: - - - start + + + start - Starts the Firebird engine. If already running, does nothing. The - engine is started under the watchful eye of the guardian process - (fbguard) and is set to automatically restart - if the engine fails for any reason. The engine runs under the firebird - user even though you have to be root to run the - rcfirebird script. - + Starts the Firebird engine. If already running, does nothing. + The engine is started under the watchful eye of the guardian process + (fbguard) and is set to automatically + restart if the engine fails for any reason. The engine runs under the + firebird user even though you have to be root to run the + rcfirebird script. + - - stop + + stop - Stops the Firebird engine. If already stopped, does nothing. It - kills the process for the running engine by reading the pidfile (by - default /var/run/firebird/firebird.pid). If the - process is not running, no error is reported. - + Stops the Firebird engine. If already stopped, does nothing. It + kills the process for the running engine by reading the pidfile (by + default /var/run/firebird/firebird.pid). If the + process is not running, no error is reported. + + + + status + + Checks the current status of the Firebird engine. This command + can return a status code (in $?) as follows: + + tux> rcfirebird status ; echo $? - - status - - Checks the current status of the Firebird engine. This command can - return a status code (in $?) as follows: - - tux> rcfirebird status ; echo $? - - - - 0 - the engine is running. - - - - 1 - the engine was not running but the pidfile was - found. - - - - 2 - the engine was not running but the lock file was - found. - - - - 3 - the engine was not running. - - + + + 0 - the engine is running. + + + + 1 - the engine was not running but the pidfile was + found. + + + + 2 - the engine was not running but the lock file was + found. + + + + 3 - the engine was not running. + + - - The status parameter is not available on - every Linux distribution. You can check if it is available on your - installation by running the rcfirebird command with - no parameters: + + The status parameter is not available + on every Linux distribution. You can check if it is available on + your installation by running the rcfirebird + command with no parameters: - tux> rcfirebird + tux> rcfirebird Usage: /usr/sbin/rcfirebird {start|stop|status|try-restart|restart| force-reload|reload} - The command will list all the options available for your - particular installation. - - - - - try-restart - - Restarts the Firebird engine but only if it is currently running, - otherwise, does nothing. - - - - restart - - Stops and restarts the Firebird engine, whether it was running or - not. - - - - force-reload - - This is exactly the same as the restart - command. - - - - reload - - Reload is not implemented. - - - - It might be necessary for you to manually shut down the engine from time to - time, and to restart it again afterwards. To do this, and assuming that either - none of the options to rcfirebird are suitable or you do not - have root privileges, fbmgr is your tool. - Fbmgr is, by default, available to all users of the - system to execute - however, in order to start and stop the Firebird engine, root - or SYSDBA rights are required. - - - It is noted that the default shell for the firebird user (at least of - Suse systems) defaults to /bin/false and so, you cannot - log in as the firebird user. This means that you must use - rcfirebird to start and stop the engine because if you use - fbmgr as root, then all databases created by the - engine will be owned by root. - - In order to allow the firebird user the ability to start and stop the - database engine, you need to alter the default shell from - /bin/false to something like - /bin/bash and set a password, while - logged in as root, as follows: - - tux> usermod --shell /bin/bash firebird + The command will list all the options available for your + particular installation. + + + + + try-restart + + Restarts the Firebird engine but only if it is currently + running, otherwise, does nothing. + + + + restart + + Stops and restarts the Firebird engine, whether it was running + or not. + + + + force-reload + + This is exactly the same as the restart + command. + + + + reload + + Reload is not implemented. + + + + It might be necessary for you to manually shut down the engine from + time to time, and to restart it again afterwards. To do this, and assuming + that either none of the options to rcfirebird are + suitable or you do not have root privileges, + fbmgr is your tool. + Fbmgr is, by default, available to all users of + the system to execute - however, in order to start and stop the Firebird + engine, root or SYSDBA rights are required. + + + It is noted that the default shell for the firebird user (at least + of Suse systems) defaults to /bin/false and so, you + cannot log in as the firebird user. This means that you must use + rcfirebird to start and stop the engine because if + you use fbmgr as root, then all databases + created by the engine will be owned by root. + + In order to allow the firebird user the ability to start and stop + the database engine, you need to alter the default shell from + /bin/false to something like + /bin/bash and set a password, + while logged in as root, as follows: + + tux> usermod --shell /bin/bash firebird tux> passwd firebird - - - Fbmgr is a very short shell script which - currently - as of version 2.1.3 - exports the FIREBIRD environment - variable and calls fmbgr.bin - passing all supplied parameters over, so - fbmgr.bin does all the hard - work. - - As the two are interchangeable, I shall use the former (and shorter!) - fbmgr in the remainder of this chapter. - -
- Fbmgr Commands. - - Fbmgr can be run interactively or in batch mode. The commands are - identical whichever mode you use and the following section describes the - commands and shows examples of each, running in both modes. - - To enter interactive mode, simply log in as the firebird user and type - the command fbmgr. If /opt/firebird/bin is not on your path, type the - command bin/fbmgr instead. - - - When you log in as the firebird user, the home directory - ($HOME) is set to be /opt/firebird. The bin subdirectory, where all the firebird - binaries live, is immediately beneath $HOME. - - -
- Getting Help. - - To see a list of all the commands - except, for some reason, the - start command - run fbmgr and pass the - -help command (in batch mode) or type - help at the prompt in interactive mode. The - resulting output is the same regardless, including the grammatical error - "... also be used as an option switches ...": - - tux> fbmgr -help + + + Fbmgr is a very short shell script which + currently - as of version 2.1.3 - exports the FIREBIRD + environment variable and calls + fmbgr.bin passing all + supplied parameters over, so + fbmgr.bin does all the + hard work. + + As the two are interchangeable, I shall use the former (and + shorter!) fbmgr in the remainder of this + chapter. + +
+ Fbmgr Commands. + + Fbmgr can be run interactively or in batch mode. The commands are + identical whichever mode you use and the following section describes the + commands and shows examples of each, running in both modes. + + To enter interactive mode, simply log in as the firebird user and + type the command fbmgr. If /opt/firebird/bin is not on your path, type + the command bin/fbmgr instead. + + + When you log in as the firebird user, the home directory + ($HOME) is set to be /opt/firebird. The bin subdirectory, where all the firebird + binaries live, is immediately beneath $HOME. + + +
+ Getting Help. + + To see a list of all the commands - except, for some reason, the + start command - run fbmgr and pass the + -help command (in batch mode) or type + help at the prompt in interactive mode. The + resulting output is the same regardless, including the grammatical + error "... also be used as an option switches + ...": + + tux> fbmgr -help Usage: fbmgr -command [-option [parameter]] @@ -281,332 +288,337 @@ fbmgr<RETURN> FBMGR> password <password> FBMGR> shut -
+
-
- Starting Up. +
+ Starting Up. - When the Firebird engine is started, it normally runs under the - watchful eyes of the guardian process. The guardian will restart the - engine any time it determines that the engine has crashed and in doing so, - will hopefully reduce the downtime that the users may suffer as a result - of a crashed engine. + When the Firebird engine is started, it normally runs under the + watchful eyes of the guardian process. The guardian will restart the + engine any time it determines that the engine has crashed and in doing + so, will hopefully reduce the downtime that the users may suffer as a + result of a crashed engine. - It is possible, however, to force the engine to be started up and - the guardian will allow it to stay down if it detects a crash. - Fbmgr allows the DBA or System Administrator to - decide which of the two startup methods will be used. + It is possible, however, to force the engine to be started up + and the guardian will allow it to stay down if it detects a crash. + Fbmgr allows the DBA or System + Administrator to decide which of the two startup methods will be + used. -
- Start And Stay Running. +
+ Start And Stay Running. - At system boot time, the engine is started in the mode that - allows the guardian to restart it in the event of a crash. To perform - this task manually using fbmgr you would - carry out one of the following: + At system boot time, the engine is started in the mode that + allows the guardian to restart it in the event of a crash. To + perform this task manually using fbmgr + you would carry out one of the following: - tux> fbmgr -start -forever + tux> fbmgr -start -forever server has been successfully started - Or, in interactive mode: + Or, in interactive mode: - tux> fbmgr + tux> fbmgr FBMGR> start -forever server has been successfully started - If you are logged in as a privileged user - then you don't need to specify a -user as these - login accounts default to SYSDBA when fbmgr - is run. If you log in as any other user, even supplying a user name - will not be enough to allow you to restart a closed database - engine. - - - A privileged user is one that the Firebird engine considers - to be privileged enough to automatically be given SYSDBA rights. - This means that it can start and stop the engine without being - required to authenticate as SYSDBA. At present there are four - login names that are assumed to be privileged, these are: - - - - root - - - - firebird - - - - interbase - - - - interbas (without the 'e') - - - - - The start command defaults to - -forever if nothing is specified. - - tux> fbmgr -start + If you are logged in as a privileged user + then you don't need to specify a -user as + these login accounts default to SYSDBA when + fbmgr is run. If you log in as any other + user, even supplying a user name will not be enough to allow you to + restart a closed database engine. + + + A privileged user is one that the Firebird engine considers + to be privileged enough to automatically be given SYSDBA rights. + This means that it can start and stop the engine without being + required to authenticate as SYSDBA. At present there are four + login names that are assumed to be privileged, these are: + + + + root + + + + firebird + + + + interbase + + + + interbas (without the 'e') + + + + + The start command defaults to + -forever if nothing is specified. + + tux> fbmgr -start server has been successfully started -
+
-
- Start And Stop Running. +
+ Start And Stop Running. - Under normal circumstances you would wish for the database - engine to remain running as long as possible. At other times, however, - you may wish for any crashes to be investigated prior to restarting - the engine. This is possible using fbmgr as - the following shows: + Under normal circumstances you would wish for the database + engine to remain running as long as possible. At other times, + however, you may wish for any crashes to be investigated prior to + restarting the engine. This is possible using + fbmgr as the following shows: - tux> fbmgr -start -once + tux> fbmgr -start -once - Or, running interactively: + Or, running interactively: - tux> fbmgr + tux> fbmgr FBMGR> start -once -
-
+
+
-
- Shutting Down. +
+ Shutting Down. - Shutting down the engine stops the guardian process from restarting - it. If this was not the case, it would be very difficult to actually stop - the Firebird engine! + Shutting down the engine stops the guardian process from + restarting it. If this was not the case, it would be very difficult to + actually stop the Firebird engine! - - Any user who has logged on to the database server and who is - armed with the SYSDBA password, can close the engine down. This is a - slight inconsistency as only the privileged users can start the - engine. - + + Any user who has logged on to the database server and who is + armed with the SYSDBA password, can close the engine down. This is a + slight inconsistency as only the privileged users can start the + engine. + - If you are logged in as a privileged user, you do not need to supply - a user name to shut down the engine, you are only required to supply the - SYSDBA password. + If you are logged in as a privileged user, you do not need to + supply a user name to shut down the engine, you are only required to + supply the SYSDBA password. - tux> fbmgr -shut -password secret + tux> fbmgr -shut -password secret server shutdown completed - You are required to supply a user name if you - log in as your own account. + You are required to supply a user name if + you log in as your own account. - tux> fbmgr -shut -password secret + tux> fbmgr -shut -password secret no permissions to perform operation tux> fbmgr -shut -user sysdba -password secret server shutdown completed -
+
-
- Showing Details. +
+ Showing Details. - The show command displays the name of the server that you are - running on and details of the user you are currently using. If you are - running fbmgr as a privileged user, then the - user will be SYSDBA unless you specified a different one with the - -user parameter. + The show command displays the name of the server that you are + running on and details of the user you are currently using. If you are + running fbmgr as a privileged user, then + the user will be SYSDBA unless you specified a different one with the + -user parameter. - tux> fbmgr -show + tux> fbmgr -show Host: localhost User: SYSDBA - You can supply a different user name on the command line if - desired: + You can supply a different user name on the command line if + desired: - tux> fbmgr -show -username norman + tux> fbmgr -show -username norman Host: localhost User: NORMAN - In interactive mode, the process is almost identical: + In interactive mode, the process is almost identical: - tux> fbmgr + tux> fbmgr FBMGR> show Host: localhost User: SYSDBA - Or, using a different user name: + Or, using a different user name: - tux> fbmgr -user norman + tux> fbmgr -user norman FBMGR> show Host: localhost User: NORMAN - It appears that the show command always - displays the hostname as localhost while you are logged onto that server. - It is unfortunate that the show command doesn't - show any details about the running (or otherwise) Firebird engine. You can - find this out as follows: + It appears that the show command always + displays the host name as localhost while you are logged onto that + server. It is unfortunate that the show command + doesn't show any details about the running (or otherwise) Firebird + engine. You can find this out as follows: - tux> ps -ef|grep -i fire[b]ird + tux> ps -ef|grep -i fire[b]ird firebird 3752 1 0 14:13 ? 00:00:00 /opt/firebird/bin/fbguard -o firebird 3753 3752 0 14:13 ? 00:00:00 /opt/firebird/bin/fbserver - Look closely at the process details for the guardian, you can see a - -o parameter. This indicates that the engine is - running and is in -once mode. If it crashes at any - time, it will not be restarted by the guardian. In - -forever mode, the parameter is - -f. - - If you don't see either the guardian or the server processes, then - you can assume that the (Superserver) engine is not running. - - - When using grep to filter out the interesting - processes from a call to ps -ef, for example, using - a character class for one single character prevents the - grep process itself from being listed. The - following two grep commands produce identical results but using the - character class in the first saves having to call grep -v - grep to filter out the unwanted grep - process. - - ps -ef | grep -i fire[b]ird + Look closely at the process details for the guardian, you can + see a -o parameter. This indicates that the + engine is running and is in -once mode. If it + crashes at any time, it will not be restarted by the guardian. In + -forever mode, the parameter is + -f. + + If you don't see either the guardian or the server processes, + then you can assume that the (Superserver) engine is not + running. + + + When using grep to filter out the + interesting processes from a call to ps -ef, for + example, using a character class for one single character prevents + the grep process itself from being listed. The + following two grep commands produce identical results but using the + character class in the first saves having to call grep -v + grep to filter out the unwanted grep + process. + + ps -ef | grep -i fire[b]ird ps -ef | grep -i firebird | grep -v grep - -
+ +
-
- Exiting. +
+ Exiting. - The quit command gets you out of an - interactive session. There is no quit command for batch mode. -
-
+ The quit command gets you out of an + interactive session. There is no quit command for batch mode. +
- -
- Windows Systems. - - On Windows 2000/2003, Vista and NT systems as well as the non-home versions - of XP, the Firebird engine runs as a service as does the Firebird Guardian. Both - of these run under the local system user account. For best results and stability, - you are advised to keep Firebird running as a service rather than as an - application. - - After installation, these two services are defined to be started and stopped - automatically on server boot and shutdown. If you wish to control when the - services are started and stopped, use Control Panel to - change their properties to manual. - - On Windows ME, 95, 98 and XP Home, the engine runs as an application as does - the guardian. In this case, an icon will be seen in the system tray and you can - carry out manual maintenance by right clicking on the icon. - - - The remainder of this section assumes that you have the Firebird engine - and the guardian running as services. All the engine commands are accessed via - a right-click on the guardian icon in the system tray when running as an - application. - - - On Windows, the guardian process is the file - fbguard.exe and the engine itself is the file - fbserver.exe. - - Normally the instsvc command is used to install or remove - services. It can also be used to start and stop services that already exist. When - discussing the instsvc command below, it will be used only to - start and stop services rather than installing and removing them. - -
- Starting The Engine. - - When you start the guardian service on Windows, it will automatically - bring up the database engine without you needing to physically start it - too. - -
- Using Net Start. - - Provided you know the exact service name, you can use the - net commands to start (and stop) the guardian and - database engine. Up until Firebird 2.0, the service name was simply - "FirebirdServer". From Version 2.1 onwards, there can be many different - services running. In this section, only the default services for Firebird - 2.x will be discussed and these are "Firebird Guardian - DefaultInstance" - and "Firebird Server - DefaultInstance". As there are spaces in the names, - double quotes are required to prevent errors. - - C:\>net start "firebird guardian - defaultinstance" +
+ +
+ Windows Systems. + + On Windows 2000/2003, Vista and NT systems as well as the non-home + versions of XP, the Firebird engine runs as a service as does the Firebird + Guardian. Both of these run under the local system user account. For best + results and stability, you are advised to keep Firebird running as a + service rather than as an application. + + After installation, these two services are defined to be started and + stopped automatically on server boot and shutdown. If you wish to control + when the services are started and stopped, use Control + Panel to change their properties to manual. + + On Windows ME, 95, 98 and XP Home, the engine runs as an application + as does the guardian. In this case, an icon will be seen in the system + tray and you can carry out manual maintenance by right clicking on the + icon. + + + The remainder of this section assumes that you have the Firebird + engine and the guardian running as services. All the engine commands are + accessed via a right-click on the guardian icon in the system tray when + running as an application. + + + On Windows, the guardian process is the file + fbguard.exe and the engine itself is the file + fbserver.exe. + + Normally the instsvc command is used to install + or remove services. It can also be used to start and stop services that + already exist. When discussing the instsvc command + below, it will be used only to start and stop services rather than + installing and removing them. + +
+ Starting The Engine. + + When you start the guardian service on Windows, it will + automatically bring up the database engine without you needing to + physically start it too. + +
+ Using Net Start. + + Provided you know the exact service name, you can use the + net commands to start (and stop) the guardian and + database engine. Up until Firebird 2.0, the service name was simply + "FirebirdServer". From Version 2.1 onwards, there can be many + different services running. In this section, only the default services + for Firebird 2.x will be discussed and these are "Firebird Guardian - + DefaultInstance" and "Firebird Server - DefaultInstance". As there are + spaces in the names, double quotes are required to prevent + errors. + + C:\>net start "firebird guardian - defaultinstance" The Firebird Guardian - DefaultInstance service is starting. The Firebird Guardian - DefaultInstance service was started successfully. -
+
-
- Using Instsvc. +
+ Using Instsvc. - As you can see from the above, under Firebird 2.x, the service names - are a bit unwieldy. It is easier to use instsvc to - start the services as you do not need to know the default service - names. + As you can see from the above, under Firebird 2.x, the service + names are a bit unwieldy. It is easier to use + instsvc to start the services as you do not need to + know the default service names. - C:\>instsvc start + C:\>instsvc start Service "Firebird Guardian - DefaultInstance" successfully started. -
-
+
+
-
- Stopping The Engine. +
+ Stopping The Engine. - When you stop the guardian service on Windows, it will automatically - bring down the database engine without you being required to stop it - too. + When you stop the guardian service on Windows, it will + automatically bring down the database engine without you being required + to stop it too. -
- Using Net Stop. +
+ Using Net Stop. - As with starting the services, in order to use net - stop to bring the guardian and engine down, you need to know the - exact service name (for the guardian) and enclose it in quotes if there - are spaces in the name. + As with starting the services, in order to use net + stop to bring the guardian and engine down, you need to know + the exact service name (for the guardian) and enclose it in quotes if + there are spaces in the name. - C:\>net stop "firebird guardian - defaultinstance" + C:\>net stop "firebird guardian - defaultinstance" The Firebird Guardian - DefaultInstance service is stopping. The Firebird Guardian - DefaultInstance service was stopped successfully. -
+
-
- Using Instsvc. +
+ Using Instsvc. - As with starting the default services, stopping them is far easier - using instsvc. + As with starting the default services, stopping them is far + easier using instsvc. - C:\>instsvc stop + C:\>instsvc stop Service "Firebird Guardian - DefaultInstance" successfully stopped. -
-
+
+
-
- Querying The Engine. +
+ Querying The Engine. - It is possible to query the services running on the server to check - whether the Firebird services are running or not. Once again, the - instsvc command is used: + It is possible to query the services running on the server to + check whether the Firebird services are running or not. Once again, the + instsvc command is used: - C:\>instsvc q + C:\>instsvc q Firebird Guardian - DefaultInstance IS installed. Status : stopped @@ -620,110 +632,115 @@ Firebird Server - DefaultInstance IS installed. Startup : manual Run as : LocalSystem - It can be seen from the above, that there are two services installed on - this server, but none of them are currently running. Other details are - displayed such as whether or not these services are started automatically on - reboot - in the example above, this is not the case - and the user account - (LocalSystem) under which the services will be run, when they are - started. - - This command is very useful as it displays the two service names - once - you have that information, you may use the net stop or - net start commands to bring the database down and to - restart it. -
+ It can be seen from the above, that there are two services + installed on this server, but none of them are currently running. Other + details are displayed such as whether or not these services are started + automatically on reboot - in the example above, this is not the case - + and the user account (LocalSystem) under which the services will be run, + when they are started. + + This command is very useful as it displays the two service names - + once you have that information, you may use the net + stop or net start commands to bring the + database down and to restart it.
+
-
- Fbmgr Caveats - - The following caveats are all specific to the Linux (and by assumption, - other Unix systems) and do not apply to Windows versions of Firebird. The reason - is simple, Windows doesn't have an fbmgr application as - it uses the instsvc command instead. +
+ Fbmgr Caveats -
- The Help Command. + The following caveats are all specific to the Linux (and by + assumption, other Unix systems) and do not apply to Windows versions of + Firebird. The reason is simple, Windows doesn't have an + fbmgr application as it uses the + instsvc command instead. - The help command, as described above, doesn't - mention that fact that there is a start command. There - is a very brief mention of the start command, but no - text explains its use, unlike the other commands which are described. -
+
+ The Help Command. -
- Who Owns The Databases? - - While not an error as such, this is something that you should be aware - of. When the server boots, it starts the Firebird engine and runs it as the - user firebird. By default, the firebird has no interactive shell - it defaults - to /bin/false - and so you cannot log in to, or - su to, the firebird user to manually run a command. - - This means that, unless you change the firebird user's default shell as - described above, you will have to carry out any manual restarts etc of the - engine as the root user - although you can shut it down as any user provided - you have the SYSDBA password. - - If you do restart the engine as root, then it will now be running as - root. While existing databases - owned by the firebird user - will happily be - read from and written to by root, any new databases created will be owned by - root. Everything will work fine for a while but after the server is next - rebooted, these new databases will then fail to be accessible as the engine is - now running as the firebird user again and that user has no permissions to - access the databases owned by root. - - You are therefore advised to always start and stop the server - either: - - - - as root, using the rcfirebird command; - or - - - - as firebird, using fbmgr. - - + The help command, as described above, + doesn't mention that fact that there is a start + command. There is a very brief mention of the + start command, but no text explains its use, + unlike the other commands which are described. +
- but never, ever, as root using fbmgr. If you - follow the above instructions, all your databases will be owned by the - firebird user. -
+
+ Who Owns The Databases? + + While not an error as such, this is something that you should be + aware of. When the server boots, it starts the Firebird engine and runs + it as the user firebird. By default, the firebird has no interactive + shell - it defaults to /bin/false - and so you + cannot log in to, or su to, the firebird user to + manually run a command. + + This means that, unless you change the firebird user's default + shell as described above, you will have to carry out any manual restarts + etc of the engine as the root user - although you can shut it down as + any user provided you have the SYSDBA password. + + If you do restart the engine as root, then it will now be running + as root. While existing databases - owned by the firebird user - will + happily be read from and written to by root, any new databases created + will be owned by root. Everything will work fine for a while but after + the server is next rebooted, these new databases will then fail to be + accessible as the engine is now running as the firebird user again and + that user has no permissions to access the databases owned by + root. + + You are therefore advised to always start and stop the server + either: + + + + as root, using the rcfirebird command; + or + + + + as firebird, using fbmgr. + + + + but never, ever, as root using fbmgr. + If you follow the above instructions, all your databases will be owned + by the firebird user. +
-
- What's That Defunct Guardian Process Doing? +
+ What's That Defunct Guardian Process Doing? - If you run fbmgr and shut down the database - engine, the fbserver process vanishes from the list of - processes running under the firebird user. However, a ps -ef|grep -i - fir[e]bird command will show the following: + If you run fbmgr and shut down the + database engine, the fbserver process vanishes from + the list of processes running under the firebird user. However, a + ps -ef|grep -i fir[e]bird command will show the + following: - tux> ps -ef|grep -i fir[e]bird + tux> ps -ef|grep -i fir[e]bird firebird 29978 29844 0 15:57 pts/0 00:00:00 /opt/firebird/bin/fbmgr.bin firebird 29979 29978 0 15:57 ? 00:00:00 [fbguard] <defunct> root 29992 29955 0 15:57 pts/1 00:00:00 grep -i fire - The guardian process, fbguard, doesn't vanish until - you exit from fbmgr. This again is not a major - problem, but knowing that all you have to do is exit from - fbmgr to make it vanish is helpful. -
+ The guardian process, fbguard, doesn't vanish + until you exit from fbmgr. This again is not + a major problem, but knowing that all you have to do is exit from + fbmgr to make it vanish is helpful. +
-
- I Can Shut Down But Not Start Up The Engine. +
+ I Can Shut Down But Not Start Up The Engine. - If you log in to the server as a privileged user and have the SYSDBA's - password, you can shut down and start up the engine with no problems. If, on - the other hand, you log in as any other user and try to use - fbmgr to stop and start the Firebird engine, you - will find that you can stop it with no problems but you will not be allowed to - restart it. Only privileged users can start the engine. The following shows - the problem. + If you log in to the server as a privileged user and have the + SYSDBA's password, you can shut down and start up the engine with no + problems. If, on the other hand, you log in as any other user and try to + use fbmgr to stop and start the Firebird + engine, you will find that you can stop it with no problems but you will + not be allowed to restart it. Only privileged users can start the + engine. The following shows the problem. - tux> # Shutdown Firebird engine as user 'norman'. + tux> # Shutdown Firebird engine as user 'norman'. tux> fbmgr -shut -password secret no permissions to perform operation @@ -746,135 +763,150 @@ tux> # Give up and restart the engine as 'firebird'. tux> su - firebird tux> bin/fbmgr -start server has been successfully started -It can be seen from the above that a normal user armed with the SYSDBA user name - and password can stop the Firebird engine but is completely unable to restart - it afterwards. - - The reason why this is the case is quite simple. Until the firebird - engine is started, there is no way to check that the password supplied for the - SYSDBA user is actually correct. Because of this, logging in as a privileged - user assumes SYSDBA privileges and allows you to start the engine. -
+It can be seen from the above that a normal user armed with the + SYSDBA user name and password can stop the Firebird engine but is + completely unable to restart it afterwards. + + The reason why this is the case is quite simple. Until the + firebird engine is started, there is no way to check that the password + supplied for the SYSDBA user is actually correct. Because of this, + logging in as a privileged user assumes SYSDBA privileges and allows you + to start the engine. +
-
- Shut with no parameters appears to be a bug. +
+ Shut with no parameters appears to be a bug. - Running fbmgr's -shut command with no user or password gives the - following cryptic output: + Running fbmgr's -shut command with no user or password gives the + following cryptic output: - tux> fbmgr -shut + tux> fbmgr -shut Invalid clumplet buffer structure: buffer end before end of clumplet - no length component can not attach to server - The same result is obtained even with a user name supplied: + The same result is obtained even with a user name supplied: - tux> fbmgr -shut -user sysdba + tux> fbmgr -shut -user sysdba Invalid clumplet buffer structure: buffer end before end of clumplet - no length component can not attach to server -
+
+ + + Document history + + The exact file history is recorded in the manual module in our CVS tree; see http://sourceforge.net/cvs/?group_id=9028. + The full URL of the CVS log for this file can be found at http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/fbutil_fbmgr.xml?view=log + + + + 1.0 + + 29 September 2009 + + ND + + + Created as a chapter in the Command Line Utilities + manual. + + + + + 1.1 + + 11 October 2009 + + ND + + + Some screen output wrapped as it extended out of the page in + the generated pdf. + + + + + 1.2 + + 20 October 2009 + + ND + + + Replaced all references to "root or firebird" account names + with "privileged users" as there are more than just these two + accounts. Converted to a stand alone manual. + + + + + 1.3 + + 21 October 2009 + + ND + + + A few spelling mistakes corrected. + + + + + 1.4 + + 26 October 2009 + + ND + + + The status option to the + rcfirebird command is not available on all + Linux distros. Text amended to warn the reader of this + discrepancy. + + + + + 1.5 + + 11 October 20011 + + ND + + + Spelling corrections. + + + + + + + License notice + + The contents of this Documentation are subject to the Public + Documentation License Version 1.0 (the License); you may + only use this Documentation if you comply with the terms of this License. + Copies of the License are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) and http://www.firebirdsql.org/manual/pdl.html + (HTML). + + The Original Documentation is titled Firebird Superserver + Manager. + + The Initial Writer of the Original Documentation is: Norman + Dunbar. - - Document history - - The exact file history is recorded in the manual module in our CVS tree; see http://sourceforge.net/cvs/?group_id=9028. - The full URL of the CVS log for this file can be found at http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/fbutil_fbmgr.xml?view=log - - - - 1.0 - - 29 September 2009 - - ND - - - Created as a chapter in the Command Line Utilities - manual. - - - - - 1.1 - - 11 October 2009 - - ND - - - Some screen output wrapped as it extended out of the page in - the generated pdf. - - - - - 1.2 - - 20 October 2009 - - ND - - - Replaced all references to "root or firebird" account names - with "privileged users" as there are more than just these two - accounts. Converted to a stand alone manual. - - - - - 1.3 - - 21 October 2009 - - ND - - - A few spelling mistakes corrected. - - - - - 1.4 - - 26 October 2009 - - ND - - - The status option to the -rcfirebird command is not available on all Linux distros. Text amended -to warn the reader of this discrepency. - - - - - - - License notice - - The contents of this Documentation are subject to the Public Documentation - License Version 1.0 (the License); you may only use this - Documentation if you comply with the terms of this License. Copies of the License - are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf - (PDF) and http://www.firebirdsql.org/manual/pdl.html - (HTML). - - The Original Documentation is titled Firebird Superserver - Manager. - - The Initial Writer of the Original Documentation is: Norman Dunbar. - - Copyright (C) 2004–2009. All Rights Reserved. Initial Writer contact: - NormanDunbar at users dot sourceforge dot net. - + Copyright (C) 2004–2009. All Rights Reserved. Initial Writer + contact: NormanDunbar at users dot sourceforge dot net. +
diff --git a/src/docs/firebirddocs/fbutil_gbak.xml b/src/docs/firebirddocs/fbutil_gbak.xml index c7fb8511..c1aab138 100644 --- a/src/docs/firebirddocs/fbutil_gbak.xml +++ b/src/docs/firebirddocs/fbutil_gbak.xml @@ -2,7 +2,7 @@ + -->
Firebird Backup & Restore Utility @@ -17,7 +17,7 @@ Dunbar - 31 March 2011 - Document version 1.5 + 11 October 2011 - Document version 1.6
@@ -64,11 +64,43 @@ are: + + -? + + This switch displays the command line options and switches. It + replaces the old method in which you had to supply an invalid switch + (see -help below) in order to see the list of + valid ones. + + + Firebird 2.5 onwards. + + + + + -FE[TCH_PASSWORD] <password file name> | + stdin | /dev/tty + + This switch causes the password for the appropriate user to be + read from a file as opposed to being specified on the command line. + The file name supplied is not in quotes and + must be readable by the user running + gbak. If the file name is specified as + stdin, then the user will be prompted for a + password. On POSIX systems, the file name /dev/tty will also result in a prompt + for the password. + + + Firebird 2.5 onwards. + + + -M[ETA_DATA] This switch causes your data to be ignored and not backed up - or restored. In a backup, only the database metadata are backed up. + or restored. In a backup, only the database meta data are backed up. When used in a restore, any data in the dump file will not be restored. This switch can be used when creating database clones which are required to contain only the tables, @@ -209,7 +241,7 @@ tux> echo $? password must be defined on the command line, or by the use of environment variables ISC_USER and ISC_PASSWORD. This version of the command will exit - with a erro code of zero. + with a error code of zero. This method of calling gbak @@ -229,7 +261,8 @@ tux> echo $? -help Help is actually not a valid option, but can be used to - display the following screen of information: + display the following screen of information as output from + gbak in Firebird 2.0: @@ -267,6 +300,60 @@ tux> echo $? -Z print version number + + The explanation of the -m[eta_data] + switch implies that it is useful in a backup situation only. This is + not the case as it can also be used on a restore. + + + From Firebird 2.5 onwards, there is a new + -? switch to display the list of valid options. + The output has slightly different layout and a couple of new options + have been added: + + gbak:legal switches are: + -B(ACKUP_DATABASE) backup database to file + -C(REATE_DATABASE) create database from backup file (restore) + -R(ECREATE_DATABASE) [O(VERWRITE)] create (or replace if OVERWRITE used) + database from backup file (restore) + -REP(LACE_DATABASE) replace database from backup file (restore) + +gbak:backup options are: + -CO(NVERT) backup external files as tables + -E(XPAND) no data compression + -FA(CTOR) blocking factor + -G(ARBAGE_COLLECT) inhibit garbage collection + -IG(NORE) ignore bad checksums + -L(IMBO) ignore transactions in limbo + -NOD(BTRIGGERS) do not run database triggers + -NT Non-Transportable backup file format + -OL(D_DESCRIPTIONS) save old style metadata descriptions + -T(RANSPORTABLE) transportable backup -- data in XDR format + +gbak:restore options are: + -BU(FFERS) override page buffers default + -FIX_FSS_D(ATA) fix malformed UNICODE_FSS data + -FIX_FSS_M(ETADATA) fix malformed UNICODE_FSS metadata + -I(NACTIVE) deactivate indexes during restore + -K(ILL) restore without creating shadows + -MO(DE) <access> "read_only" or "read_write" access + -N(O_VALIDITY) do not restore database validity conditions + -O(NE_AT_A_TIME) restore one table at a time + -P(AGE_SIZE) override default page size + -USE_(ALL_SPACE) do not reserve space for record versions + +gbak:general options are: + -FE(TCH_PASSWORD) fetch password from file + -M(ETA_DATA) backup or restore metadata only + -PAS(SWORD) Firebird password + -RO(LE) Firebird SQL role + -SE(RVICE) use services manager + -USER Firebird user name + -V(ERIFY) report each action taken + -Y <path> redirect/suppress status message output + -Z print version number + + The parentheses shown in the above indicates how much of the switch name you need to use in order to avoid ambiguity. Once you have specified the absolute minimum - the part before the opening '[' - you @@ -276,12 +363,6 @@ tux> echo $? between -b and -backup_database will be accepted. - - The explanation of the -m[eta_data] - switch implies that it is useful in a backup situation only. This is - not the case as it can also be used on a restore. - - Using the -help switch like this, or any other invalid switch, will cause gbak to exit with an error code of 1 on Linux and Windows. @@ -338,13 +419,12 @@ tux> echo $? -G[ARBAGE_COLLECT] - Normally gbak will ignore 'garbage' - data when creating the backup. This is useful when you might want to - reduce the size of your database by dumping it, then immediately, - restoring it. (See the manual on gfix for - details of what garbage entails.) The use of this switch prevents - garbage collection from taking place and the resulting dump file is - larger. + The use of this switch prevents Firebird's garbage collection + from taking place while gbak is running. + Normally gbak connects to the database as + any other connection would and garbage collection runs normally. + Using this switch prevents garbage collection from running during + the course of the backup. @@ -392,7 +472,7 @@ tux> echo $? This switch is unlikely to be used. It has been deprecated. Its purpose is to force the backup to be made using the older - InterBase versions' format of metadata descriptions. + InterBase versions' format of meta data descriptions. @@ -490,6 +570,42 @@ tux> echo $? specified. + + -FIX_FSS_D[ATA] + + This switch forces gbak to fix + malformed UNICODE_FSS character data during a restore. + + This switch, and the following one, should not be required + under normal circumstances. However, if a restore operation fails + with a "malformed string" error, the message output from + gbak will refer the user to one or both + of these switches to fix the malformed UNICODE_FSS data or meta data + as appropriate. + + + Firebird 2.5 onwards. + + + + + -FIX_FSS_M[ETADATA] + + This switch forces gbak to fix + malformed UNICODE_FSS metadata during a restore. + + This switch, and the preceding one, should not be required + under normal circumstances. However, if a restore operation fails + with a "malformed string" error, the message output from + gbak will refer the user to one or both + of these switches to fix the malformed UNICODE_FSS data or meta data + as appropriate. + + + Firebird 2.5 onwards. + + + -I[NACTIVE] @@ -797,6 +913,45 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test new name. This way, your users will always refer to the database by the alias regardless of the actual filename on the server.
+ +
+ Malformed String Errors During Restores + + During a restore operation, most likely when restoring a backup + taken using an older gbak version, it is + possible to see failure messages, in gbak's + output, indicating malformed Unicode strings. The reason that these may + occur is as explained by Helen Borrie: + +
+ The source text of stored procedures (and several other types of + object, such as CHECK constraints) is stored in a blob, as is the + "compiled" BLR code. When you restore a database, the BLR is not + recreated: the same BLR is used until next time you recreate or alter + the object. + + Historically, the engine did not do the right thing regarding + the transliteration of strings embedded in the source and the BLR. In + v.2.1 and 2.5 a lot of work was done to address the international + language issues, as you probably know. A side effect of this was that + everything that was read from data and meta data became subject to + "well-formedness" checks. Hence, on restoring, those previously stored + source and BLR objects are throwing "malformed string" errors when + gbak tries to read and write the data in + these system table records. This very old bug affects user blobs, too, + if they have been stored using character set NONE and the client is + configured to read a specified character set to which the stored data + could not be transliterated. + + In v.2.1 there were scripts in ../misc that you could run to repair the + meta data blobs and also use as a template for repairing the similar + errors in blobs in your user data. The repair switches were added to + the gbak restore code in v.2.5 to do the + same corrections to meta data and data, respectively, during the + process of restoring a database for upgrade. +
+
@@ -883,14 +1038,14 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test
- Backup & Restore Recipies + Backup & Restore Recipes - The following recipies show examples of backup and restore tasks + The following recipes show examples of backup and restore tasks using gbak. These are probably the commonest cases that you will encounter as a DBA. All the examples use the employee database supplied with Firebird and the actual location is correctly configured in - aliases.conf. Each of the following recipies is run + aliases.conf. Each of the following recipes is run with the assumption that the environment variables ISC_USER and ISC_PASSWORD have been given suitable values. @@ -927,7 +1082,7 @@ tux> gbak -replace overwrite /backups/employee.fbk employee
- Metadata Only + Meta Data Only It is possible to use gbak to recreate an empty database containing only the various @@ -946,7 +1101,7 @@ tux> gbak -backup -meta_data employee employee.meta.fbk only the meta data will be present. There is another way to create a database with no data and only - the metadata. Simply restore from an existing dump which contains the + the meta data. Simply restore from an existing dump which contains the data and supply the -m[eta_data] switch to the restore command line. The database will be restored but none of the original data will be present. @@ -1373,8 +1528,8 @@ tux> chown firebird:firebird $DBFILE -b[ackup] or -c[reate] etc, then gbak will perform a backup as if the -b[ackup] switch had been specified - - provided that the other switches specified are correct for a backup. - + provided that the other switches specified are correct for a + backup. This detection of whether you are attempting a backup or a @@ -1382,10 +1537,10 @@ tux> chown firebird:firebird $DBFILE line switch to view gbak information, then you will create a backup - and overwrite the backup file you supply - if the command line also has a database name - and a backup file name present. This assums that there is a way for - gbak to deteremine the username and - password to be used - either as command line parameters or via defined - environment variables. + and a backup file name present. This assumes that there is a way for + gbak to determine the username and password + to be used - either as command line parameters or via defined + environment variables.
@@ -1550,6 +1705,23 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log it does carry out a backup. + + + 1.6 + + 11 October 2011 + + ND + + + Updated to cover Firebird 2.5 changes. + + Corrected description of + -g[arbage_collect] switch. + + Lots of spelling mistakes corrected. + + diff --git a/src/docs/firebirddocs/fbutil_gfix.xml b/src/docs/firebirddocs/fbutil_gfix.xml index 8af16186..b7f66603 100644 --- a/src/docs/firebirddocs/fbutil_gfix.xml +++ b/src/docs/firebirddocs/fbutil_gfix.xml @@ -2,239 +2,279 @@ + -->
- Firebird Database Housekeeping Utility + Firebird Database Housekeeping Utility - Gfix - Database Housekeeping + Gfix - Database Housekeeping - - 20 October 2009 + + 20 October 2009 - - Norman + + Norman - Dunbar - + Dunbar + - 25 June 2010 – Document version 1.2 - + 11 October 2011 – Document version 1.3 + -
- Introduction +
+ Introduction - Gfix allows attempts to fix corrupted databases, - starting and stopping of databases, resolving 'in limbo' transactions between - multiple databases, changing the number of page buffers and so on. - Gfix is a general purpose tool for system - administrators (and database owners) to use to make various 'system level' changes - to their databases. + Gfix allows attempts to fix corrupted + databases, starting and stopping of databases, resolving 'in limbo' + transactions between multiple databases, changing the number of page + buffers and so on. Gfix is a general purpose + tool for system administrators (and database owners) to use to make + various 'system level' changes to their databases. - Almost all the gfix commands have the same format - when typed on the command line: + Almost all the gfix commands have the + same format when typed on the command line: - gfix [commands and parameters] database_name + gfix [commands and parameters] + database_name - The commands and their options are described in the following sections. The - database name is the name of the primary database file which - for a single file database is simply the database name and for multi-file - databases, it is the first data file added. + The commands and their options are described in the following + sections. The database name is the name of the + primary database file which for a single file + database is simply the database name and for multi-file databases, it is + the first data file added. - Coming up in the remainder of this manual, we will discuss the - following: + Coming up in the remainder of this manual, we will discuss the + following: - - - Command line options for the gfix - database utility. - + + + Command line options for the gfix + database utility. + - - Shadow file handling. - + + Shadow file handling. + - - Cache and buffer handling. - + + Cache and buffer handling. + - - Transaction management. - + + Transaction management. + - - Cache management. - + + Cache management. + - - Starting and stopping a database. - + + Starting and stopping a database. + - - And much, much more ... - - -
+ + And much, much more ... + + +
-
- Command Line Options +
+ Command Line Options - Running gfix without a command (or an invalid - command) results in the following screen of helpful information being - displayed: + Running gfix without a command (or an + invalid command), or with the new -? switch in + Firebird 2.5, results in the following screen of helpful information being + displayed: - invalid switch --help -please retry, specifying an option + usage: gfix [options] <database> plausible options are: - -activate activate shadow file for database usage - -attach shutdown new database attachments - -buffers set page buffers <n> - -commit commit transaction <tr / all> - -cache shutdown cache manager - -full validate record fragments (-v) - -force force database shutdown - -housekeeping set sweep interval <n> - -ignore ignore checksum errors - -kill kill all unavailable shadow files - -list show limbo transactions - -mend prepare corrupt database for backup - -mode read_only or read_write - -no_update read-only validation (-v) - -online database online <single / multi / normal> - -prompt prompt for commit/rollback (-l) - -password default password - -rollback rollback transaction <tr / all> - -sql_dialect set database dialect n - -sweep force garbage collection - -shut shutdown <full / single / multi> - -two_phase perform automated two-phase recovery - -tran shutdown transaction startup - -use use full or reserve space for versions - -user default user name - -validate validate database structure - -write write synchronously or asynchronously - -z print software version number - - qualifiers show the major option in parenthesis -
+ -activate activate shadow file for database usage + -attach shutdown new database attachments + -buffers set page buffers <n> + -commit commit transaction <tr / all> + -cache shutdown cache manager + -full validate record fragments (-v) + -force force database shutdown + -fetch_password fetch_password from file + -housekeeping set sweep interval <n> + -ignore ignore checksum errors + -kill kill all unavailable shadow files + -list show limbo transactions + -mend prepare corrupt database for backup + -mode read_only or read_write + -no_update read-only validation (-v) + -online database online <single / multi / normal> + -prompt prompt for commit/rollback (-l) + -password default password + -rollback rollback transaction <tr / all> + -sql_dialect set database dialect n + -sweep force garbage collection + -shut shutdown <full / single / multi> + -two_phase perform automated two-phase recovery + -tran shutdown transaction startup + -use use full or reserve space for versions + -user default user name + -validate validate database structure + -write write synchronously or asynchronously + -z print software version number + + qualifiers show the major option in parenthesis + +
+ +
+ <application>Gfix</application> Commands + + + In the following discussion, I use the full parameter names in all + examples. This is not necessary as each command can be abbreviated. When + the command is shown with '[' and ']' in the name then these are the + optional characters. + + For example, the command -validate is shown + as -v[alidate] and so can be specified as + -v, -va, + -val and so on up to the full + -validate version. + + + For almost all of the options in the following sections, two of the + above command line options will be required. These are + -u[ser] and -pa[ssword]. + These can be supplied for every command as parameters on the command line, + or can be configured once in a pair of environment variables. + + + + -? + + This switch displays the command line options and switches. It + replaces the old method in which you had to supply an invalid switch + (such as -help) in order to see the list of + valid ones. + + + Firebird 2.5 onwards. + + + + + -FE[TCH_PASSWORD] <password file name> | stdin + | /dev/tty + + This switch causes the password for the appropriate user to be + read from a file as opposed to being specified on the command line. + The file name supplied is not in quotes and must + be readable by the user running gfix. If + the file name is specified as stdin, then the + user will be prompted for a password. On POSIX systems, the file name + /dev/tty will also result in a + prompt for the password. -
- <application>Gfix</application> Commands + + Firebird 2.5 onwards. + + + + + -u[ser] username + + Allows the username of the SYSDBA user, or the owner of the + database to be specified This need not be supplied if the + ISC_USER environment variable has been defined and has + the correct value. + + + + -pa[ssword] password + + Supplies the password for the username specified above. This + need not be supplied if the ISC_PASSWORD environment + variable has been defined and have the correct value. - In the following discussion, I use the full parameter names in all - examples. This is not necessary as each command can be abbreviated. When the - command is shown with '[' and ']' in the name then these are the optional - characters. - - For example, the command -validate is shown as - -v[alidate] and so can be specified as - -v, -va, - -val and so on up to the full - -validate version. + Up until Firebird 2, any utility which was executed with a + password on the command line could result in other users of the + server seeing that password using a command like ps -efx | + grep -i pass. From Firebird 2 onwards, this is no longer + the case as the password on the command line can no longer be seen + by the ps (or other) commands. + + - For almost all of the options in the following sections, two of the above - command line options will be required. These are -u[ser] - and -pa[ssword]. These can be supplied for every command as - parameters on the command line, or can be configured once in a pair of environment - variables. - - - - -u[ser] username - - Allows the username of the SYSDBA user, or the owner of the database - to be specified This need not be supplied if the ISC_USER - environment variable has been defined and has the correct value. - - - - -pa[ssword] password - - Supplies the password for the username specified above. This need - not be supplied if the ISC_PASSWORD environment variable - has been defined and have the correct value. - - - Up until Firebird 2, any utility which was executed with a - password on the command line could result in other users of the server - seeing that password using a command like ps -efx | grep -i - pass. From Firbird 2 onwards, this is no longer the case as - the password on the command line can no longer be seen by the - ps (or other) commands. - - - - - To define the username and password as environment variables on a Linux - system: - - linux> export ISC_USER=sysdba + To define the username and password as environment variables on a + Linux system: + + linux> export ISC_USER=sysdba linux> export ISC_PASSWORD=masterkey - Alternatively, on Windows: + Alternatively, on Windows: - C:\> set ISC_USER=sysdba + C:\> set ISC_USER=sysdba C:\> set ISC_PASSWORD=masterkey - - This is very insecure as it allows anyone who can access your session - the ability to perform DBA functions that you might not want to allow. - + + This is very insecure as it allows anyone who can access your + session the ability to perform DBA functions that you might not want to + allow. + - - - -u[ser] default user name - + + + -u[ser] default user name + - - -pa[ssword] default password - - + + -pa[ssword] default password + + - If you have not defined the above environment variables, some commands will - not work unless you supply -u[ser] and - -pa[ssword] on the command line. For example: + If you have not defined the above environment variables, some + commands will not work unless you supply -u[ser] + and -pa[ssword] on the command line. For + example: - linux> gfix -validate my_employee + linux> gfix -validate my_employee linux> Unable to perform operation. You must be either SYSDBA - or owner of the database - - The line that starts with 'Unable to perform' above, has had to be split - to fit on the page of the PDF file. In reality, it is a single line. - + + The line that starts with 'Unable to perform' above, has had to be + split to fit on the page of the PDF file. In reality, it is a single + line. + - However, passing the username and password works: + However, passing the username and password works: - linux> gfix -validate my_employee -user sysdba -password masterkey + linux> gfix -validate my_employee -user sysdba -password masterkey - You will notice, hopefully, that some commands do not give any printed - output at all. gfix, in the main, only reports when - problems are encountered. Always check the response code returned by - gfix to be sure that it worked. However, see the - caveats section below for details because it looks like the response code is - always zero - at least up until Firebird 2.0. + You will notice, hopefully, that some commands do not give any + printed output at all. gfix, in the main, only + reports when problems are encountered. Always check the response code + returned by gfix to be sure that it worked. + However, see the caveats section below for details because it looks like + the response code is always zero - at least up until Firebird 2.0. - - When logging into a database on a remote server, you will always be - required to pass the -u[ser] and - -pa[ssword] parameters. - -
+ + When logging into a database on a remote server, you will always + be required to pass the -u[ser] and + -pa[ssword] parameters. + +
-
- Shadow Files +
+ Shadow Files - A shadow file is an additional copy of the primary database file(s). More - than one shadow file may exist for any given database and these may be activated - and de-activated at will using the gfix utility. + A shadow file is an additional copy of the primary database file(s). + More than one shadow file may exist for any given database and these may + be activated and de-activated at will using the gfix + utility. - The following descriptions of activating and de-activating shadow files - assume that a shadow file already exists for the database. To this end, a shadow - was created as follows: + The following descriptions of activating and de-activating shadow + files assume that a shadow file already exists for the database. To this + end, a shadow was created as follows: - + linux> isql my_employee; SQL> create shadow 1 manual '/home/norman/firebird/shadow/my_employee.shd1'; SQL> create shadow 2 manual '/home/norman/firebird/shadow/my_employee.shd2'; @@ -248,85 +288,91 @@ Database: my_employee SQL> quit; - It can be seen that the database now has two separate shadow files created, - but as they are manual, they have not been activated. We can see that shadows are - in use if we use gstat as follows: + It can be seen that the database now has two separate shadow files + created, but as they are manual, they have not been activated. We can see + that shadows are in use if we use gstat as + follows: - linux> gstat -header my_employee | grep -i shadow + linux> gstat -header my_employee | grep -i shadow Shadow count 2 - - Sometimes, it takes gstat a while to figure - out that there are shadow files for the database. - + + Sometimes, it takes gstat a while to + figure out that there are shadow files for the database. + - - Shadow file details can be found in the RDB$FILES - table within the database. - + + Shadow file details can be found in the + RDB$FILES table within the database. + -
- Activating Shadows +
+ Activating Shadows - The command to activate a database shadow is: + The command to activate a database shadow is: - gfix -ac[tivate] <shadow_file_name> + gfix -ac[tivate] + <shadow_file_name> - This makes the shadow file the new database file and the users are able - to continue processing data as normal and without loss. + This makes the shadow file the new database file and the users are + able to continue processing data as normal and without loss. - In the event that your main database file(s) become corrupted or - unreadable, the DBA can activate a shadow file. Once activated, the file is no - longer a shadow file and a new one should be created to replace it. - Additionally, the shadow file should be renamed (at the operating system - prompt) to the name of the old database file that it replaces. + In the event that your main database file(s) become corrupted or + unreadable, the DBA can activate a shadow file. Once activated, the file + is no longer a shadow file and a new one should be created to replace + it. Additionally, the shadow file should be renamed (at the operating + system prompt) to the name of the old database file that it + replaces. - - It should be noted that activating a shadow while the database - itself is active can lead to corruption of the shadow. Make sure that the - database file is really unavailable before activating a shadow. - + + It should be noted that activating a shadow while the database + itself is active can lead to corruption of the shadow. Make sure that + the database file is really unavailable before activating a + shadow. + - Once a shadow file has been activated, you can see the fact that there - are active shadows in the output from gstat: + Once a shadow file has been activated, you can see the fact that + there are active shadows in the output from + gstat: - linux> gstat -header my_employee | grep -i shadow + linux> gstat -header my_employee | grep -i shadow Shadow count 2 Attributes active shadow, multi-user maintenance - - The DBA can set up the database to automatically create a new shadow - file in the event of a current shadow being activated. This allows a - continuous supply of shadow files and prevents the database ever running - without one. - -
+ + The DBA can set up the database to automatically create a new + shadow file in the event of a current shadow being activated. This + allows a continuous supply of shadow files and prevents the database + ever running without one. + +
-
- Killing Shadows +
+ Killing Shadows - The command to kill all unavailable database - shadows, for a specific database, is: + The command to kill all unavailable database + shadows, for a specific database, is: - gfix -k[ill] database_name + gfix -k[ill] database_name - In the event that a database running with shadow files loses a shadow, - or a shadow becomes unusable for some reason, the database will stop accepting - new connections until such time as the DBA kills the faulty shadow and, - ideally, creates a new shadow to replace the broken one. + In the event that a database running with shadow files loses a + shadow, or a shadow becomes unusable for some reason, the database will + stop accepting new connections until such time as the DBA kills the + faulty shadow and, ideally, creates a new shadow to replace the broken + one. - The following (contrived) example, shows what happens when the database - loses a shadow file and an attempt is made to connect to that database. There - are two sessions in the following example, one is connected to the database - while the second deletes a shadow file and then tries to connect to the - database. The command line prompts shows which of the two sessions we are - using at the time. + The following (contrived) example, shows what happens when the + database loses a shadow file and an attempt is made to connect to that + database. There are two sessions in the following example, one is + connected to the database while the second deletes a shadow file and + then tries to connect to the database. The command line prompts shows + which of the two sessions we are using at the time. - First, the initial session is connected to the database and can see that - there are two shadow files attached: + First, the initial session is connected to the database and can + see that there are two shadow files attached: - linux_1>isql my_employee + linux_1>isql my_employee Database: my_employee SQL> show database; Database: my_employee @@ -335,10 +381,10 @@ Shadow 1: "/home/norman/firebird/shadow/my_employee.shd1" manual Shadow 2: "/home/norman/firebird/shadow/my_employee.shd2" manual ... - In the second session, we delete one of the shadow files, and then try - to connect to the database + In the second session, we delete one of the shadow files, and then + try to connect to the database - linux_2> rm /home/norman/firebird/shadow/my_employee.shd2 + linux_2> rm /home/norman/firebird/shadow/my_employee.shd2 linux_2> isql_my_employee Statement failed, SQLCODE = -901 lock conflict on no wait transaction @@ -349,12 +395,13 @@ lock conflict on no wait transaction Use CONNECT or CREATE DATABASE to specify a database SQL> quit; - The second session cannot connect to the database until the problem is - fixed. The DBA would use the gfix -k[ill] command to remove - details of the problem shadow file from the database and once completed, the - second (and subsequent) sessions would be able to connect. + The second session cannot connect to the database until the + problem is fixed. The DBA would use the gfix -k[ill] + command to remove details of the problem shadow file from the database + and once completed, the second (and subsequent) sessions would be able + to connect. - linux_2> gfix -kill my_employee + linux_2> gfix -kill my_employee linux_2> isql my_employee Database: my_employee @@ -364,123 +411,129 @@ Database: my_employee Shadow 1: "/home/norman/firebird/shadow/my_employee.shd1" manual ... - The database now has a single shadow file where before it had two. It is - noted, however, that gstat still shows the database - as having two shadows, even when one has been removed. + The database now has a single shadow file where before it had two. + It is noted, however, that gstat still shows + the database as having two shadows, even when one has been + removed. - linux> gstat -header my_employee | grep -i shadow + linux> gstat -header my_employee | grep -i shadow Shadow count 2 Attributes active shadow, multi-user maintenance - - In addition to the above strange result, if I subsequently - DROP SHADOW 1 and COMMIT, to - remove the remaining shadow file, gstat now - shows that the shadow count has gone up to three when it should have gone - down to zero! - -
+ + In addition to the above strange result, if I subsequently + DROP SHADOW 1 and COMMIT, to + remove the remaining shadow file, gstat now + shows that the shadow count has gone up to three when it should have + gone down to zero! +
+
-
- Set Database Page Buffers +
+ Set Database Page Buffers - The database cache is an area of RAM allocated to store (cache) database - pages in memory to help improve the efficiency of the database performance. It is - far quicker to read data from memory that it is to have to physically read the - data from disc. + The database cache is an area of RAM allocated to store (cache) + database pages in memory to help improve the efficiency of the database + performance. It is far quicker to read data from memory that it is to have + to physically read the data from disc. - The size of the database cache is dependent on the database page size and - the number of buffers allocated, a buffer is the same size as a database page, and - whether the installation is using Classic or Superserver versions of - Firebird. + The size of the database cache is dependent on the database page + size and the number of buffers allocated, a buffer is the same size as a + database page, and whether the installation is using Classic or + Superserver versions of Firebird. - In a Classic Server installation, each connection to the database gets its - own relatively small cache of 75 pages while Superserver creates a much larger - cache of 2,048 pages which is shared between all the connections. + In a Classic Server installation, each connection to the database + gets its own relatively small cache of 75 pages while Superserver creates + a much larger cache of 2,048 pages which is shared between all the + connections. - The command to set the number of cache pages is: + The command to set the number of cache pages is: - gfix -b[uffers] BUFFERS database_name + gfix -b[uffers] BUFFERS database_name - This command allows you to change the number of buffers (pages) allocated in - RAM to create the database cache. + This command allows you to change the number of buffers (pages) + allocated in RAM to create the database cache. - You cannot change the database page size in this manner, only the number of - pages reserved in RAM. One parameter is required which must be numeric and between - 50 (the minimum) and 131,072 (the maximum). + You cannot change the database page size in this manner, only the + number of pages reserved in RAM. One parameter is required which must be + numeric and between 50 (the minimum) and 131,072 (the maximum). - The setting applies only to the database you specify. No other databases - running on the same server are affected. + The setting applies only to the database you specify. No other + databases running on the same server are affected. - The following example shows the use of gstat to - read the current number of buffers, the gfix utility - being used to set the buffers to 4,000 pages and gstat - being used to confirm the setting. The value of zero for page buffers indicates - the default setting for the server type is in use. + The following example shows the use of + gstat to read the current number of buffers, + the gfix utility being used to set the buffers + to 4,000 pages and gstat being used to confirm + the setting. The value of zero for page buffers indicates the default + setting for the server type is in use. - - You can use the gstat command line utility to - display the database details with the command line: gstat -header - db_name however, to run gstat, you need - to be logged into the server - it cannot be used remotely. - + + You can use the gstat command line + utility to display the database details with the command line: + gstat -header db_name however, to run + gstat, you need to be logged into the server + - it cannot be used remotely. + - linux> gstat -header my_employee | grep -i "page buffers" + linux> gstat -header my_employee | grep -i "page buffers" Page buffers 0 linux> gfix -buffers 4000 my_employee linux> gstat -header my_employee | grep -i "page buffers" Page buffers 4000 -
- -
- Limbo Transaction Management - - Limbo transactions can occur when an application is updating two (or more) - databases at the same time, in the same transaction. At - COMMIT time, Firebird will prepare each database for the - COMMIT and then COMMIT each database - separately. - - In the event of a network outage, for example, it is possible for part of - the transaction to have been committed on one database but the data on the other - database(s) may not have been committed. Because Firebird cannot tell if these - transactions (technically sub-transactions) should be committed or rolled back, - they are flagged as being in limbo. - - Gfix offers a number of commands to allow the - management of these limbo transactions. - - - The following examples of limbo transactions are based on Firebird 1.5 - and have kindly been provided by Paul Vinkenoog. Because of the limitation of - my setup, I am unable to create limbo transactions in my current - location. - - In the spirit of consistency, however, I have renamed Paul's servers and - database locations to match the remainder of this document. - - -
- Listing Limbo Transactions - - The gfix command - -l[ist] will display details of transactions that are - in limbo. If there is no output, then there are no transactions in limbo and - no further work need be done. The command is: - - gfix -l[ist] database_name - - An example of listing limbo transactions is shown below. This command is - run against the local database on the server named linux where a - multi-database transaction had been run connected to databases - linux@my_employee and - remote:testlimbo. Both of these database names are - aliases. - - linux> gfix -list my_employee +
+ +
+ Limbo Transaction Management + + Limbo transactions can occur when an application is updating two (or + more) databases at the same time, in the same transaction. At + COMMIT time, Firebird will prepare each database for + the COMMIT and then COMMIT each + database separately. + + In the event of a network outage, for example, it is possible for + part of the transaction to have been committed on one database but the + data on the other database(s) may not have been committed. Because + Firebird cannot tell if these transactions (technically sub-transactions) + should be committed or rolled back, they are flagged as being in + limbo. + + Gfix offers a number of commands to allow + the management of these limbo transactions. + + + The following examples of limbo transactions are based on Firebird + 1.5 and have kindly been provided by Paul Vinkenoog. Because of the + limitation of my setup, I am unable to create limbo transactions in my + current location. + + In the spirit of consistency, however, I have renamed Paul's + servers and database locations to match the remainder of this + document. + + +
+ Listing Limbo Transactions + + The gfix command + -l[ist] will display details of transactions that + are in limbo. If there is no output, then there are no transactions in + limbo and no further work need be done. The command is: + + gfix -l[ist] database_name + + An example of listing limbo transactions is shown below. This + command is run against the local database on the server named linux + where a multi-database transaction had been run connected to databases + linux@my_employee and + remote:testlimbo. Both of these database names are + aliases. + + linux> gfix -list my_employee Transaction 67 is in limbo. Multidatabase transaction: Host Site: linux @@ -489,21 +542,21 @@ has been prepared. Remote Site: remote Database path: /opt/firebird/examples/testlimbo.fdb - If the command is run against the remote database then nothing will be - listed because that database does not have any limbo transactions - the - transaction that went into limbo, when the network failed, for example, was - initiated on the local database. + If the command is run against the remote database then nothing + will be listed because that database does not have any limbo + transactions - the transaction that went into limbo, when the network + failed, for example, was initiated on the local database. - You may also supply the -p[rompt] option to the - command and you will be prompted to COMMIT or - ROLLBACK each detected limbo transaction. In this case, - the command would be: + You may also supply the -p[rompt] option to + the command and you will be prompted to COMMIT or + ROLLBACK each detected limbo transaction. In this + case, the command would be: - gfix -l[ist] -p[rompt] database_name + gfix -l[ist] -p[rompt] database_name - An example of this is shown below. + An example of this is shown below. - linux> gfix -list -prompt my_employee + linux> gfix -list -prompt my_employee Transaction 67 is in limbo. Multidatabase transaction: Host Site: linux @@ -512,163 +565,172 @@ has been prepared. Remote Site: remote Database path: /opt/firebird/examples/testlimbo.fdb Commit, rollback or neither (c, r, or n)? -
+
-
- Committing Or Rolling Back +
+ Committing Or Rolling Back - When a limbo transaction has been detected, the DBA has the option of - committing or rolling back one or more of the transactions reported as being - in limbo. + When a limbo transaction has been detected, the DBA has the option + of committing or rolling back one or more of the transactions reported + as being in limbo. - When more than one transaction is listed, the DBA can either commit or - roll back all transactions in limbo, or a specific transaction number. + When more than one transaction is listed, the DBA can either + commit or roll back all transactions in limbo, or a specific transaction + number. - The following commands show the -c[ommit] option - being used, but the -r[ollback] option applies as well, - it all depends on what the DBA is trying to achieve. + The following commands show the -c[ommit] + option being used, but the -r[ollback] option + applies as well, it all depends on what the DBA is trying to + achieve. - To commit every limbo transaction on the database, the following command - would be used: + To commit every limbo transaction on the database, the following + command would be used: - gfix -commit all database_name + gfix -commit all database_name - If the DBA wanted to commit a single transaction, then the command would - change to the following: + If the DBA wanted to commit a single transaction, then the command + would change to the following: - gfix -commit TXN database_name + gfix -commit TXN database_name - Where TXN is the transaction number to be committed. + Where TXN is the transaction number to be committed. - When either of these options are user, there is no feedback from gfix to - advise you that the commit actually worked. You would need to rerun the - gfix -list command to make sure that all, or the selected, - limbo transactions had indeed gone. + When either of these options are user, there is no feedback from + gfix to advise you that the commit actually worked. You would need to + rerun the gfix -list command to make sure that all, + or the selected, limbo transactions had indeed gone. - You cannot commit or rollback a transaction that is not in limbo. If you - try , the following will occur: + You cannot commit or rollback a transaction that is not in limbo. + If you try , the following will occur: - linux> gfix -commit 388 my_employee + linux> gfix -commit 388 my_employee failed to reconnect to a transaction in database my_employee transaction is not in limbo -transaction 388 is active unknown ISC error 0 - When committing or rolling back all limbo transactions, the - -p[rompt] option can be specified. It is, however, not - permitted when processing a single transaction. An example of using the - -p[rompt] option has been shown above under listing - limbo transactions. -
+ When committing or rolling back all limbo transactions, the + -p[rompt] option can be specified. It is, + however, not permitted when processing a single transaction. An example + of using the -p[rompt] option has been shown + above under listing limbo transactions. +
-
- Automatic Two-phase Recovery +
+ Automatic Two-phase Recovery - Gfix can be used to perform automatic - two-phase recovery. The command for this is - -t[wo_phase] and, like -c[ommit] - and -r[ollback] above, requires either 'all' or a - transaction number. + Gfix can be used to perform automatic + two-phase recovery. The command for this is + -t[wo_phase] and, like + -c[ommit] and -r[ollback] + above, requires either 'all' or a transaction number. - The output of the -l[ist] command shows what will - happen to each listed transaction in the event that the DBA runs the - -t[wo_phase] command. + The output of the -l[ist] command shows + what will happen to each listed transaction in the event that the DBA + runs the -t[wo_phase] command. - The command also takes the -p[rompt] option, as - above, when used to process all transaction. + The command also takes the -p[rompt] + option, as above, when used to process all transaction. - The command line to carry out automatic two-phase recovery is: + The command line to carry out automatic two-phase recovery + is: - gfix -t[wo_phase] TXN database_name or + gfix -t[wo_phase] TXN database_name or - gfix -t[wo_phase] all database_name + gfix -t[wo_phase] all database_name - As above, TXN is a single transaction number from the list of limbo - transactions. + As above, TXN is a single transaction number from the list of + limbo transactions. - - Paul has noted that when using the -c[ommit], - -r[ollback] or -t[wo_phase] - options, the output is exactly the same and appears to show that these - three are all just synonyms for the -l[ist] - -p[rompt] pair of options. This occurred whether or not Paul - used the transaction number, 67, or 'all' in the command line. - -
+ + Paul has noted that when using the + -c[ommit], -r[ollback] + or -t[wo_phase] options, the output is exactly + the same and appears to show that these three are all just synonyms + for the -l[ist] -p[rompt] pair of options. This + occurred whether or not Paul used the transaction number, 67, or 'all' + in the command line. +
+
-
- Cache Manager +
+ Cache Manager - When the help page for gfix is displayed there is - a message in the output for the -ca[che] option which - states: + When the help page for gfix is displayed + there is a message in the output for the -ca[che] + option which states: - ... + ... -ca[che] shutdown cache manager ... - However, when called this option simply displays the help page again. + However, when called this option simply displays the help page + again. - The question that immediately springs to my mind is, if we can shutdown the - cache manager with this option, how do we start it back up again? -
+ The question that immediately springs to my mind is, if we can + shutdown the cache manager with this option, how do we start it back up + again? +
-
- Changing The Database Mode +
+ Changing The Database Mode - Databases can be set to run in one of two modes, read only - where no - updates are permitted, and read/write - where both reading and writing of data is - permitted. By default, Firebird creates read/write databases and as such, all - read/write databases must be placed on a file system which allows writing to take - place. + Databases can be set to run in one of two modes, read only - where + no updates are permitted, and read/write - where both reading and writing + of data is permitted. By default, Firebird creates read/write databases + and as such, all read/write databases must be placed on a file system + which allows writing to take place. - Should you wish to put a Firebird database on a CD, for example, you - wouldn't be able to do so. After a new database has been populated with data it - can be changed to read only mode, and then used on a CD (or other read only file - systems) with no problems. + Should you wish to put a Firebird database on a CD, for example, you + wouldn't be able to do so. After a new database has been populated with + data it can be changed to read only mode, and then used on a CD (or other + read only file systems) with no problems. - - Firebird uses SQL internally to maintain its - internal structures with details about transactions, for example, and this is - the reason that a database must be placed on a read/write file system - regardless of whether only SELECT statements are run or - not. - + + Firebird uses SQL internally to maintain its + internal structures with details about transactions, for example, and + this is the reason that a database must be placed on a read/write file + system regardless of whether only SELECT statements + are run or not. + - - Only databases in dialect 3 can be changed to read only mode. - + + Only databases in dialect 3 can be changed to read only + mode. + - The command to set the required mode for a database is: + The command to set the required mode for a database is: - gfix -mo[de] MODE database_name + gfix -mo[de] MODE database_name - The command takes two parameters, the MODE which must be one of the - following: + The command takes two parameters, the MODE which must be one of the + following: - - - read_only - the database cannot be written - to. - + + + read_only - the database cannot be + written to. + - - read_write - the database can be written - to. - - + + read_write - the database can be written + to. + + - The meaning of the two modes should be quite meaningful. + The meaning of the two modes should be quite meaningful. - The second parameter is a database name to apply the mode change to. + The second parameter is a database name to apply the mode change + to. - The following example shows how to put a database into read only mode, and - then change it back again. The example also shows what happens when you try to - update the database while running in read only mode. + The following example shows how to put a database into read only + mode, and then change it back again. The example also shows what happens + when you try to update the database while running in read only + mode. - linux> gfix -mode read_only my_employee + linux> gfix -mode read_only my_employee linux> isql my_employee Database: my_employee @@ -692,11 +754,11 @@ STUFF INTEGER Nullable SQL> quit; - If there are any connections to the database in read/write mode when you - attempt to convert the database to read only, the attempt will fail as shown below - with Firebird 1.5. + If there are any connections to the database in read/write mode when + you attempt to convert the database to read only, the attempt will fail as + shown below with Firebird 1.5. - linux> gfix -mode read_only my_employee + linux> gfix -mode read_only my_employee lock time-out on wait transaction -lock time-out on wait transaction -object my_employee is in use @@ -704,70 +766,72 @@ lock time-out on wait transaction linux> echo $? 0 - - As with many failures of gfix, the response - code returned to the operating system is zero. - + + As with many failures of gfix, the + response code returned to the operating system is zero. + - Under Firebird 2, the error message is more self explanatory: + Under Firebird 2, the error message is more self explanatory: - linux> gfix -mode read_only my_employee + linux> gfix -mode read_only my_employee lock time-out on wait transaction -object /opt/firebird/databases/my_employee.fdb is in use linux> echo $? 0 -
- -
- Setting The Database Dialect - - The dialect of the database is simply a term that defines the specific - features of the SQL language that are available when - accessing that database. There are three dialects at present (Firebird version - 2.0), these are: - - - - Dialect 1 stores date and time information in a - DATE data type and has a - TIMESTAMP data type which is identical to DATE. - Double quotes are used to delimit string data. The precision for - NUMERIC and DECIMAL data types - is less than a dialect 3 database and if the precision is greater than 9, - Firebird stores these as DOUBLE PRECISION. - INT64 is not permitted as a data type. - - - - Dialect 2 is available only on the Firebird client connection and - cannot be set in the database. It is intended to assist debugging of - possible problems with legacy data when migrating a database from dialect - 1 to 3. This dialect cannot be set for a database using - gfix. (See below.) - - - - Dialect 3 databases allow numbers (DECIMAL and - NUMERIC data types) to be stored as - INT64 when the precision is greater than 9. The - TIME data type is able to be used and stores time - data only. The DATE data type stores on date - information. Double quotes can be used but only for identifiers that are - case dependent, not for string data which has to use single quotes. - - - - The command to change the SQL dialect for a database is: - - gfix -s[ql_dialect] DIALECT database_name - - The DIALECT parameter is simply 1 or 3. - - The following example changes a database to use dialect 3 which will allow - many newer features of SQL 92 to be used. - - linux> gfix -sql_dialect 3 my_employee +
+ +
+ Setting The Database Dialect + + The dialect of the database is simply a term that defines the + specific features of the SQL language that are + available when accessing that database. There are three dialects at + present (Firebird version 2.0), these are: + + + + Dialect 1 stores date and time information in a + DATE data type and has a + TIMESTAMP data type which is identical to DATE. + Double quotes are used to delimit string data. The precision for + NUMERIC and DECIMAL data + types is less than a dialect 3 database and if the precision is + greater than 9, Firebird stores these as DOUBLE + PRECISION. INT64 is not permitted as a + data type. + + + + Dialect 2 is available only on the Firebird client connection + and cannot be set in the database. It is intended to assist debugging + of possible problems with legacy data when migrating a database from + dialect 1 to 3. This dialect cannot be set for a database using + gfix. (See below.) + + + + Dialect 3 databases allow numbers (DECIMAL + and NUMERIC data types) to be stored as + INT64 when the precision is greater than 9. The + TIME data type is able to be used and stores time + data only. The DATE data type stores on date + information. Double quotes can be used but only for identifiers that + are case dependent, not for string data which has to use single + quotes. + + + + The command to change the SQL dialect for a database is: + + gfix -s[ql_dialect] DIALECT database_name + + The DIALECT parameter is simply 1 or 3. + + The following example changes a database to use dialect 3 which will + allow many newer features of SQL 92 to be used. + + linux> gfix -sql_dialect 3 my_employee linux> gstat -header my_employee | grep dialect Database dialect 3 @@ -777,30 +841,31 @@ linux> gfix -sql_dialect 1 my_employee linux> gstat -header my_employee | grep dialect Database dialect 1 - Because you cannot use gstat remotely, you may - also use the isql command SHOW SQL - DIALECT from a remote location to see which dialect your client and - database are using, as follows: + Because you cannot use gstat remotely, + you may also use the isql command + SHOW SQL DIALECT from a remote location to see which + dialect your client and database are using, as follows: - remote> isql my_employee -user norman -password whatever + remote> isql my_employee -user norman -password whatever Database: my_employee SQL> show sql dialect; Client SQL dialect is set to: 3 and database SQL dialect is: 3 - Although dialect 2 is possible on the client, trying to set a dialect of 2 - will fail on the server as the following example shows. + Although dialect 2 is possible on the client, trying to set a + dialect of 2 will fail on the server as the following example + shows. - linux> gfix -sql_dialect 2 my_employee + linux> gfix -sql_dialect 2 my_employee Database dialect 2 is not a valid dialect. -Valid database dialects are 1 and 3. -Database dialect not changed. - To set dialect 2 for your client connection, you use - isql as follows: + To set dialect 2 for your client connection, + you use isql as follows: - linux> isql my_employee + linux> isql my_employee Database: my_employee SQL> set sql dialect 2; @@ -810,327 +875,335 @@ to Database SQL dialect 3 database. SQL> show sql dialect; Client SQL dialect is set to: 2 and database SQL dialect is: 3 - - The WARNING line above has had to be split to fit on the page of the PDF - version of this manual. In reality, it is a single line of text. - + + The WARNING line above has had to be split to fit on the page of + the PDF version of this manual. In reality, it is a single line of + text. + +
+ +
+ Database Housekeeping And Garbage Collection + + DB Housekeeping and Garbage Collection + +
+ Garbage + + Garbage, for want of a better name, is the detritus that Firebird + leaves around in the database after a rollback has been carried out. + This is basically a copy of the row(s) from the table(s) that were being + updated (or deleted) by the transaction prior to the rollback. + + Because Firebird uses multi-generational architecture, every time + a row is updated or deleted, Firebird keeps a copy in the database. + These copies use space in the pages and can remain in the database for + some time. + + In addition to taking up space in the database, these old copies + can lead to increased transaction startup times. + + There are two types of garbage: + + + + Remnants from a committed transaction. + + + + Remnants from an aborted (rolled back) transaction. + + These remnants are simply older copies of the rows that + were being updated by the respective transactions. The differences are + that: + + + + Whenever a subsequent transaction reaches garbage from a + committed transaction, that garbage is + automatically cleared out. + + + + Rolled back garbage is never + automatically cleared out. + + This means that on a database with a lot of rolled back + transactions, there could be a large build up of old copies of the rows + that were updated and then rolled back. + + Firebird will automatically sweep through the database and remove + the remnants of rolled back transactions and this has two + effects: + + + + The database size is reduced as the old copies of rows are + deleted. + + + + The performance of the database may be affected while the + sweep is in progress. + + + + + One other method of clearing out old rolled back transactions' + garbage is simply to carry out a database backup. + + + In the Super Server version of Firebird 2.0, garbage collection + has been vastly improved. There are now three different ways of + operation and these are configurable by setting the + GCPOLICY parameter in the + firebird.conf configuration file. By default, Super + Server uses combined while Classic Server uses + cooperative. The other option is + background. + + + Classic Server ignores the setting and always uses cooperative + garbage collection. + + +
+ Cooperative Garbage Collection + + This is the default setting, indeed the only setting, that + Classic Server uses. In this mode, the normal operation - as described + above - takes place. When a full scan is performed (perhaps during a + backup) old versions of the rows are deleted at that point in + time. +
+ +
+ Background garbage Collection + + Super Server has, even since before version 1.0, performed + background garbage collection where the server informs the garbage + collector about old versions of updated and deleted rows when they are + ready to be cleaned up. This helps avoid the need to force a full scan + of each record in the database tables to get the garbage collector to + remove these old versions. + + When all rows in a table are read by the server, any old record + versions are flagged to the garbage collector as being ready to be + cleared out. They are not deleted by the scanning process as in the + cooperative method. The garbage collector runs as a separate + background thread and it will, at some point, remove these older + record versions from the database. +
+ +
+ Combined Garbage Collection + + This is the default garbage collection method for Super Server + installations. In this mode, both the above methods are used + together. +
-
- Database Housekeeping And Garbage Collection - - DB Housekeeping and Garbage Collection - -
- Garbage - - Garbage, for want of a better name, is the detritus that Firebird leaves - around in the database after a rollback has been carried out. This is - basically a copy of the row(s) from the table(s) that were being updated (or - deleted) by the transaction prior to the rollback. - - Because Firebird uses multi-generational architecture, every time a row - is updated or deleted, Firebird keeps a copy in the database. These copies use - space in the pages and can remain in the database for some time. - - In addition to taking up space in the database, these old copies can - lead to increased transaction startup times. - - There are two types of garbage: - - - - Remnants from a committed transaction. - - - - Remnants from an aborted (rolled back) transaction. - - These remnants are simply older copies of the rows that - were being updated by the respective transactions. The differences are - that: - - - - Whenever a subsequent transaction reaches garbage from a - committed transaction, that garbage is - automatically cleared out. - - - - Rolled back garbage is never - automatically cleared out. - - This means that on a database with a lot of rolled back - transactions, there could be a large build up of old copies of the rows that - were updated and then rolled back. - - Firebird will automatically sweep through the database and remove the - remnants of rolled back transactions and this has two effects: - - - - The database size is reduced as the old copies of rows are - deleted. - - - - The performance of the database may be affected while the sweep - is in progress. - - - - - One other method of clearing out old rolled back transactions' - garbage is simply to carry out a database backup. - - - In the Super Server version of Firebird 2.0, garbage collection has been - vastly improved. There are now three different ways of operation and these are - configurable by setting the GCPOLICY parameter in the - firebird.conf configuration file. By default, Super - Server uses combined while Classic Server uses - cooperative. The other option is - background. - - - Classic Server ignores the setting and always uses cooperative - garbage collection. - - -
- Cooperative Garbage Collection - - This is the default setting, indeed the only setting, that Classic - Server uses. In this mode, the normal operation - as described above - - takes place. When a full scan is performed (perhaps during a backup) old - versions of the rows are deleted at that point in time. -
- -
- Background garbage Collection - - Super Server has, even since before version 1.0, performed - background garbage collection where the server informs the garbage - collector about old versions of updated and deleted rows when they are - ready to be cleaned up. This helps avoid the need to force a full scan of - each record in the database tables to get the garbage collector to remove - these old versions. - - When all rows in a table are read by the server, any old record - versions are flagged to the garbage collector as being ready to be cleared - out. They are not deleted by the scanning process as in the cooperative - method. The garbage collector runs as a separate background thread and it - will, at some point, remove these older record versions from the - database. -
- -
- Combined Garbage Collection - - This is the default garbage collection method for Super Server - installations. In this mode, both the above methods are used - together. -
-
- -
- Setting Sweep Interval - - The default sweep interval for a new database is 20,000. The sweep - interval is the difference between the oldest - interesting transaction or OIT and the next transaction - number. - - - This doesn't mean that every 20,000 transaction a sweep will take - place. It will take place when the difference between - the OIT and the next transaction is greater than the sweep - interval. - - - An interesting transaction is one which has not yet committed. It may be - still active, in limbo or may have been rolled back. - - The sweep facility runs through the database and gets rid of old rows in - tables that are out of date. This prevents the database from growing too big - and helps reduce the time it takes to start a new transaction on the - database. - - - If you find that starting a new transaction takes a long time, it - may be a good idea to run a manual sweep of the database in case the need - for a sweep is causing the hold-up. - - - You can check if a manual sweep may be required by running the - gstat utility to check the database header page and - extract the oldest and next transaction numbers from the output. If the gap is - small (less than the sweep interval) then a manual sweep may be in order. - Alternatively, the SHOW DATABASE - command in isql will also show the details you - need. - - A manual sweep can be run by using the -s[weep] - command. (See below). - - To alter the database's automatic sweep interval, use the following - command: - - gfix -h[ousekeeping] INTERVAL database_name - - The INTERVAL parameter is the new value for the sweep interval. The - database name parameter is the database upon which you wish to alter the - setting for automatic sweeping. The following example shows the setting being - changed from the default to a new value of 1,000. - - linux> gfix -h 1000 my_employee +
+ Setting Sweep Interval -linux> gstat -header my_employee | grep Sweep -Sweep interval: 1000 -
+ The default sweep interval for a new database is 20,000. The sweep + interval is the difference between the + oldest interesting transaction or OIT and the next + transaction number. + + + This doesn't mean that every 20,000 transaction a sweep will + take place. It will take place when the + difference between the OIT and the next + transaction is greater than the sweep interval. + + + An interesting transaction is one which has not yet committed. It + may be still active, in limbo or may have been rolled back. + + The sweep facility runs through the database and gets rid of old + rows in tables that are out of date. This prevents the database from + growing too big and helps reduce the time it takes to start a new + transaction on the database. -
- Manual Garbage Collection + + If you find that starting a new transaction takes a long time, + it may be a good idea to run a manual sweep of the database in case + the need for a sweep is causing the hold-up. + - If automatic sweeping has been turned off, or only runs rarely because - of the sweep interval setting, the DBA can manually force a sweep to be - performed. The command to carry out this task is: + You can check if a manual sweep may be required by running the + gstat utility to check the database header + page and extract the oldest and next transaction numbers from the + output. If the gap is small (less than the sweep interval) then a manual + sweep may be in order. Alternatively, the SHOW + DATABASE command in + isql will also show the details you + need. - gfix -s[weep] [-i[gnore]] database_name + A manual sweep can be run by using the + -s[weep] command. (See below). - This command will force the garbage left over from old rolled back - transactions to be removed, reducing the database size and improving the - performance of new transactions. + To alter the database's automatic sweep interval, use the + following command: - The -i[gnore] option may be supplied. This forces - Firebird to ignore checksum errors on database pages. This is not a good idea - and should rarely need to be used, however, if your database has suffered some - problems it might be necessary to use it. + gfix -h[ousekeeping] INTERVAL + database_name - The following example shows a manual database sweep being - implemented: + The INTERVAL parameter is the new value for the sweep interval. + The database name parameter is the database upon which you wish to alter + the setting for automatic sweeping. The following example shows the + setting being changed from the default to a new value of 1,000. - linux> gfix -sweep my_employee -
+ linux> gfix -h 1000 my_employee -
- Disabling Automatic Sweeping +linux> gstat -header my_employee | grep Sweep +Sweep interval: 1000 +
+ +
+ Manual Garbage Collection + + If automatic sweeping has been turned off, or only runs rarely + because of the sweep interval setting, the DBA can manually force a + sweep to be performed. The command to carry out this task is: + + gfix -s[weep] [-i[gnore]] database_name + + This command will force the garbage left over from old rolled back + transactions to be removed, reducing the database size and improving the + performance of new transactions. + + The -i[gnore] option may be supplied. This + forces Firebird to ignore checksum errors on database pages. This is not + a good idea and should rarely need to be used, however, if your database + has suffered some problems it might be necessary to use it. - If you set the sweep interval to zero then automatic sweeping will be - disabled. This implies that there will be no automatic housekeeping done so - your database performance will not suffer as a result of the processing - requirements of the automatic sweep. + The following example shows a manual database sweep being + implemented: - If you disable sweeping you are advised to run a manual sweep at regular - intervals when the database is quiet. Alternatively, simply make sure that you - take regular backups of the database and as this is something you should be - doing anyway, it shouldn't be a problem. -
+ linux> gfix -sweep my_employee
-
- Database Startup and Shutdown +
+ Disabling Automatic Sweeping - - The first part of this section describes the shutdown and startup - options up to Firebird 2.0. There is a separate section at the end which - discusses the new states for starting and stopping a - database using Firebird 2.0 onwards. - + If you set the sweep interval to zero then automatic sweeping will + be disabled. This implies that there will be no automatic housekeeping + done so your database performance will not suffer as a result of the + processing requirements of the automatic sweep. -
- Database Shutdown - - If there is maintenance work required on a database, you may wish to - close down that database under certain circumstances. This is different from - stopping the Firebird server as the server may well be running other databases - which you do not wish to affect. - - The command to close a database is: - - gfix -shut OPTION TIMEOUT database_name - - The TIMEOUT parameter is the time, in seconds, that the shutdown must - complete in. If the command cannot complete in the specified time, the - shutdown is aborted. There are various reasons why the shutdown may not - complete in the given time and these vary with the mode of the shutdown and - are described below. - - The OPTION parameter is one of the following: - - - - -at[tach] - prevents new - connections. - - - - -tr[an] - prevents new - transactions. - - - - -f[orce] - simply aborts all connections - and transactions. - - - - When a database is closed, the SYSDBA or the database owner can still - connect to perform maintenance operations or even query and update the - database tables. - - - If you specify a long time for the shutdown command to complete in, - you can abort the shutdown by using the -online - command (see below) if the timeout period has not completed. - - -
- Preventing New Connections - - -at[tach] : this parameter prevents any new - connections to the database from being made with the exception of the - SYSDBA and the database owner. The shutdown will fail if there are any - sessions connected after the timeout period has expired. It makes no - difference if those connected sessions belong to the SYSDBA, the database - owner or any other user. Any connections remaining will terminate the - shutdown with the following details: - - linux> gfix -shut -attach 5 my_employee + If you disable sweeping you are advised to run a manual sweep at + regular intervals when the database is quiet. Alternatively, simply make + sure that you take regular backups of the database and as this is + something you should be doing anyway, it shouldn't be a problem. +
+
+ +
+ Database Startup and Shutdown + + + The first part of this section describes the shutdown and startup + options up to Firebird 2.0. There is a separate section at the end which + discusses the new states for starting and + stopping a database using Firebird 2.0 onwards. + + +
+ Database Shutdown + + If there is maintenance work required on a database, you may wish + to close down that database under certain circumstances. This is + different from stopping the Firebird server as the server may well be + running other databases which you do not wish to affect. + + The command to close a database is: + + gfix -shut OPTION TIMEOUT database_name + + The TIMEOUT parameter is the time, in seconds, that the shutdown + must complete in. If the command cannot complete in the specified time, + the shutdown is aborted. There are various reasons why the shutdown may + not complete in the given time and these vary with the mode of the + shutdown and are described below. + + The OPTION parameter is one of the following: + + + + -at[tach] - prevents new + connections. + + + + -tr[an] - prevents new + transactions. + + + + -f[orce] - simply aborts all + connections and transactions. + + + + When a database is closed, the SYSDBA or the database owner can + still connect to perform maintenance operations or even query and update + the database tables. + + + If you specify a long time for the shutdown command to complete + in, you can abort the shutdown by using the + -online command (see below) if the timeout + period has not completed. + + +
+ Preventing New Connections + + -at[tach] : this parameter prevents any + new connections to the database from being made with the exception of + the SYSDBA and the database owner. The shutdown will fail if there are + any sessions connected after the timeout period has expired. It makes + no difference if those connected sessions belong to the SYSDBA, the + database owner or any other user. Any connections remaining will + terminate the shutdown with the following details: + + linux> gfix -shut -attach 5 my_employee lock conflick on no wait transaction -database shutdown unsuccessful - Anyone other than the SYSDBA or database owner, attempting to - connect to the database will see the following: + Anyone other than the SYSDBA or database owner, attempting to + connect to the database will see the following: - linux> isql my_employee -user norman -password whatever + linux> isql my_employee -user norman -password whatever Statement failed, SQLCODE = -901 database my_employee shutdown Use CONNECT or CREATE DATABASE to specify a database SQL> - Connections in the database will still be able to start new - transactions or complete old ones. -
+ Connections in the database will still be able to start new + transactions or complete old ones. +
-
- Preventing New Transactions +
+ Preventing New Transactions - -tr[an] : prevents any new transactions from - being started and also prevents new connections to the database. If there - are any active transactions after the timeout period has expired, then the - shutdown will fail as follows: + -tr[an] : prevents any new transactions + from being started and also prevents new connections to the database. + If there are any active transactions after the timeout period has + expired, then the shutdown will fail as follows: - linux> gfix -shut -tran 5 my_employee + linux> gfix -shut -tran 5 my_employee lock conflick on no wait transaction -database shutdown unsuccessful - If any user connected to the database being shutdown with the - -tr[an] tries to start a new transaction during the - shutdown timeout period, the following will result: + If any user connected to the database being shutdown with the + -tr[an] tries to start a new transaction during + the shutdown timeout period, the following will result: - SQL> select * from test; + SQL> select * from test; Statement failed, SQLCODE = -902 database /home/norman/firebird/my_employee.fdb shutdown in progress Statement failed, SQLCODE = -902 @@ -1139,115 +1212,120 @@ Statement failed, SQLCODE = -901 Dynamic SQL Error -SQL error code = -901 -invalid transaction handle (expecting explicit transaction start) -
- -
- Force Closure - - -f[orce] : shuts down with no regard for the - connection or transaction status of the database. No new connections or - transactions are permitted and any active sessions are terminated along - with any active transactions. - - Anyone other than SYSDBA or the database owner trying to connect to - the database during the timeout period will not be able to connect - successfully or start any (new) transactions. - - Be nice to your users, use the -f[orce] - option with great care. - - - There is a bug in Classic Server which still exists at version - 2.0. The bug is such that the -f[orce] option - behaves in exactly the same way as the - -at[tach] option. - -
-
- -
- Starting a Database - - Once all maintenance work required on a database has been carried out, - you need to restart the database to allow normal use again. (See shutdown - option above for details of closing a database.) - - The -o[nline] command allows a database to be - restarted. It takes a single parameter which is the database name as - follows: - - gfix -o[nline] database_name - - The following example shows a closed database being started. - - linux> gfix -online my_employee -
- -
- New Startup and Shutdown States in Firebird 2.0 - - The above discussion of stopping and starting a database apply to all - versions of the server up to version 2.0. From 2.0 the commands will work as - described above, but a new state has been added to define - exactly how the database is to be stopped or started. The commands change from - those described above to the following: - - gfix -shut STATE OPTION TIMEOUT database_name - - gfix -o[nline] STATE database_name - - STATE is new in Firebird 2.0 and is one of the following: - - - - normal - This is the default state for - starting the database backup. It allows connections from any - authorised users - not just SYSDBA or the database owner. This option - is not accepted for shutdown operations. - - - - multi - this is the default mode as - described above. When the database is shutdown as above, or using the - multi state, then unlimited connections can be - made by the SYSDBA or the database owner. No other connections are - allowed. - - - - single - Similar to the multi option - above, but only one SYSDBA or database owner - connection is allowed. - - - - full - Shutdown and don't allow - any connections from anyone, even SYSDBA or the - database owner. This is not an acceptable option for starting up a - database. - - - - - There is no leading dash for the state parameters, unlike the - command itself and the -shut OPTION. - - - There is a hierarchy of states for a database. The above list shows them - in order with normal at the top and full at the bottom. - - This hierarchy is important, you cannot shutdown a - database to a higher or equal level that it currently is, - nor can you startup a database to a lower or - equal level. - - If you need to identify which level a database is currently running at, - gstat will supply the answers. The following - example puts a database fully online then progressively shuts it down to fully - offline. At each stage, gstat is run to extract the - Attributes of the database. - - linux> gfix -online normal my_employee +
+ +
+ Force Closure + + -f[orce] : shuts down with no regard for + the connection or transaction status of the database. No new + connections or transactions are permitted and any active sessions are + terminated along with any active transactions. + + Anyone other than SYSDBA or the database owner trying to connect + to the database during the timeout period will not be able to connect + successfully or start any (new) transactions. + + Be nice to your users, use the -f[orce] + option with great care. + + + There is a bug in Classic Server which still exists at version + 2.0. The bug is such that the -f[orce] option + behaves in exactly the same way as the + -at[tach] option. + +
+
+ +
+ Starting a Database + + Once all maintenance work required on a database has been carried + out, you need to restart the database to allow normal use again. (See + shutdown option above for details of closing a database.) + + The -o[nline] command allows a database to + be restarted. It takes a single parameter which is the database name as + follows: + + gfix -o[nline] database_name + + The following example shows a closed database being + started. + + linux> gfix -online my_employee +
+ +
+ New Startup and Shutdown States in Firebird 2.0 + + The above discussion of stopping and starting a database apply to + all versions of the server up to version 2.0. From 2.0 the commands will + work as described above, but a new state has been + added to define exactly how the database is to be stopped or started. + The commands change from those described above to the following: + + gfix -shut STATE OPTION TIMEOUT + database_name + + gfix -o[nline] STATE database_name + + STATE is new in Firebird 2.0 and is one of the following: + + + + normal - This is the default state for + starting the database backup. It allows connections from any + authorised users - not just SYSDBA or the database owner. This + option is not accepted for shutdown operations. + + + + multi - this is the default mode as + described above. When the database is shutdown as above, or using + the multi state, then unlimited connections can + be made by the SYSDBA or the database owner. No other connections + are allowed. + + + + single - Similar to the multi option + above, but only one SYSDBA or database owner + connection is allowed. + + + + full - Shutdown and don't allow + any connections from anyone, even SYSDBA or the + database owner. This is not an acceptable option for starting up a + database. + + + + + There is no leading dash for the state parameters, unlike the + command itself and the -shut OPTION. + + + There is a hierarchy of states for a database. The above list + shows them in order with normal at the top and full at the + bottom. + + This hierarchy is important, you cannot + shutdown a database to a higher or + equal level that it currently is, nor can you + startup a database to a lower or + equal level. + + If you need to identify which level a database is currently + running at, gstat will supply the answers. + The following example puts a database fully online then progressively + shuts it down to fully offline. At each stage, + gstat is run to extract the Attributes of the + database. + + linux> gfix -online normal my_employee linux> gstat -header my_employee | grep Attributes Attributes @@ -1268,369 +1346,375 @@ linux> gstat -header my_employee | grep Attributes Attributes full shutdown linux> -
+
-
- Database Page Space Utilisation +
+ Database Page Space Utilisation - When a database page is being written to, Firebird reserves 20% of the page - for future use. This could be used to extend VARCHAR columns - that started off small and then were updated to a longer value, for - example. + When a database page is being written to, Firebird reserves 20% of + the page for future use. This could be used to extend + VARCHAR columns that started off small and then were + updated to a longer value, for example. - If you wish to use all the available space in each database page, you may - use the -use command to configure the database to do so. If - you subsequently wish to return to the default behaviour, the - -use command can be used to revert back to leaving 20% free - space per page. + If you wish to use all the available space in each database page, + you may use the -use command to configure the + database to do so. If you subsequently wish to return to the default + behaviour, the -use command can be used to revert + back to leaving 20% free space per page. - - Once a page has been filled to 'capacity' (80 or 100%) changing the page - usage setting will not change those pages, only subsequently written pages - will be affected. - + + Once a page has been filled to 'capacity' (80 or 100%) changing + the page usage setting will not change those pages, only subsequently + written pages will be affected. + - The -use command takes two parameters as - follows: + The -use command takes two parameters as + follows: - gfix -use USAGE database_name + gfix -use USAGE database_name - The USAGE is one of: + The USAGE is one of: - - - full : use 100% of the space in each database - page. - + + + full : use 100% of the space in each + database page. + - - reserve : revert to the default behaviour and - only use 80% of each page. - - + + reserve : revert to the default behaviour + and only use 80% of each page. + + - The following example configures a database to use all available space in - each database page: + The following example configures a database to use all available + space in each database page: - linux> gfix -use full my_employee + linux> gfix -use full my_employee linux> gstat -header my_employee | grep Attributes Attributes no reserve - The following example sets the page usage back to the default: + The following example sets the page usage back to the + default: - linux> gfix -use reserve my_employee + linux> gfix -use reserve my_employee linux> gstat -header my_employee | grep Attributes Attributes - If you are using full page utilisation then the Attributes show up with 'no - reserve' in the text. This doesn't appear for normal 80% utilisation mode. -
+ If you are using full page utilisation then the Attributes show up + with 'no reserve' in the text. This doesn't appear for normal 80% + utilisation mode. +
+ +
+ Database Validation and Recovery + +
+ Database Validation + + Sometimes, databases get corrupted. Under certain circumstances, + you are advised to validate the database to check for corruption. The + times you would check are: + + + + When an application receives a database + corrupt error message. + + + + When a backup fails to complete without errors. + + + + If an application aborts rather than shutting down + cleanly. + + + + On demand - when the SYSDBA decides to check the + database. + + + + + Database validation requires that you have exclusive access to + the database. To prevent other users from accessing the database while + you validate it, use the gfix -shut command to + shutdown the database. + + + When a database is validated the following checks are made + and corrected by default: + + + + Orphan pages are returned to free space. This updates the + database. + + + + Pages that have been misallocated are reported. + + + + Corrupt data structures are reported. + + + + There are options to perform further, more intensive, validation + and these are discussed below. + +
+ Default Validation + + The command to carry out default database validation is: + + gfix -v[alidate] database_name + + This command validates the database and makes updates to it when + any orphan pages are found. An orphan page is one which was allocated + for use by a transaction that subsequently failed, for example, when + the application aborted. In this case, committed data is safe but + uncommitted data will have been rolled back. The page appears to have + been allocated for use, but is unused. + + This option updates the database and fixes any corrupted + structures. +
+ +
+ Full Validation + + By default, validation works at page level. If no need to go + deeper and validate at the record level as well, the command to do + this is: + + gfix -v[alidate] -full database_name + + using this option will validate, report and update at both page + and record level. Any corrupted structures etc will be fixed. +
+ +
+ Read-only Validation + + As explained above, a validation of a database will actually + validate and update the database structures to, hopefully, return the + database to a working state. However, you may not want this to happen + and in this case, you would perform a read only validation which + simply reports any problem areas and does not make any changes to the + database. -
- Database Validation and Recovery - -
- Database Validation + To carry out a read only validation, simply supply the + -n[o_update] option to whichever command line + you are using for the validation. To perform a full validation, at + record and page level, but in reporting mode only, use the following + command: - Sometimes, databases get corrupted. Under certain circumstances, you are - advised to validate the database to check for corruption. The times you would - check are: + gfix -v[alidate] -full -n[o_update] + database_name - - - When an application receives a database - corrupt error message. - + On the other hand, to stay at page level validation only, the + command would be: - - When a backup fails to complete without errors. - + gfix -v[alidate] -n[o_update] + database_name +
- - If an application aborts rather than shutting down - cleanly. - +
+ Ignore Checksum Errors - - On demand - when the SYSDBA decides to check the - database. - - - - - Database validation requires that you have exclusive access to the - database. To prevent other users from accessing the database while you - validate it, use the gfix -shut command to shutdown the - database. - + Checksums are used to ensure that data in a page is valid. If + the checksum no longer matches up, then it is possible that a database + corruption has occurred. You can run a validation against a database, + but ignore the checksums using the -i[gnore] + option. - When a database is validated the following checks are made and - corrected by default: + This option can be combined with the + -n[o_update] option described above and applies + to both full and default validations. So, to perform a full validation + and ignore checksums on a database, but reporting errors only, use the + following command: - - - Orphan pages are returned to free space. This updates the - database. - - - - Pages that have been misallocated are reported. - - - - Corrupt data structures are reported. - - - - There are options to perform further, more intensive, validation and - these are discussed below. - -
- Default Validation + gfix -v[alidate] -full -i[gnore] -n[o_update] + database_name - The command to carry out default database validation is: + Alternatively, to carry out a page level validation, ignoring + checksum errors but updating the database structures to repair it, the + command would be: - gfix -v[alidate] database_name + gfix -v[alidate] -i[gnore] + database_name - This command validates the database and makes updates to it when any - orphan pages are found. An orphan page is one which was allocated for use - by a transaction that subsequently failed, for example, when the - application aborted. In this case, committed data is safe but uncommitted - data will have been rolled back. The page appears to have been allocated - for use, but is unused. - - This option updates the database and fixes any corrupted - structures. -
- -
- Full Validation - - By default, validation works at page level. If no need to go deeper - and validate at the record level as well, the command to do this - is: - - gfix -v[alidate] -full database_name - - using this option will validate, report and update at both page and - record level. Any corrupted structures etc will be fixed. -
- -
- Read-only Validation - - As explained above, a validation of a database will actually - validate and update the database structures to, hopefully, return the - database to a working state. However, you may not want this to happen and - in this case, you would perform a read only validation which simply - reports any problem areas and does not make any changes to the - database. - - To carry out a read only validation, simply supply the - -n[o_update] option to whichever command line you - are using for the validation. To perform a full validation, at record and - page level, but in reporting mode only, use the following command: - - gfix -v[alidate] -full -n[o_update] - database_name - - On the other hand, to stay at page level validation only, the - command would be: - - gfix -v[alidate] -n[o_update] - database_name -
- -
- Ignore Checksum Errors - - Checksums are used to ensure that data in a page is valid. If the - checksum no longer matches up, then it is possible that a database - corruption has occurred. You can run a validation against a database, but - ignore the checksums using the -i[gnore] - option. - - This option can be combined with the - -n[o_update] option described above and applies to - both full and default validations. So, to perform a full validation and - ignore checksums on a database, but reporting errors only, use the - following command: - - gfix -v[alidate] -full -i[gnore] -n[o_update] - database_name - - Alternatively, to carry out a page level validation, ignoring - checksum errors but updating the database structures to repair it, the - command would be: - - gfix -v[alidate] -i[gnore] database_name - - Ignoring checksums would allow a corrupted database to be validated - (unless you specify the -n[o_update] option) but it - is unlikely that the recovered data would be usable, if at all, - present. -
-
- -
- Database Recovery - - If the database validation described above produces no output then the - database structures can be assumed to be valid. However, - in the event that errors are reported, you may have to repair the database - before it can be used again. - -
- Recover a Corrupt Database - - The option required to fix a corrupted database is the gfix - -m[end] command. However, it cannot fix all problems and - may result in a loss of data. It all depends on the - level of corruption detected. The command is: - - gfix -m[end] database_name - - This causes the corruptions in data records to be ignored. While - this sounds like a good thing, it is not. Subsequent database actions - (such as taking a backup) will not include the corrupted records, leading - to data loss. - - - The best way to avoid data loss is to make sure that you have - enough regular backups of your database and to regularly carry out - test restorations. There is no point taking backups every night, for - example, if they cannot be used when required. Test always and - frequently. - - Equally, when attempting to recover a potentially corrupted - database, always work with a copy of the main - database file and never with the original. Using the - -mend option can lead to silent deletions of data - because gfix doesn't care about internal - database constraints like foreign keys etc, the - -mend option simply says to - gfix "go ahead and clean out - anything you don't like". - -
-
+ Ignoring checksums would allow a corrupted database to be + validated (unless you specify the -n[o_update] + option) but it is unlikely that the recovered data would be usable, if + at all, present. +
-
- Database Write Mode - - Many operating systems employ a disc cache mechanism. This uses an area of - memory (which may be part of your server's overall RAM or may be built into the - disc hardware) to buffer writes to the hardware. This improves the performance of - applications that are write intensive but means that the user is never certain - when their data has actually been written to the physical disc. - - With a database application, it is highly desirable to have the data secured - as soon as possible. Using Firebird, it is possible to specify whether the data - should be physically written to disc on a COMMIT or simply - left to the operating system to write the data when it gets around to - it. - - To give the DBA or database owner full control of when data is written, the - gfix -w[rite] command can be used. The command takes two - parameters: - - gfix -write MODE database_name - - The MODE parameter specifies whether data would be written immediately or - later, and is one of: - - - - sync - data is written synchronously. This - means that data is flushed to disc on COMMIT. This is - safest for your data. - - - - async - data is written asynchronously. The - operating system controls when the data is actually written to - disc. - - - - If your system is highly robust, and protected by a reliable UPS - (uninterruptable Power Supply) then it is possible to run asynchronously but for - most systems, synchronous running is safest this will help prevent corruption in - the event of a power outage or other uncontrolled shutdown of the server and/or - database. - - - Firebird defaults to synchronous mode (forced writes enabled) on Linux, - Windows NT, XP, 2000, 2003 and Vista. - - - This command has no effect on Windows 95, 98 and ME. - - - Cache flushing on Windows servers (up to but not including Vista - which - has not been confirmed yet) is unreliable. If you set the database to - async mode (forced writes disabled) then it is possible - that the cache will never be flushed and data could be lost if the server is - never shutdown tidily. - - - - If your database was originally created with Interbase 6 or an early - beta version of Firebird then the database will be running in asynchronous - mode - which is not ideal. - +
+ Database Recovery + + If the database validation described above produces no output then + the database structures can be assumed to be valid. + However, in the event that errors are reported, you may have to repair + the database before it can be used again. + +
+ Recover a Corrupt Database + + The option required to fix a corrupted database is the + gfix -m[end] command. However, it cannot fix all + problems and may result in a loss of data. It all + depends on the level of corruption detected. The command is: + + gfix -m[end] database_name + + This causes the corruptions in data records to be ignored. While + this sounds like a good thing, it is not. Subsequent database actions + (such as taking a backup) will not include the corrupted records, + leading to data loss. + + + The best way to avoid data loss is to make sure that you have + enough regular backups of your database and to regularly carry out + test restorations. There is no point taking backups every night, for + example, if they cannot be used when required. Test always and + frequently. + + Equally, when attempting to recover a potentially corrupted + database, always work with a copy of the main + database file and never with the original. Using the + -mend option can lead to silent deletions of data + because gfix doesn't care about internal + database constraints like foreign keys etc, the + -mend option simply says to + gfix "go ahead and clean out + anything you don't like". + +
- -
- Version Number - - The -z option to gfix - simply prints out the version of the Firebird utility software that you are - running. It takes no parameters as the following example (running on Linux) - shows. - - linux> gfix -z +
+ +
+ Database Write Mode + + Many operating systems employ a disc cache mechanism. This uses an + area of memory (which may be part of your server's overall RAM or may be + built into the disc hardware) to buffer writes to the hardware. This + improves the performance of applications that are write intensive but + means that the user is never certain when their data has actually been + written to the physical disc. + + With a database application, it is highly desirable to have the data + secured as soon as possible. Using Firebird, it is possible to specify + whether the data should be physically written to disc on a + COMMIT or simply left to the operating system to + write the data when it gets around to it. + + To give the DBA or database owner full control of when data is + written, the gfix -w[rite] command can be used. The + command takes two parameters: + + gfix -write MODE database_name + + The MODE parameter specifies whether data would be written + immediately or later, and is one of: + + + + sync - data is written synchronously. + This means that data is flushed to disc on + COMMIT. This is safest for your data. + + + + async - data is written asynchronously. + The operating system controls when the data is actually written to + disc. + + + + If your system is highly robust, and protected by a reliable UPS + (uninterruptable Power Supply) then it is possible to run asynchronously + but for most systems, synchronous running is safest this will help prevent + corruption in the event of a power outage or other uncontrolled shutdown + of the server and/or database. + + + Firebird defaults to synchronous mode (forced writes enabled) on + Linux, Windows NT, XP, 2000, 2003 and Vista. + + + This command has no effect on Windows 95, 98 and ME. + + + Cache flushing on Windows servers (up to but not including Vista - + which has not been confirmed yet) is unreliable. If you set the database + to async mode (forced writes disabled) then it is + possible that the cache will never be flushed and data could be lost if + the server is never shutdown tidily. + + + + If your database was originally created with Interbase 6 or an + early beta version of Firebird then the database will be running in + asynchronous mode - which is not ideal. + +
+ +
+ Version Number + + The -z option to + gfix simply prints out the version of the + Firebird utility software that you are running. It takes no parameters as + the following example (running on Linux) shows. + + linux> gfix -z gfix version LI-V2.0.0.12748 Firebird 2.0 -
+
-
- Caveats +
+ Caveats - This section summarises the various problems that you may encounter from - time to time when using gfix. They have already been - discussed above, or mentioned in passing, but are explained in more details - here. + This section summarises the various problems that you may encounter + from time to time when using gfix. They have + already been discussed above, or mentioned in passing, but are explained + in more details here. -
- Shadows +
+ Shadows - The gstat seems to take some time to respond - to the addition of shadow files to a database. After adding two shadows to a - test database, gstat still showed that there was a - Shadow count of zero. + The gstat seems to take some time to + respond to the addition of shadow files to a database. After adding two + shadows to a test database, gstat still + showed that there was a Shadow count of zero. - Even worse, after killing the second shadow file and running the - DROP SHADOW command in isql to - remove the one remaining shadow file, gstat decided - that there were now three shadow files in use. -
+ Even worse, after killing the second shadow file and running the + DROP SHADOW command in + isql to remove the one remaining shadow file, + gstat decided that there were now three + shadow files in use. +
-
- Response Codes Are Usually Zero +
+ Response Codes Are Usually Zero - Even using Firebird version 2 it appears that many commands, which fail - to complete without an error, return a response of 0 to the operating - system. + Even using Firebird version 2 it appears that many commands, which + fail to complete without an error, return a response of 0 to the + operating system. - For example, the following shows two attempts to shut down the same - database, the second one should fail - it displays an error message - but - still returns a zero response to the operating system. This makes it - impossible to built correctly error trapped database shutdown scripts as you - can never tell whether it actually worked or not. + For example, the following shows two attempts to shut down the + same database, the second one should fail - it displays an error message + - but still returns a zero response to the operating system. This makes + it impossible to built correctly error trapped database shutdown scripts + as you can never tell whether it actually worked or not. - linux> gfix -shut -force 5 my_employee + linux> gfix -shut -force 5 my_employee linux> echo $? 0 @@ -1639,50 +1723,51 @@ Target shutdown mode is invalid for database - "/home/norman/firebird/my_employee.fdb" linux> echo $? 0 -
- -
- Force Closing a Database - - Under classic server, using the -f[orce] option - to the -shut command acts exactly the same as the - -at[tach] option. -
- -
- Limbo Transactions - - There are a couple of problems with limbo transactions as discovered by - Paul in his testing. - -
- Limbo Transaction Options - All The Same? - - When processing limbo transactions, it appears under Firebird 1.5 at - least, that the -l[ist] -p[rompt] option is called - regardless of whether you use -c[ommit], - -r[ollback] or -t[wo_phase]. - The outcome is the same regardless of whether the DBA specifies a specific - transaction number or 'all' on the command line - a prompt is given with - the option to commit, rollback or neither. -
- -
- Limbo Transactions - Can Be Backed Up - - Paul's testing of limbo transactions revealed that it is possible to - make a backup of a database with limbo transactions. This backup can then - be used to create a new database and the limbo transactions will still be - able to be listed. This applies to a filesystem copy of the database and - to version 1.5 of Firebird. - - If you attempt to list the limbo transactions in the copy database - and the original database has been deleted, renamed - or has been set to read-only, then gfix will - present you with a request to supply the correct path to the original - database - - linux>cd /home/norman/firebird +
+ +
+ Force Closing a Database + + Under classic server, using the -f[orce] + option to the -shut command acts exactly the same + as the -at[tach] option. +
+ +
+ Limbo Transactions + + There are a couple of problems with limbo transactions as + discovered by Paul in his testing. + +
+ Limbo Transaction Options - All The Same? + + When processing limbo transactions, it appears under Firebird + 1.5 at least, that the -l[ist] -p[rompt] option + is called regardless of whether you use + -c[ommit], -r[ollback] + or -t[wo_phase]. The outcome is the same + regardless of whether the DBA specifies a specific transaction number + or 'all' on the command line - a prompt is given with the option to + commit, rollback or neither. +
+ +
+ Limbo Transactions - Can Be Backed Up + + Paul's testing of limbo transactions revealed that it is + possible to make a backup of a database with limbo transactions. This + backup can then be used to create a new database and the limbo + transactions will still be able to be listed. This applies to a file + system copy of the database and to version 1.5 of Firebird. + + If you attempt to list the limbo transactions in the copy + database and the original database has been + deleted, renamed or has been set to read-only, then + gfix will present you with a request to + supply the correct path to the original database + + linux>cd /home/norman/firebird linux>cp my_employee.fdb my_new_employee.fdb linux> mv my_employee.fdb my_old_employee.fdb @@ -1701,105 +1786,120 @@ has been prepared. Remote Site: remote Database path: /opt/firebird/examples/testlimbo.fdb - In the above example, the original database - my_employee.fdb was first of all copied using the - operating system command cp to - my_new_employee.fdb and then renamed to - my_old_employee.fdb. - - Gfix was then run on the copy named - my_new_employee.fdb and it noted the limbo - transaction. However, it could not find the original database file as it - had been renamed, so gfix prompted for the path - to the original database file. When this was entered, - gfix happily listed the details. - - - This implies that if you have a database with limbo transactions - and you copy it using the operating system utilities and subsequently - run gfix against the new database, it is - possible to have gfix fix limbo - transactions in the original database file and not in the one you - think it is updating - the copy. - - It is also a good warning about making copies of databases - without using the correct tools for the job. - -
-
+ In the above example, the original database + my_employee.fdb was first of all copied using the + operating system command cp to + my_new_employee.fdb and then renamed to + my_old_employee.fdb. + + Gfix was then run on the copy named + my_new_employee.fdb and it noted the limbo + transaction. However, it could not find the original database file as + it had been renamed, so gfix prompted for + the path to the original database file. When this was entered, + gfix happily listed the details. + + + This implies that if you have a database with limbo + transactions and you copy it using the operating system utilities + and subsequently run gfix against the new + database, it is possible to have gfix fix + limbo transactions in the original database file and not in the one + you think it is updating - the copy. + + It is also a good warning about making copies of databases + without using the correct tools for the job. + +
+
+ + + Document history + + The exact file history is recorded in the manual module in our CVS tree; see http://sourceforge.net/cvs/?group_id=9028. + The full URL of the CVS log for this file can be found at http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/fbutil_gfix.xml?view=log + + + + 1.0 + + 19 June 2007 + + ND - - Document history + + Created as a chapter in the Command Line Utilities + manual. + + - The exact file history is recorded in the manual module in our CVS tree; see http://sourceforge.net/cvs/?group_id=9028. - The full URL of the CVS log for this file can be found at http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/fbutil_gfix.xml?view=log + + 1.1 - - - 1.0 + 20 October 2009 - 19 June 2007 + ND - ND + + More minor updates and converted to a stand alone + manual. + + - - Created as a chapter in the Command Line Utilities - manual. - - + + 1.2 - - 1.1 + 25 June 2010 - 20 October 2009 + ND - ND + + Fixed spacing on a couple of lists. Added an enhancement to + the details of the -mend recovery option. It can lead to a loss of + data. + + - - More minor updates and converted to a stand alone - manual. - - + + 1.3 - - 1.2 + 11 October 2011 - 25 June 2010 + ND - ND + + Spelling errors corrected. - - Fixed spacing on a couple of lists. Added an enhancement to - the details of the -mend recovery option. It can lead to a loss of - data. - - - - + Updated for Firebird 2.5. + + + + - - License notice + + License notice - The contents of this Documentation are subject to the Public Documentation - License Version 1.0 (the License); you may only use this - Documentation if you comply with the terms of this License. Copies of the License - are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf - (PDF) and http://www.firebirdsql.org/manual/pdl.html - (HTML). + The contents of this Documentation are subject to the Public + Documentation License Version 1.0 (the License); you may + only use this Documentation if you comply with the terms of this License. + Copies of the License are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) and http://www.firebirdsql.org/manual/pdl.html + (HTML). - The Original Documentation is titled Firebird Database - Housekeeping Utility. + The Original Documentation is titled Firebird Database + Housekeeping Utility. - The Initial Writer of the Original Documentation is: Norman Dunbar. + The Initial Writer of the Original Documentation is: Norman + Dunbar. - Copyright (C) 2007–2009. All Rights Reserved. Initial Writer contact: - NormanDunbar at users dot sourceforge dot net. - + Copyright (C) 2007–2009. All Rights Reserved. Initial Writer + contact: NormanDunbar at users dot sourceforge dot net. +
diff --git a/src/docs/firebirddocs/fbutil_gsec.xml b/src/docs/firebirddocs/fbutil_gsec.xml index f7723998..cd715250 100644 --- a/src/docs/firebirddocs/fbutil_gsec.xml +++ b/src/docs/firebirddocs/fbutil_gsec.xml @@ -2,223 +2,247 @@ + -->
- Firebird Password File Utility - - Gsec - Password File Utility - - - 20 October 2009 - - - Norman - - Dunbar - - - 05 January 2010 – Document version 1.3 - - -
- Introduction - - Gsec is the security database manipulation - utility. It allows the SYSDBA (or any privileged user) the ability to maintain - user accounts for various Firebird databases. Using various options, users can be - added, amended or deleted from the security database. - - - A privileged user is an account on the database server which the - Firebird engine considers to be privileged enough to automatically be given - SYSDBA rights. At present there are four login names that are assumed to be - privileged, these are: - - - - root - - - - firebird - - - - interbase - - - - interbas (without the 'e') - - - - - Normal users, ie all those accounts not listed above, can only see their own - user details from version 2.0 of Firebird. They can, however, change their own - passwords with the new version. Previously the SYSDBA had to make the changes on - bahalf of the users.. - - - It is possible on some operating systems that users will not be able to - run gsec, even if they know the SYSDBA password. - This is because those operating systems allow the system administrator to set - filesystem permissions which prevent execution of certain programs and - utilities for security reasons. - - - The Firebird database holds details of all users in a single security - database. This is located on the server in a normal Firebird database named - security.fdb for Firebird 1.5 or - security2.fdb for Firebird 2.0 onwards. The default locations - for this file are : + Firebird Password File Utility + + Gsec - Password File Utility + + + 20 October 2009 + + + Norman + + Dunbar + + + 11 October 2011 – Document version 1.4 + + +
+ Introduction + + Gsec is the security database + manipulation utility. It allows the SYSDBA (or any privileged user) the + ability to maintain user accounts for various Firebird databases. Using + various options, users can be added, amended or deleted from the security + database. + + + A privileged user is an account on the database server which the + Firebird engine considers to be privileged enough to automatically be + given SYSDBA rights. At present there are four login names that are + assumed to be privileged, these are: + + + + root + + + + firebird + + + + interbase + + + + interbas (without the 'e') + + + + + Normal users, ie all those accounts not listed above, can only see + their own user details from version 2.0 of Firebird. They can, however, + change their own passwords with the new version. Previously the SYSDBA had + to make the changes on behalf of the users.. + + + It is possible on some operating systems that users will not be + able to run gsec, even if they know the + SYSDBA password. This is because those operating systems allow the + system administrator to set file system permissions which prevent + execution of certain programs and utilities for security reasons. + + + The Firebird database holds details of all users in a single + security database. This is located on the server in a normal Firebird + database named security.fdb for Firebird 1.5 or + security2.fdb for Firebird 2.0 onwards. The default + locations for this file are : + + + + C:\Program + Files\Firebird\Firebird_1_5 for Windows. (Change '1_5' to + suit your Firebird version.) + + + + /opt/firebird for Linux + and other Unix systems. + + + + The gsec utility manipulates data in the + table(s) in the security database, and by doing so, allows users to be + added, amended and deleted from the system. + + Up until Firebird 2.0, it used to be possible to use + isql to connect directly to the security + database as the SYSDBA user. This is no longer possible, even if you have + the SYSDBA username and password and/or are logged in as a privileged + user. + + Like most of the command line utilities supplied with Firebird, + gsec can be run in interactive or batch mode + and has a help screen showing all of the utility's options, we'll be + seeing that a little later on. + + In the remainder of this manual we shall discuss the + following: + + + + Command line options for gsec. + + + + Gsec commands and their + parameters. + + + + Running gsec in interactive or batch + modes, both of which allow you to : - - C:\Program - Files\Firebird\Firebird_1_5 for Windows. (Change '1_5' to suit - your Firebird version.) - - - - /opt/firebird for Linux and - other Unix systems. - - - - The gsec utility manipulates data in the table(s) - in the security database, and by doing so, allows users to be added, amended and - deleted from the system. + + Display user details. + - Up until Firebird 2.0, it used to be possible to use - isql to connect directly to the security database as - the SYSDBA user. This is no longer possible, even if you have the SYSDBA username - and password and/or are logged in as a privileged user. + + Amend user details. + - Like most of the command line utilities supplied with Firebird, - gsec can be run in interactive or batch mode and has a - help screen showing all of the utility's options, we'll be seeing that a little - later on. + + Add new users. + - In the remainder of this manual we shall discuss the following: - - - - Commandline options for gsec. - - - - Gsec commands and their - parameters. - - - - Running gsec in interactive or batch - modes, both of which allow you to : - - - - Display user details. - - - - Amend user details. - - - - Add new users. - - - - Delete existing users. - - - - - - Using gsec to administer a remote - security database. - - - - Some caveats, gotchas and foibles of - gsec. - + + Delete existing users. + -
- -
- Commandline Options - - Regardless of the mode that gsec is run in, there - are a number of options that can be supplied on the command line. These are - : + + + + Using gsec to administer a remote + security database. + + + + Some caveats, gotchas and foibles of + gsec. + + +
+ +
+ Command Line Options + + Regardless of the mode that gsec is run + in, there are a number of options that can be supplied on the command + line. These are : + + + + -user <username> + + Allows the username of the SYSDBA user to be specified if the + database is to be modified, or a normal username if the database is to + be displayed only. This need not be supplied if + ISC_USER and ISC_PASSWORD environment + variables exist and have the correct values. + + + + -password <password> + + Supplies the password for the username specified above. This + need not be supplied if ISC_USER and + ISC_PASSWORD environment variables exist and have the + correct values. + + + + -fe[tch_password] <password file name> | stdin + | /dev/tty + + This switch causes the password for the appropriate user to be + read from a file as opposed to being specified on the command line. + The file name supplied is not in quotes and must + be readable by the user running gsec. If + the file name is specified as stdin, then the + user will be prompted for a password. On POSIX systems, the file name + /dev/tty will also result in a + prompt for the password. - - - -user <username> - - Allows the username of the SYSDBA user to be specified if the - database is to be modified, or a normal username if the database is to be - displayed only. This need not be supplied if ISC_USER and - ISC_PASSWORD environment variables exist and have the - correct values. - - - - -password <password> - - Supplies the password for the username specified above. This need - not be supplied if ISC_USER and ISC_PASSWORD - environment variables exist and have the correct values. - + + Firebird 2.5 onwards. + + - - -role <SQL role name> + + -role <SQL role name> - Allows the specification of the role to be used by the connecting - user. - + Allows the specification of the role to be used by the + connecting user. + - - -database <server:security database - name> + + -database <server:security database + name> - You can specify the full pathname of a security database to - gsec and this will allow you to remotely - administer the users for that server. The whole parameter should be - enclosed in quotes if there are any spaces in the path to the security - database. - + You can specify the full pathname of a security database to + gsec and this will allow you to remotely + administer the users for that server. The whole parameter should be + enclosed in quotes if there are any spaces in the path to the security + database. + - - -z + + -z - Displays the version number of the gsec - utility. - + Displays the version number of the + gsec utility. + - - -help + + -help or -? - Help displays the following screen of information : - - + Help displays the following screen of information : + + - gsec utility - maintains user password database + gsec utility - maintains user password database command line usage: gsec [ <options> ... ] <command> [ <parameter> ... ] interactive usage: gsec [ <options> ... ] - GSEC> + GSEC> <command> [ <parameter> ... ] available options: -user <database administrator name> -password <database administrator password> + -fetch_password <file to fetch password from> -role <database administrator SQL role name> - -database <security database> + -trusted (use trusted authentication) + -database <database to manage> -z available commands: @@ -232,6 +256,8 @@ display <name> modifying a user's parameters: modify <name> <parameter> [ <parameter> ... ] + changing admins mapping to RDB$ADMIN role in security database: + mapping {set|drop} help: ? (interactive only) help @@ -247,165 +273,191 @@ -fname <firstname> -mname <middlename> -lname <lastname> - -
- -
- Gsec Commands - - After the assorted options, comes the command that you wish to run. The - following commands are available in both batch and interactive modes, but for - interactive mode the leading minus sign is not required. - - - - -add <name> [ <parameter> ... - ] - - This command adds a new user to the database. You may optionally add - other details such as first, middle and last names plus a password for the - new user, all in the same add command. - Alternatively, you may add a user then modify it to - fill in the missing details. - - - - -delete <name> - - This command removes the named user from the database. All details - of the user are removed and cannot be undone unless you add the user back - again. - - - - -display [ <name> ] + -admin {yes|no} - This command displays the details of a single named user, or all - users in the database. The password is never displayed. - - - - -modify <name> <parameter> [ - <parameter> ... ] - - + +
+ +
+ Gsec Commands + + After the assorted options, comes the command that you wish to run. + The following commands are available in both batch and interactive modes, + but for interactive mode the leading minus sign is not required. + + + + -add <name> [ <parameter> ... + ] + + This command adds a new user to the database. You may optionally + add other details such as first, middle and last names plus a password + for the new user, all in the same add command. + Alternatively, you may add a user then modify + it to fill in the missing details. + + + + -delete <name> + + This command removes the named user from the database. All + details of the user are removed and cannot be undone unless you add + the user back again. + + + + -display [ <name> ] + + This command displays the details of a single named user, or all + users in the database. The password is never displayed. + + + + -modify <name> <parameter> [ + <parameter> ... ] + + + + The <name> option is how you wish the user to be known when + connecting to Firebird databases. Some of the above commands take + parameters and these are one, or more, of the following : + + + + -pw <password> + + This parameter lets you supply a new password for the user. If + you omit the password, the current one will be removed and the user + will be unable to login to any Firebird databases at all. The password + can be up to 8 characters long, but when supplying one to + gsec, or logging into databases, the + characters after the eighth are simply ignored. + + + + -uid <uid> + + + + -gid <gid> + + -uid and -gid are + used on some POSIX systems to enter the Unix userid and groupid as + found in /etc/passwd and + /etc/group configuration files. If not supplied, + these default to zero. + + + + -fname [ <first name> ] + + This parameter allows you to store the user's first name in the + database. This helps when identifying users from their login name - + which may be abbreviated. You can delete a first name by not supplying + a name. + + + + -mname [ <middle name> ] + + This parameter allows you to store the user's middle name in the + database. This helps when identifying users from their login name - + which may be abbreviated. You can delete a middle name by not + supplying a name. + + + + -lname [ <lastname> ] + + This parameter allows you to store the user's last name in the + database. This helps when identifying users from their login name - + which may be abbreviated. You can delete a last name by not supplying + a name. + + + + -admin yes | no + + This parameter allows you to specify whether or not the user + will be granted the RDB$ADMIN role. - The <name> option is how you wish the user to be known when connecting - to Firebird databases. Some of the above commands take parameters and these are - one, or more, of the following : - - - - -pw <password> - - This parameter lets you supply a new password for the user. If you - omit the password, the current one will be removed and the user will be - unable to login to any Firebird databases at all. The password can be up - to 8 characters long, but when supplying one to - gsec, or logging into databases, the characters - after the eighth are simply ignored. - - - - -uid <uid> - - - - -gid <gid> - - -uid and -gid are used - on some POSIX systems to enter the Unix userid and groupid as found in - /etc/passwd and /etc/group - configuration files. If not supplied, these default to zero. - - - - -fname [ <first name> ] - - This parameter allows you to store the user's first name in the - database. This helps when identifying users from their login name - which - may be abbreviated. You can delete a first name by not supplying a - name. - - - - -mname [ <middle name> ] - - This parameter allows you to store the user's middle name in the - database. This helps when identifying users from their login name - which - may be abbreviated. You can delete a middle name by not supplying a - name. - - - - -lname [ <lastname> ] - - This parameter allows you to store the user's last name in the - database. This helps when identifying users from their login name - which - may be abbreviated. You can delete a last name by not supplying a - name. - - -
+ + Firebird 2.5 onwards. + + + +
-
- Interactive Mode +
+ Interactive Mode - To run gsec in interactive mode, start the - utility using the command line : + To run gsec in interactive mode, start + the utility using the command line : - C:\>gsec -user sysdba -password masterkey + C:\>gsec -user sysdba -password masterkey GSEC> - The GSEC> prompt shows that the utility is waiting for a command. The - -user and -password options are - those of the user who wishes to manipulate the security database. Obviously, the - username supplied must be a valid SYSDBA user if updates are to be carried out. - Normal users may only read the database. - - - With Firebird 1.5 and Windows Vista this may not work correctly and an - 'unavailable database' error will be displayed. The problem is caused by - trying to use the IPCServer transport implemented in Firebird 1.5 which - doesn't work on Vista. The solution is to use TCP local loopback. - - - - Put an alias in aliases.conf for the path - to your security.fdb, e.g. sec = - C:\Program - Files\Firebird\Firebird_1_5\security.fdb. - - - - Call gsec using gsec - -database localhost:sec -user SYSDBA -password masterkey - - - - - As localhost may not be available on some Vista workstations you may - have to change localhost in the command above to use the actual hostname or - the IP address of the Vista computer. - - - To exit gsec in - interactive mode, the quit command is used : - - GSEC> quit + The GSEC> prompt shows that the utility is waiting for a command. + The -user and -password + options are those of the user who wishes to manipulate the security + database. Obviously, the username supplied must be a valid SYSDBA user if + updates are to be carried out. Normal users may only read the + database. + + + With Firebird 1.5 and Windows Vista this may not work correctly + and an 'unavailable database' error will be displayed. The problem is + caused by trying to use the IPCServer transport implemented in Firebird + 1.5 which doesn't work on Vista. The solution is to use TCP local + loopback. + + + + Put an alias in aliases.conf for the path + to your security.fdb, e.g. sec = + C:\Program + Files\Firebird\Firebird_1_5\security.fdb. + + + + Call gsec using gsec + -database localhost:sec -user SYSDBA -password masterkey + + + + + As localhost may not be available on some Vista workstations you + may have to change localhost in the command above to use the actual host + name or the IP address of the Vista computer. + + + To exit gsec + in interactive mode, the quit command is used + : + + GSEC> quit C:\> - The following sections show how to carry out various commands in interactive - mode. It is assumed that you are already running the utility as a SYSDBA - user. + The following sections show how to carry out various commands in + interactive mode. It is assumed that you are already running the utility + as a SYSDBA user. + +
+ Displaying User Details -
- Displaying User Details + + From Firebird 2.5 onwards, the display command shows an + additional column named admin. This shows the text admin where a user + has been granted the RDB$ADMIN role either within the database, or by + using gsec. In the following examples, + where it is necessary to show this detail, it will be shown, + otherwise, all output examples are as per Firebird 2.0. + - To display all users in the security database the command, and it's - output are : + To display all users in the security database the command, and + it's output are : - GSEC> display + GSEC> display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 @@ -413,52 +465,69 @@ NORMAN 0 0 Norman Dunbar EPOCMAN 0 0 Benoit Gilles Mascia GSEC> - To display details of a single user, pass the username as a parameter to - the display command. + To display details of a single user, pass the username as a + parameter to the display command. - GSEC> display epocman + GSEC> display epocman user name uid gid full name ------------------------------------------------------------------------ EPOCMAN 0 0 Benoit Gilles Mascia GSEC> - If you enter the name of a non-existent user as a parameter of the - display command, nothing is displayed and gsec remains - in interactive mode. + If you enter the name of a non-existent user as a parameter of the + display command, nothing is displayed and gsec + remains in interactive mode. - GSEC> display alison + GSEC> display alison GSEC> -
+
-
- Adding New Users +
+ Adding New Users - When adding a new user in interactive mode, nothing is displayed to - confirm that the user was indeed added. You need to use the - display or display <name> - commands to make sure that the user was added successfully. + When adding a new user in interactive mode, nothing is displayed + to confirm that the user was indeed added. You need to use the + display or display + <name> commands to make sure that the user was added + successfully. - GSEC> add newuser -pw newuser -fname New -lname User + GSEC> add newuser -pw newuser -fname New -lname User GSEC> - GSEC> display newuser + GSEC> display newuser user name uid gid full name ------------------------------------------------------------------------ NEWUSER 0 0 New User GSEC> -
-
- Deleting Existing Users + From Firebird 2.5 onwards, a new role - RDB$ADMIN - has been added + to the security database. Gsec allows you to + indicate whether new users are assigned this role. The display command + has also been modified to show whether a user had this role or not. + - When deleting a user in interactive mode, there is no confirmation that - the user has been deleted. You should use the display - or display <name> command to check. + GSEC> add newadmin -pw secret -fname New -mname admin -lname User -admin yes +GSEC> - GSEC> delete newuser + GSEC> display newadmin + user name uid gid admin full name +------------------------------------------------------------------------------------------------ +NEWADMIN 0 0 admin New admin User GSEC> +
+ +
+ Deleting Existing Users + + When deleting a user in interactive mode, there is no confirmation + that the user has been deleted. You should use the + display or display + <name> command to check. - GSEC> display + GSEC> delete newuser +GSEC> + + GSEC> display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 @@ -466,486 +535,615 @@ NORMAN 0 0 Norman Dunbar EPOCMAN 0 0 Benoit Gilles Mascia GSEC> - If, on the other hand, you try to delete a non-existing user, - gsec will display an error message, and - exit. + If, on the other hand, you try to delete a non-existing user, + gsec will display an error message, and + exit. - GSEC> delete newuser + GSEC> delete newuser record not found for user: NEWUSER C:\> -
+
-
- Amending Existing Users +
+ Amending Existing Users - Existing users can have one or more of their password, first name, - middle name or lastname amended. There is no confirmation that your - modification has worked, so you must use one of the - display commands to determine how well it - worked. + Existing users can have one or more of their password, first name, + middle name or lastname amended. There is no confirmation that your + modification has worked, so you must use one of the + display commands to determine how well it + worked. - GSEC> modify norman -pw newpassword + GSEC> modify norman -pw newpassword GSEC> - GSEC> modify norman -mname MiddleName -fname Fred + GSEC> modify norman -mname MiddleName -fname Fred GSEC> - GSEC> display norman + GSEC> display norman user name uid gid full name ------------------------------------------------------------------------ NORMAN 0 0 Fred MiddleName Dunbar GSEC> - If you wish to remove one or more of a user's attributes, don't pass a - (new) value for that attribute. + If you wish to remove one or more of a user's attributes, don't + pass a (new) value for that attribute. - GSEC> modify norman -mname -fname -lname + GSEC> modify norman -mname -fname -lname - GSEC> display norman + GSEC> display norman user name uid gid full name ------------------------------------------------------------------------ -NORMAN 0 0 +NORMAN 0 0 +GSEC> - Now I can be known as 'the man with no name', just like Clint Eastwood - ! -
+ Now I can be known as 'the man with no name', just like Clint + Eastwood ! -
- Help + From Firebird 2.5 onwards, a user's admin rights can be modified + using this command: - The help command, in interactive mode, displays - the same help screen as shown above. -
+ GSEC> modify norman -admin yes -
- Version Information + GSEC> display norman + user name uid gid admin full name +------------------------------------------------------------------------------------------------ +NORMAN 0 0 admin New admin User +GSEC> +
- The version of gsec can be obtained using the - z command. +
+ OS Admin Mapping - GSEC> z -gsec version WI-V1.5.0.4306 Firebird 1.5 -GSEC> -
-
+ + Firebird 2.5. + -
- Batch Mode + Since Firebird 2.1, Windows domain administrators have had + full access to the user management functions. This + meant that when an admin user connected to the server and then used + gsec, they had the ability to modify + any user account in the security database. - - In the following descriptions of batch mode operations, assume that I - have set the ISC_USER and ISC_PASSWORD - environment variables. This allows gsec to be run - without always having to specify the -user and - -password switches. This in turn reduces the amount of - code on the command line, which means that when this XML file is rendered into - pdf, all the commandline will fit on the width of an A4 page. - - It is not secure to have these variables set all the time, so don't do - it ! - + From Firebird 2.5 they do not get these + privileges automatically unless the DBA has configured the security + database to make it happen automatically. This is done either in + isql as follows: - - If you are using gsec from Firebird version - 1.5 (and possibly version 1.0 as well) then when you are running in batch - mode, you may think that you can check the result of an operation by checking - %ERRORLEVEL% in Windows, or $? in various - flavours of Unix. This doesn't work. The result is always zero. + SQL> SQL> alter role rdb$admin set auto admin mapping; +SQL> commit; + + + The command above will cause all Windows Administrator accounts to + automatically have full access to the user management functions. The + automatic mapping can be revoked as follows: - In gsec from Firebird version 2.0 onwards, - this problem is fixed and the exit code will be zero for everything was ok, or - a non-zero value for error conditions. - + SQL> SQL> alter role rdb$admin drop auto admin mapping; +SQL> commit; + - In batch mode, the command line to run gsec is as - follows : + The functionality of the above isql + commands can also be set using gsec, as + follows, by using the -mapping command. The + command takes a parameter of set or + drop accordingly. - gsec [ <options> ... ] <command> [ <parameter> ... ] + GSEC> mapping set -
- Displaying User Details + or: - To display all users in the security database the command, and its - output are : + GSEC> mapping drop +
+ +
+ Help + + The help command, in interactive mode, + displays the same help screen as shown above. From Firebird 2.5, this + can be abbreviated to a single question mark. +
- C:\>gsec -display +
+ Version Information + + The version of gsec can be obtained + using the z command. + + GSEC> z +gsec version WI-V1.5.0.4306 Firebird 1.5 +GSEC> + + Or, in gsec from Firebird 2.5: + + GSEC> z +gsec version LI-V2.5.0.26074 Firebird 2.5 +GSEC> + +
+
+ +
+ Batch Mode + + + In the following descriptions of batch mode operations, assume + that I have set the ISC_USER and + ISC_PASSWORD environment variables. This allows + gsec to be run without always having to + specify the -user and + -password switches. This in turn reduces the + amount of code on the command line, which means that when this XML file + is rendered into pdf, all the command line will fit on the width of an + A4 page. + + It is not secure to have these variables set all the time, so + don't do it ! + + + + If you are using gsec from Firebird + version 1.5 (and possibly version 1.0 as well) then when you are running + in batch mode, you may think that you can check the result of an + operation by checking %ERRORLEVEL% in Windows, or + $? in various flavours of Unix. This doesn't work. The + result is always zero. + + In gsec from Firebird version 2.0 + onwards, this problem is fixed and the exit code will be zero for + everything was ok, or a non-zero value for error conditions. + + + In batch mode, the command line to run + gsec is as follows : + + gsec [ <options> ... ] <command> [ <parameter> ... ] + +
+ Displaying User Details + + To display all users in the security database the command, and its + output are : + + C:\>gsec -display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 NORMAN 0 0 Norman Dunbar EPOCMAN 0 0 Benoit Gilles Mascia - To display details of a single user, pass the username as a parameter to - the display command. + To display details of a single user, pass the username as a + parameter to the display command. - C:\>gsec -display epocman + C:\>gsec -display epocman user name uid gid full name ------------------------------------------------------------------------ EPOCMAN 0 0 Benoit Gilles Mascia -
+
-
- Adding New Users +
+ Adding New Users - When adding a user in batch mode, there is no confirmation that the user - has been added. You should use the -display or - -display <name> command to check. + When adding a user in batch mode, there is no confirmation that + the user has been added. You should use the + -display or -display + <name> command to check. - C:\>gsec -add newuser -pw newuser -fname New -lname User + C:\>gsec -add newuser -pw newuser -fname New -lname User - C:\>gsec -display + C:\>gsec -display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 NORMAN 0 0 Norman Dunbar NEWUSER 0 0 New User EPOCMAN 0 0 Benoit Gilles Mascia -
-
- Deleting Existing Users + Under Firebird 2.5, the -admin parameter + may be specified: + + C:\>gsec -add newadmin -pw ignoreit -fname New -mname Admin -lname User -admin yes + + + c:\>gsec -display newadmin + user name uid gid admin full name +------------------------------------------------------------------------------------------------ +NEWADMIN 0 0 New Admin User +
- When deleting a user in batch mode, there is no confirmation that the - user has been deleted. You should use the -display or - -display <name> command to check. +
+ Deleting Existing Users - C:\>gsec -delete newuser + When deleting a user in batch mode, there is no confirmation that + the user has been deleted. You should use the + -display or -display + <name> command to check. - C:\>gsec -display + C:\>gsec -delete newuser + + C:\>gsec -display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 NORMAN 0 0 Norman Dunbar EPOCMAN 0 0 Benoit Gilles Mascia -
+
-
- Amending Existing Users +
+ Amending Existing Users - Existing users can have one or more of their password, first name, - middle name or lastname amended. + Existing users can have one or more of their password, first name, + middle name, lastname or admin rights amended. - C:\>gsec -modify norman -pw newpassword + C:\>gsec -modify norman -pw newpassword - C:\>gsec -modify norman -mname MiddleName -fname Fred + C:\>gsec -modify norman -mname MiddleName -fname Fred - C:\>gsec -display + C:\>gsec -display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 NORMAN 0 0 Fred MiddleName Dunbar EPOCMAN 0 0 Benoit Gilles Mascia - If you wish to remove one or more of a user's attributes, don't pass a - (new) value for that attribute. + If you wish to remove one or more of a user's attributes, don't + pass a (new) value for that attribute. - C:\>gsec -modify norman -mname -fname -lname + C:\>gsec -modify norman -mname -fname -lname - C:\>gsec -display + C:\>gsec -display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 NORMAN 0 0 EPOCMAN 0 0 Benoit Gilles Mascia - Now nobody knows who I am :o) -
+ Now nobody knows who I am :o) +
-
- Version Information +
+ Version Information - The version of gsec can be obtained using the -z - command. However, note that it leaves you in interactive mode on completion. - It doesn't exit like the other batch mode commands do, so you have to use the - interactive quit command to exit. There is a way around - this problem as shown in the following. The first part shows the - problem. + The version of gsec can be obtained using the + -z command. However, note that it leaves you in + interactive mode on completion. It doesn't exit like the other batch + mode commands do, so you have to use the interactive + quit command to exit. There is a way around this + problem as shown in the following. The first part shows the problem - + which still exists in Firebird 2.5. - C:\>gsec -z + C:\>gsec -z gsec version WI-V1.5.0.4306 Firebird 1.5 GSEC> - The solution is to have a small file containing the command - quit and force gsec to read this file when it needs - user input, as follows. + The solution is to have a small file containing the command + quit and force gsec to read this file when it + needs user input, as follows. - C:\>copy con fred + C:\>copy con fred quit ^Z 1 file(s) copied. - C:\>gsec -z <fred + C:\>gsec -z <fred gsec version WI-V1.5.0.4306 Firebird 1.5 GSEC> C:\> - This could be a good idea for any of the commands which leave you - 'stuck' in the interactive mode when you thought you were running in batch - mode. By redirecting input from a command file, gsec will read a line of text - from that file any time it requires user input. By forcing it to read the - quit command, you make it exit. - - - The -z command doesn't need a - -user and -password, it will - display the version details and then tell you that you don't have a - username/password - but you can safely ignore this message. - -
+ This could be a good idea for any of the commands which leave you + 'stuck' in the interactive mode when you thought you were running in + batch mode. By redirecting input from a command file, gsec will read a + line of text from that file any time it requires user input. By forcing + it to read the quit command, you make it + exit. + + + The -z command doesn't need a + -user and -password, it + will display the version details and then tell you that you don't have + a username/password - but you can safely ignore this message. +
-
- Running Gsec Remotely +
+ OS Admin Mapping - Gsec can be used to administer the security - database on a remote server. To do this you must supply the remote security - database name on the commandline as shown in the following example which connects - my Windows XP client version of gsec to my Linux server - named Ganymede and allows me to manage the users on my Linux server. + + Firebird 2.5. + - C:\>gsec -database ganymede:/opt/firebird/security2.fdb - -user sysdba -password masterkey -GSEC> + Since Firebird 2.1, Windows domain administrators have had + full access to the user management functions. This + meant that when an admin user connected to the server and then used + gsec, they had the ability to modify any user account in the security + database. - - In the above example, I have split the full commandline over two lines. - This is to prevent it 'falling off' the right side of the page when this - manual is rendered as a PDF document. The whole command should, indeed must, - be typed on a single line. + The functionality that allows Windows domain administrators to + have full access to the user management functions + of the Firebird's security database, can also be set using + gsec on the command line as follows, by using + the -mapping command. The command takes a + parameter of set or drop + accordingly. - Also note that if there are spaces in the database name, you must - enclose the whole parameter in double quotes. - + C:/> gsec -mapping set - Once connected to the remote security database, you can manipulate users in - the normal manner in either interactive or batch modes as described above. + or: - The version of gsec provided in Firebird 2.0 can be used to maintain the - security database on previous versions of Firebird and it is hoped, Interbase from - version 6.0 upwards. However, from version 2.0 of Firebird, the format of the - security database changed and because of this, gsec from an older version cannot - be used to maintain the security database for Firebird 2.0 onwards. + C:/> gsec -mapping drop
+
-
- Gsec caveats +
+ Running Gsec Remotely - The following is a brief list of gotchas and funnies that I have detected in - my own use of gsec. Some of these are mentioned above, others may not be. By - collecting them all here in one place, you should be able to find out what's - happening if you have problems. + Gsec can be used to administer the + security database on a remote server. To do this you must supply the + remote security database name on the command line as shown in the + following example which connects my Windows XP client version of + gsec to my Linux server named ganymede and + allows me to manage the users on my Linux server. -
- Normal Versus Privileged Users - - Only a privileged user can update the security database. Normal users - can run the gsec utility, but can only list the - contents under Firebird 1.5. The following shows what happens when trying to - update the database when running gsec as a normal - user. + C:\>gsec -database ganymede:/opt/firebird/security2.fdb + -user sysdba -password masterkey +GSEC> - C:\>gsec -user norman -password norman + + In the above example, I have split the full command line over two + lines. This is to prevent it 'falling off' the right side of the page + when this manual is rendered as a PDF document. The whole command + should, indeed must, be typed on a single line. + + Also note that if there are spaces in the database path, you must + enclose the whole parameter in double quotes. + + + Once connected to the remote security database, you can manipulate + users in the normal manner in either interactive or batch modes as + described above. + + The version of gsec provided in Firebird + 2.0 can be used to maintain the security database on previous versions of + Firebird and it is hoped, Interbase from version 6.0 upwards. However, + from version 2.0 of Firebird, the format of the security database changed + and because of this, gsec from an older version cannot be used to maintain + the security database for Firebird 2.0 onwards. +
+ +
+ Gsec caveats + + The following is a brief list of gotchas and funnies that I have + detected in my own use of gsec. Some of these + are mentioned above, others may not be. By collecting them all here in one + place, you should be able to find out what's happening if you have + problems. + +
+ Normal Versus Privileged Users + + Only a privileged user can update the security database. Normal + users can run the gsec utility, but can only + list the contents under Firebird 1.5. The following shows what happens + when trying to update the database when running + gsec as a normal user. + + C:\>gsec -user norman -password norman GSEC> add myuser -pw mypassword add record error no permission for insert/write access to TABLE USERS - A normal users can only display details from the security - database. + A normal users can only display details from the security + database. - C:\>gsec -user norman -password norman -display + C:\>gsec -user norman -password norman -display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 NORMAN 0 0 Norman Dunbar EPOCMAN 0 0 Benoit Gilles Mascia - - From Firebird version 2 onwards, there are slight changes to the - above. Normal users are now able to change their own passwords and can no - longer display details of other users that may be present in the security - database. - + + From Firebird version 2 onwards, there are slight changes to the + above. Normal users are now able to change their own passwords and can + no longer display details of other users that may be present in the + security database. + - The above user, running under Firebird 2.0 would see the following - : + The above user, running under Firebird 2.0 would see the following + : - C:\>gsec -user norman -password norman -display + C:\>gsec -user norman -password norman -display user name uid gid full name ------------------------------------------------------------------------ NORMAN 0 0 Norman Dunbar -
+
-
- Differences Between Batch And Interactive Mode +
+ Differences Between Batch And Interactive Mode - The gsec commands apply to both modes of - operation, however, when running in batch mode, you must prefix the command - name with a minus sign (-) or you will get an error message similar to the - following : + The gsec commands apply to both modes + of operation, however, when running in batch mode, you must prefix the + command name with a minus sign (-) or you will get an error message + similar to the following : - C:\>gsec -user sysdba -password masterkey display + C:\>gsec -user sysdba -password masterkey display invalid parameter, no switch defined error in switch specifications GSEC> - Note also that you will be left in interactive mode when an error - occurs. The correct commandline should have a minus in front of the - display command, as follows : + Note also that you will be left in interactive mode when an error + occurs. The correct command line should have a minus in front of the + display command, as follows : - C:\>gsec -user sysdba -password masterkey -display + C:\>gsec -user sysdba -password masterkey -display user name uid gid full name ------------------------------------------------------------------------ SYSDBA 0 0 NORMAN 0 0 Norman Dunbar EPOCMAN 0 0 Benoit Gilles Mascia - This time, gsec performed its duties, - displayed all known users and quit from the utility. - - - If environment variables ISC_USER and - ISC_PASSWORD have been defined, and this isn't a very good - idea for security reasons, gsec can be run - without passing the -user or - -password options. - - - - As with all of the command line utilities, it is best to use the - version of the gsec utility that was supplied - with your database. - -
- -
- Batch Mode Exit Codes - - When running gsec under windows, you can trap - the exit code in %ERRORLEVEL% and check it to determine the - success or failure of the last command executed. - - When your operating system is Unix - whatever flavour - the exit code is - to be found in the $? variable. - - Unfortunately, using the version of gsec - supplied with Firebird 1.5, it appears that gsec - always exits with a zero and this makes it quite unsuitable to build into a - properly error trapped batch script on either system. Sad but true. - - - From version 2.0 of Firebird, this has been corrected and an exit - code of zero indicates success while non-zero values indicate - failures. - -
- -
- Errors In Batch Mode Swap To Interactive Mode - - Sometimes, when running in batch mode, an error condition in gsec will - result in gsec switching over to interactive mode. This is not very useful if - you started gsec in batch mode from a script, because your script will just - sit there waiting on something to be typed. -
- -
- Potential Security Problems - - Up until Firebird 2.0, running any of the Firebird - utilities with a password supplied on the command line meant that anyone - logged on to the same server could call ps -efx|grep -i - pass (or similar) and be able to see the SYSDBA or other passwords. - From Firebird 2.0 this is no longer possible as Firebird now replaces the - supplied password with spaces. -
+ This time, gsec performed its duties, + displayed all known users and quit from the utility. + + + If environment variables ISC_USER and + ISC_PASSWORD have been defined, and this isn't a very + good idea for security reasons, gsec can be + run without passing the -user or + -password options. + + + + As with all of the command line utilities, it is best to use the + version of the gsec utility that was + supplied with your database. + +
+ +
+ Batch Mode Exit Codes + + When running gsec under windows, you + can trap the exit code in %ERRORLEVEL% and check it to + determine the success or failure of the last command executed. + + When your operating system is Unix - whatever flavour - the exit + code is to be found in the $? variable. + + Unfortunately, using the version of + gsec supplied with Firebird 1.5, it appears + that gsec always exits with a zero and this + makes it quite unsuitable to build into a properly error trapped batch + script on either system. Sad but true. + + + From version 2.0 of Firebird, this has been corrected and an + exit code of zero indicates success while non-zero values indicate + failures. + +
+ +
+ Errors In Batch Mode Swap To Interactive Mode + + Sometimes, when running in batch mode, an error condition in gsec + will result in gsec switching over to interactive mode. This is not very + useful if you started gsec in batch mode from a script, because your + script will just sit there waiting on something to be typed. +
+ +
+ Potential Security Problems + + Up until Firebird 2.0, running any of the + Firebird utilities with a password supplied on the command line meant + that anyone logged on to the same server could call ps + -efx|grep -i pass (or similar) and be able to see the SYSDBA + or other passwords. From Firebird 2.0 this is no longer possible as + Firebird now replaces the supplied password with spaces.
+
+ + + Document history + + The exact file history is recorded in the manual module in our CVS tree; see http://sourceforge.net/cvs/?group_id=9028. + The full URL of the CVS log for this file can be found at http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/fbutil_gsec.xml?view=log + + + + 1.0 + + 9 November 2004 + + ND - - Document history + + Created as a chapter in the Command Line Utilities + manual. + + - The exact file history is recorded in the manual module in our CVS tree; see http://sourceforge.net/cvs/?group_id=9028. - The full URL of the CVS log for this file can be found at http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/fbutil_gsec.xml?view=log + + 1.1 - - - 1.0 + 19 November 2004 - 9 November 2004 + ND - ND + + Updated for Firebird 2.0. + + - - Created as a chapter in the Command Line Utilities - manual. - - + + 1.2 - - 1.1 + 20 October 2009 - 19 November 2004 + ND - ND + + More minor updates and converted to a stand alone + manual. + + - - Updated for Firebird 2.0. - - + + 1.3 - - 1.2 + 05 January 2010 - 20 October 2009 + ND - ND + + Updated with details of Firebird 1.5 and Windows Vista not + working when using IPCServer protocol. Thanks to Helen Borrie for + the fix information. + + - - More minor updates and converted to a stand alone - manual. - - + + 1.4 - - 1.3 + 11 October 2011 - 05 January 2010 + ND - ND + + Updated for Firebird 2.5. - - Updated with details of Firebird 1.5 and Windows Vista not - working when using IPCServer protocol. Thanks to Helen Borrie for - the fix information. - - - - + Spelling errors corrected. + + + + - - License notice + + License notice - The contents of this Documentation are subject to the Public Documentation - License Version 1.0 (the License); you may only use this - Documentation if you comply with the terms of this License. Copies of the License - are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf - (PDF) and http://www.firebirdsql.org/manual/pdl.html - (HTML). + The contents of this Documentation are subject to the Public + Documentation License Version 1.0 (the License); you may + only use this Documentation if you comply with the terms of this License. + Copies of the License are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) and http://www.firebirdsql.org/manual/pdl.html + (HTML). - The Original Documentation is titled Firebird Password File - Utility. + The Original Documentation is titled Firebird Password + File Utility. - The Initial Writer of the Original Documentation is: Norman Dunbar. + The Initial Writer of the Original Documentation is: Norman + Dunbar. - Copyright (C) 2004–2009. All Rights Reserved. Initial Writer contact: - NormanDunbar at users dot sourceforge dot net. - + Copyright (C) 2004–2009. All Rights Reserved. Initial Writer + contact: NormanDunbar at users dot sourceforge dot net. +
diff --git a/src/docs/firebirddocs/fbutil_gstat.xml b/src/docs/firebirddocs/fbutil_gstat.xml index c9130405..c47de419 100644 --- a/src/docs/firebirddocs/fbutil_gstat.xml +++ b/src/docs/firebirddocs/fbutil_gstat.xml @@ -18,7 +18,7 @@ Dunbar - 23 March 2011 – Document version 1.4 + 11 October 2011 – Document version 1.5
@@ -87,20 +87,26 @@ connection to the server - it reads the database file directly. If gstat is called with an invalid - switch, the following is displayed to remind you of the valid ones. Only + switch, or with the new -? switch from Firebird 2.5 + onwards, the following is displayed to remind you of the valid ones. Only the short form of the switches is displayed, unfortunately. - Available switches: + ./gstat -? +usage: gstat [options] <database> or gstat <database> [options] +Available switches: -a analyze data and index pages -d analyze data pages - -h analyze header page + -h analyze header page ONLY -i analyze index leaf pages - -s analyze system relations + -s analyze system relations in addition to user tables -u username -p password + -fetch fetch password from file -r analyze average record and version length - -t tablename + -t tablename <tablename2...> (case sensitive) -z display version number +option -t accepts several table names only if used after <database> + @@ -111,6 +117,11 @@ removed from gstat. + + The -fetch switch is only available from + Firebird 2.5 onwards. + + These switches are described below. @@ -243,6 +254,24 @@ the server using a privileged account. + + -fetch <password file name> | stdin + | /dev/tty + + This switch causes the password for the appropriate user to be + read from a file as opposed to being specified on the command line. + The file name supplied is not in quotes and must + be readable by the user running gstat. If + the file name is specified as stdin, then the + user will be prompted for a password. On POSIX systems, the file name + /dev/tty will also result in a + prompt for the password. + + + Firebird 2.5 onwards. + + + -z @@ -421,6 +450,10 @@ Database header page information: 11.1 for Firebird 2.1 + + + 11.2 for Firebird 2.5 + @@ -558,7 +591,7 @@ Database header page information: - Because of the incosistency between what + Because of the inconsistency between what gstat reports and reality, it is best to use isql and the SHOW DATABASE command to view correct details of the shadow files. @@ -1493,13 +1526,27 @@ tux> gstat employee -h | grep -i sh[a]dow values. Added reference to Managing Limbo Transactions in the gfix - manaual. + manual. Corrected explanation of when an automatic database sweep is carried out, based on OIT and OST as opposed to OIT and OAT. As advised by Vlad Khorsun. + + + 1.5 + + 11 October 2011 + + ND + + + Updated for Firebird 2.5. + + Spelling errors corrected. + + From 38f0830e1f19534bc0e0105a03f475523aaa7256 Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Thu, 13 Oct 2011 13:38:00 +0000 Subject: [PATCH 09/33] Various files updated for the use of xi:includes. Fbmgr updated to include details of fbguard and to indicate forthcoming demise. --- src/docs/firebirddocs.xml | 176 +++++-------- src/docs/firebirddocs/fbcache.xml | 6 +- src/docs/firebirddocs/fbutil_fbmgr.xml | 259 +++++++++++++++++++- src/docs/firebirddocs/fbutil_gbak.xml | 10 +- src/docs/firebirddocs/fbutil_gfix.xml | 6 +- src/docs/firebirddocs/fbutil_gsec.xml | 6 +- src/docs/firebirddocs/fbutil_gsplit.xml | 6 +- src/docs/firebirddocs/fbutil_gstat.xml | 6 +- src/docs/firebirddocs/fbutil_isql.xml | 25 +- src/docs/firebirddocs/fbutil_scripts.xml | 6 +- src/docs/firebirddocs/firebirdinternals.xml | 4 +- 11 files changed, 339 insertions(+), 171 deletions(-) diff --git a/src/docs/firebirddocs.xml b/src/docs/firebirddocs.xml index 75f60fd5..42de6ec6 100644 --- a/src/docs/firebirddocs.xml +++ b/src/docs/firebirddocs.xml @@ -1,138 +1,84 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]> - + Firebird Documentation Set Firebird Docset - - : All contributions are Copyright of their individual - authors, except where otherwise noted. + 2000–2012 + All contributions are Copyright of their individual authors, except where otherwise + noted. Overview - This is the index to the English documentation produced within the Firebird Project. - For a full Firebird documentation index, visit the URLs below: -
- http://www.firebirdsql.org/index.php?op=doc - http://www.firebirdsql.org/index.php?op=doc&id=othersites -
+ This is the index to the English documentation produced within the Firebird Project. For + a full Firebird documentation index, visit the URLs below: +
+ http://www.firebirdsql.org/index.php?op=doc + http://www.firebirdsql.org/index.php?op=doc&id=othersites +
The Firebird Documentation Subproject homepage is here: -
- http://www.firebirdsql.org/index.php?op=devel&sub=doc -
+
+ http://www.firebirdsql.org/index.php?op=devel&sub=doc +
- - - &uf; - Firebird Database Documentation Firebird Database Docs + + + + + + + + + + + + + + + + - - - - &quickstartguide25; - &quickstartguide2; - &quickstartguide15; - &quickstartguide10; - &ubuntu-setup; - &fbmetasecur; - &nullguide; - &generatorguide; - &migrationmssql; - &coexist-article; - &nbackup; - &fbutilities-gsec; - &fbutilities-gfix; - &fbutilities-gsplit; - &fbutilities-scripts; - &fbutilities-gbak; - &fbutilities-fbmgr; - &fbutilities-gstat; - &fbutilities-isql; - &fbcache; - &fb-internals; - - - + + + + Firebird Command Line Utilities + Firebird Utilities + + + + + + + + + - - + + + + Firebird Internal Information + Firebird Internals + + + + + + - &fb-docwriters-info; - - - &licenses; - + + + diff --git a/src/docs/firebirddocs/fbcache.xml b/src/docs/firebirddocs/fbcache.xml index 64e661ca..87619a4d 100644 --- a/src/docs/firebirddocs/fbcache.xml +++ b/src/docs/firebirddocs/fbcache.xml @@ -1,8 +1,6 @@ - +
Firebird Database Cache Buffer diff --git a/src/docs/firebirddocs/fbutil_fbmgr.xml b/src/docs/firebirddocs/fbutil_fbmgr.xml index 68dd1962..5e00e0dc 100644 --- a/src/docs/firebirddocs/fbutil_fbmgr.xml +++ b/src/docs/firebirddocs/fbutil_fbmgr.xml @@ -1,8 +1,6 @@ - +
Firebird Superserver Manager @@ -15,7 +13,7 @@ Dunbar - 11 October 2011 – Document version 1.5 + 13 October 2011 – Document version 1.6
@@ -34,6 +32,16 @@ may not even exist in your installation directory. + + If you are using Firebird 2.5 onwards, you will see a message + whenever you use fbmgr, telling you that + fbmgr has been deprecated. From Firebird 3.0 + onwards, this utility will no longer be present in the Firebird + releases. You are advised to use the fbguard + utility instead. See the chapter on fbguard + for details. + + On Windows systems, the engine runs as a service and is slightly different. Windows will be discussed separately in this manual for that reason. @@ -69,7 +77,7 @@
- Linux Systems. + Fbmgr on Linux Systems. On Linux, the Firebird engine is started whenever you carry out an install - from an RPM or via a script - and at system boot time. This @@ -228,9 +236,10 @@ tux> passwd firebird
Fbmgr Commands. - Fbmgr can be run interactively or in batch mode. The commands are - identical whichever mode you use and the following section describes the - commands and shows examples of each, running in both modes. + Fbmgr can be run interactively or in + batch mode. The commands are identical whichever mode you use and the + following section describes the commands and shows examples of each, + running in both modes. To enter interactive mode, simply log in as the firebird user and type the command fbmgr. If Getting Help. To see a list of all the commands - except, for some reason, the - start command - run fbmgr and pass the + start command - run + fbmgr and pass the -help command (in batch mode) or type help at the prompt in interactive mode. The resulting output is the same regardless, including the grammatical @@ -288,13 +298,21 @@ fbmgr<RETURN> FBMGR> password <password> FBMGR> shut + + + When using this option under Firebird 2.5, an additional line + is printed at the beginning of the output advising you that + fbmgr is deprecated and will be + removed soon. +
Starting Up. When the Firebird engine is started, it normally runs under the - watchful eyes of the guardian process. The guardian will restart the + watchful eyes of the guardian process - + fbguard. The guardian will restart the engine any time it determines that the engine has crashed and in doing so, will hopefully reduce the downtime that the users may suffer as a result of a crashed engine. @@ -506,6 +524,199 @@ ps -ef | grep -i firebird | grep -v grep
+
+ Fguard on Linux Systems. + + From Firebird 2.5 onwards the use of + fbmgr is deprecated and from Firebird 3.0, it + will be removed. The fbguard utility, which was + actually used by fbmgr, should be used instead. + The system start and stop scripts, as described in the previous chapter, + use fbguard to start and stop the Firebird + engine at system startup and shutdown. + +
+ Fguard Commands. + + + For best results and security, you are advised to + always start and stop the Firebird engine using + the default scripts /etc/init.d/firebird or the + alias rcfirebird. These scripts carry out various + checks to ensure that the engine runs as the correct user, makes sure + that the guardian process watches over the engine and so on. Running + fbguard on its own makes no such checks and + can lead to databases becoming unavailable due to + being owned by root, for example - because this command always runs + the Firebird engine as the root user. + + + Fguard cannot be run interactively, you + must supply the required commands on the command line when executing + fbguard. Fbguard + can be run as the firebird user, for example, but will always cause the + engine itself to run as root. This may be a cause of serious concern for + system administrators. If you create any databases while the engine is + running as root then those databases will be owned by root and you will + not be able to access it at some future point when + the engine runs - correctly - as the firebird user. + + If you always use the /etc/init.d.firebird + (or rcfirebird) command to start and stop the + engine, it will always run as the firebird user, + regardless of which user you actually run the command as. + + + You cannot mix and match the various methods of starting and + stopping the engine. If you use fbguard to + start the engine, you need to kill the + fbserver process to stop it. If you use + /etc/init.d/firebird (or + rcfirebird) to start the engine, you + must use the corresponding stop script. You + cannot shut down the engine with rcfirebird + stop, for example, if you started it with + fbguard. + + +
+ Getting Help. + + To see a list of all the commands run + fbguard passing the + -help command. The resulting output is as + follows: + + tux> cd /opt/firebird/bin +tux> ./fbguard -help +Usage: fbguard [-signore|-onetime|-forever (default)][-daemon][-pidfile filename] + + + The use of the -daemon option forces the + engine to run as a daemon. If you run the + fbguard command to start the engine from a + terminal session, your terminal will hang. + + By default, fbguard will use its own + default location to store the file that holds the process id of the + running Firebird engine. You may tell it to use a specific pidfile, if + you wish, by specifying the -pidfile option. + The default is + /var/run/firebird/default.pid. + + + In Firebird 2.50 and 2.5.1, on the OpenSuse platform, the + default pidfile is named /var/run/firebird/.pid + because of a bug in the /etc/init.d/firebird + script where the variable INSTANCE is not + defined. It should be defined with a value of default. + +
+ +
+ Starting Up. + + When the Firebird engine is started at system boot or by the + /etc/init.d/firebird script, it runs under the + watchful eyes of the guardian process. The guardian will restart the + engine any time it determines that the engine has crashed and in doing + so, will hopefully reduce the downtime that the users may suffer as a + result of a crashed engine. It is possible, however, to force the + engine to be started up and the guardian will allow it to stay down if + it detects a crash. + + As mentioned above, regardless of the user you are logged in as + when you execute the fbguard command, the + engine always runs as the root user. + + Regardless of the start mode chosen, the + -signore option can be used to indicate that + startup errors are to be ignored, and + fbguard is to continue to attempt to + startup the engine. Startup errors include problems such as port 3050 + already being used, etc. Normally, on a startup error + fbguard will make no further attempt to + start the engine. + +
+ Start And Stay Running. + + At system boot time, the engine is started in the mode that + allows the guardian to restart it in the event of a crash. To + perform this task manually using fbguard + you would carry out the following process: + + tux> fguard -forever -daemon + + + The command defaults to -forever if + nothing is specified. + + tux> fguard -daemon + +
+ +
+ Start And Stop Running. + + Under normal circumstances you would wish for the database + engine to remain running as long as possible. At other times, + however, you may wish for any crashes to be investigated prior to + restarting the engine. This is possible using + fbguard as the following shows: + + tux> fguard -onetime -daemon + +
+
+ +
+ Shutting Down. + + There is no fbguard command line + option that shuts down the running Firebird engine. To do so requires + that you kill the running process as root. + + tux> ps -ef| grep -i fire[b]ird +root 11556 11555 0 12:18 ? 00:00:00 /opt/firebird/bin/fbserver + +tux> kill 11556 + +tux> ps -ef| grep -i fire[b]ird +## No output shown ## + + + + The fbserver process is always + listed as running from /opt/firebird as per the output from + the various grep commands above. The + fbguard process, on the other hand, + doesn't show the full path unless it was started using the full + path, as follows: + + tux> cd /opt/firebird/bin +tux> ./fbguard -forever -daemon + +tux> ps -ef | grep -i fire[b]ird +root 11794 11793 0 12:32 ? 00:00:00 /opt/firebird/bin/fbserver + +tux> ps -ef|grep -i fb[g]uard +root 11793 1 0 12:32 ? 00:00:00 ./fbguard -forever -daemon + +tux> kill 11794 + +tux> /opt/firebird/bin/fbguard -forever -daemon + +tux> ps -ef | grep -i fire[b]ird +root 11838 1 0 12:34 ? 00:00:00 /opt/firebird/bin/fbguard -forever -daemon +root 11839 11838 0 12:34 ? 00:00:00 /opt/firebird/bin/fbserver + + +
+
+
+
Windows Systems. @@ -655,6 +866,15 @@ Firebird Server - DefaultInstance IS installed. fbmgr application as it uses the instsvc command instead. +
+ Fbmgr is Deprecated at Firebird 2.5 + + The biggest drawback to the fbmgr + utility is the fact that it is deprecated from Firebird 2.5 onwards and + will be removed altogether from Firebird 3.0. You are advised to use + fbguard instead. +
+
The Help Command. @@ -885,6 +1105,23 @@ can not attach to server Spelling corrections. + + + 1.6 + + 13 October 20011 + + ND + + + Updated to mention that fbmgr is + deprecated from Firebird 2.5 onwards, and removed altogether from + Firebird 3.0. + + Added a chapter on using + fbguard. + + diff --git a/src/docs/firebirddocs/fbutil_gbak.xml b/src/docs/firebirddocs/fbutil_gbak.xml index c1aab138..1ae3cf05 100644 --- a/src/docs/firebirddocs/fbutil_gbak.xml +++ b/src/docs/firebirddocs/fbutil_gbak.xml @@ -1,8 +1,6 @@ - +
Firebird Backup & Restore Utility @@ -1617,7 +1615,7 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log userlevel="">http://firebird.cvs.sourceforge.net/viewvc/firebird/ manual/src/docs/firebirddocs/fbutil_gbak.xml?view=log - + 1.0 @@ -1722,7 +1720,7 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log Lots of spelling mistakes corrected. - + diff --git a/src/docs/firebirddocs/fbutil_gfix.xml b/src/docs/firebirddocs/fbutil_gfix.xml index b7f66603..a7f411fd 100644 --- a/src/docs/firebirddocs/fbutil_gfix.xml +++ b/src/docs/firebirddocs/fbutil_gfix.xml @@ -1,8 +1,6 @@ - +
Firebird Database Housekeeping Utility diff --git a/src/docs/firebirddocs/fbutil_gsec.xml b/src/docs/firebirddocs/fbutil_gsec.xml index cd715250..2366c042 100644 --- a/src/docs/firebirddocs/fbutil_gsec.xml +++ b/src/docs/firebirddocs/fbutil_gsec.xml @@ -1,8 +1,6 @@ - +
Firebird Password File Utility diff --git a/src/docs/firebirddocs/fbutil_gsplit.xml b/src/docs/firebirddocs/fbutil_gsplit.xml index 105cc2a2..898e50b3 100644 --- a/src/docs/firebirddocs/fbutil_gsplit.xml +++ b/src/docs/firebirddocs/fbutil_gsplit.xml @@ -1,8 +1,6 @@ - +
Firebird Backup File Splitting Filter diff --git a/src/docs/firebirddocs/fbutil_gstat.xml b/src/docs/firebirddocs/fbutil_gstat.xml index c47de419..e911f324 100644 --- a/src/docs/firebirddocs/fbutil_gstat.xml +++ b/src/docs/firebirddocs/fbutil_gstat.xml @@ -1,8 +1,6 @@ - +
Firebird Database Statistics Reporting Tool diff --git a/src/docs/firebirddocs/fbutil_isql.xml b/src/docs/firebirddocs/fbutil_isql.xml index 5f678175..32f185cb 100644 --- a/src/docs/firebirddocs/fbutil_isql.xml +++ b/src/docs/firebirddocs/fbutil_isql.xml @@ -1,8 +1,6 @@ - +
Isql - Firebird Interactive SQL Utility @@ -714,6 +712,9 @@ CON> SET TRANSACTION WAIT SNAPSHOT NO AUTO UNDONE LOCK TIMEOUT 10; + When you request help in isql for the + set command, set transaction is not shown. +
@@ -721,25 +722,25 @@ CON> A batch of DDL or DML statements in a text file is known as a script. Scripts can be used to create and alter database objects. These are referred to as - data definition files or DDL scripts. Scipts that manipulate data by inserting, + Data Definition Language (DDL) scripts. Scipts that manipulate data by inserting, updating or performing data conversions, are called DML scripts, because they use - commands described in the Data Manipulation Language(DML). + commands described in the Data Manipulation Language (DML). One of the most important tasks handled by isql is to process scripts. It can handle both DDL and DML Scripts, but they should be included in separate scripts to avoid data integrity problems. This script processing feature of isql allows the linking of one - script to another using the isql INPUT - <filespec>. Scripts statements are executed in order. The default setting in - isql for the AUTODDL is set to ON. You may use the SET - AUTODDL command to control where or when statements will be committed. + script to another using the isql INPUT + <filespec>. Scripts statements are executed in order. The default setting in + isql for the AUTODDL is set to ON. You may use the SET + AUTODDL command to control where or when statements will be committed. - The isql utility processes scripts in two ways: +
diff --git a/src/docs/firebirddocs/fbutil_scripts.xml b/src/docs/firebirddocs/fbutil_scripts.xml index 441f97cc..e052c295 100644 --- a/src/docs/firebirddocs/fbutil_scripts.xml +++ b/src/docs/firebirddocs/fbutil_scripts.xml @@ -1,8 +1,6 @@ - +
Firebird Shell Scripts diff --git a/src/docs/firebirddocs/firebirdinternals.xml b/src/docs/firebirddocs/firebirdinternals.xml index 254aa6e9..3d4083ca 100644 --- a/src/docs/firebirddocs/firebirdinternals.xml +++ b/src/docs/firebirddocs/firebirdinternals.xml @@ -1,8 +1,6 @@ - +"../../../tools/docbook-dtd/docbookx.dtd">
Firebird Internals From 30d067134b88d4cb11cdb2f4c55f6cb114b91ff3 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Thu, 13 Oct 2011 14:09:57 +0000 Subject: [PATCH 10/33] Reserve more Java memory for build process. --- src/build/build.bat | 2 +- src/build/build.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/build/build.bat b/src/build/build.bat index 6d92ee83..009c7169 100755 --- a/src/build/build.bat +++ b/src/build/build.bat @@ -14,7 +14,7 @@ goto exit set cp=..\..\lib\ant-launcher.jar set class=org.apache.tools.ant.launch.Launcher -"%JAVA_HOME%\bin\java.exe" -showversion -Xmx100000000 -classpath %cp% -Dant.home=..\.. %class% %1 %2 %3 %4 %5 %6 %7 %8 %9 +"%JAVA_HOME%\bin\java.exe" -showversion -Xmx300000000 -classpath %cp% -Dant.home=..\.. %class% %1 %2 %3 %4 %5 %6 %7 %8 %9 :exit diff --git a/src/build/build.sh b/src/build/build.sh index 09de5663..e701274b 100755 --- a/src/build/build.sh +++ b/src/build/build.sh @@ -11,4 +11,4 @@ fi cp=../../lib/ant-launcher.jar class=org.apache.tools.ant.launch.Launcher -"$JAVA_HOME/bin/java" -showversion -Xmx100000000 -classpath $cp -Dant.home=../.. $class $* +"$JAVA_HOME/bin/java" -showversion -Xmx300000000 -classpath $cp -Dant.home=../.. $class $* From 863559744c8443d633453a827eb1fc182a2847ac Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Sat, 15 Oct 2011 22:54:59 +0000 Subject: [PATCH 11/33] Never used. --- src/docs/firebirddocs/firebirdintro.xml | 24 ------------------------ 1 file changed, 24 deletions(-) delete mode 100644 src/docs/firebirddocs/firebirdintro.xml diff --git a/src/docs/firebirddocs/firebirdintro.xml b/src/docs/firebirddocs/firebirdintro.xml deleted file mode 100644 index bb40ca52..00000000 --- a/src/docs/firebirddocs/firebirdintro.xml +++ /dev/null @@ -1,24 +0,0 @@ - - - - - Firebird - your favorite database - Author: - - David - Jencks - - davidjencks@earthlink.net - -
- Introduction -
- Introduction to Firebird - Our first manual section is on migrating from MS SQL Server to Firebird. We invite you to contribute documentation on your area of expertise. -
-
- About Firebird - Firebird is a relational database product with a history stretching back to the mid 1980s, when Jim Starkey, then working for DEC, realized that transaction isolation could be provided without locking by storing multiple record versions within the database. After several changes in ownership, the source code to what was by then known as InterBase was released in open source by Inprise/Borland in July 2000. The Firebird project has formed to continue open development of this database. -
-
- \ No newline at end of file From 9d482fbade2e798d89fefbc3f92b4f9048036d7d Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Fri, 11 Jan 2013 16:27:45 +0000 Subject: [PATCH 12/33] Gbak updated with details of stdin and stdout file names. Added examples of usage of these parameters to the recipies section. --- src/docs/firebirddocs/fbutil_gbak.xml | 339 ++++++++++++++++++++------ 1 file changed, 259 insertions(+), 80 deletions(-) diff --git a/src/docs/firebirddocs/fbutil_gbak.xml b/src/docs/firebirddocs/fbutil_gbak.xml index 1ae3cf05..e82d9d0c 100644 --- a/src/docs/firebirddocs/fbutil_gbak.xml +++ b/src/docs/firebirddocs/fbutil_gbak.xml @@ -15,7 +15,7 @@ Dunbar - 11 October 2011 - Document version 1.6 + 11 January 2013 - Document version 1.7
@@ -378,6 +378,16 @@ gbak:general options are: line. + + You may, if you wish, send the output to standard output rather + than a backup file. In this case, you must specify stdout as the dump + file name. This is not really of much use, unless you wish to pipe the + dump through a tool to modify it in some way. You can pipe the output + directly to a gbak restore operation to + clone a database without needing an intermediate dump file. An example + is given later in this manual. + + When carrying out a backup of a database, the following switches, in addition to the common ones above, will be of use: @@ -542,6 +552,16 @@ gbak:general options are: is specified as the second file name on the command line.. + + You may, if you wish, read the dump data directly from standard + input rather than a backup file. In this case, you must specify stdin + as the dump file name. You could pipe a + gbak dump operation directly to a + gbak restore operation to clone a database + without needing an intermediate dump file. An example is given later + in this manual. + + When carrying out a restore or replacement of a database, the following switches, in addition to the common ones above, will be of use: @@ -926,7 +946,7 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test object, such as CHECK constraints) is stored in a blob, as is the "compiled" BLR code. When you restore a database, the BLR is not recreated: the same BLR is used until next time you recreate or alter - the object. + the object. Historically, the engine did not do the right thing regarding the transliteration of strings embedded in the source and the BLR. In @@ -939,7 +959,7 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test these system table records. This very old bug affects user blobs, too, if they have been stored using character set NONE and the client is configured to read a specified character set to which the stored data - could not be transliterated. + could not be transliterated. In v.2.1 there were scripts in ../misc that you could run to repair the @@ -947,7 +967,7 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test errors in blobs in your user data. The repair switches were added to the gbak restore code in v.2.5 to do the same corrections to meta data and data, respectively, during the - process of restoring a database for upgrade. + process of restoring a database for upgrade.
@@ -1286,6 +1306,44 @@ tuxrep> gstat -h employee|grep -i attributes
+
+ Create a Database Clone Without a Dump File. + + You may use gbak to create a clone of a + database, on the same server, without needing to create a potentially + large dump file. To do this, you pipe the output of a + gbak backup directly to the input of a + gbak restore, as follows. + + tux> # Clone a test database to the same server, without requiring a dump file. +tux> gbak -backup emptest stdout | gbak -replace stdin emptest_2 + + + You will notice that the output file name for the backup is + stdout and the input file name for the restore is + stdin. This ability to pipe standard output of + one process to the standard input of another, is how you can avoid + creating an intermediate dump file. The commands above assume that there + are suitable alias names set up for both emptest and emptest_2. If not, + you will need to supply the full path to the two databases rather than + the alias. + + The -replace option on the restore process + will overwrite the database name specified - as an alias or as a full + path - if it exists and will create it anew if it doesn't. You may also + use the -recreate overwrite option as an + alternative. Both have the same result. + + If you don't want to overwrite any existing databases, use + -create which will only create a database if it + doesn't already exist, and will exit with an error if it does. In POSIX + compatible systems, the error code in $? is 1 in this + case. + + Further examples of backing up and restoring remote databases over + ssh, using the stdin and stdout file names, can be seen below. +
+
Backup & Restore With & Without Shadow Files. @@ -1357,7 +1415,7 @@ SQL> quit; Firebird's gbak utility can make backups of a remote database. To do this, you need to connect to the - service manager running on the database, this is normally called + service manager running on the remote server, this is normally called service_mgr. The following example shows the Firebird employee database on server tuxrep being backed up from the server @@ -1428,6 +1486,106 @@ tux> gbak -replace -service tux:service_mgr /backups/remote_backup.fbk employ
+
+ Remote Backups and Restores Using SSH + + As shown above, you can use the special file names stdin and + stdout to backup and restore a database to a separate database on the + same server. However, you can also use the same tools, over an SSH + connection to a remote server, and pass the backup of one database + directly to a restoration of a separate one. + + The first example copies a local database to a remote server where + Firebird is running and the firebird user has its environment set up so + that the gbak tool is on $PATH by default, on login. + + + In each of the following examples, the -user + sysdba and -password whatever + parameters on the command lines have been replaced by {...}. When + executing these commands, any remote gbak + commands will require to have them specified unless the firebird user + on the remote database(s) has ISC_USER and + ISC_PASSWORD defined in the + .profile or .bashrc (or + equivalent) login files. However, that is a + seriously bad idea and incredibly + insecure. + + + tux> # Clone a test database to a different server, without requiring a dump file. +tux> gbak -backup employee stdout | \ +ssh firebird@tuxrep "gbak {...} -replace stdin emptest" + + + When the above is executed, you will be prompted for a password + for the remote firebird user on server tuxrep, assuming that you don't + have a proper SSH key-pair already set up and active. The command will + replace the local database according to the alias name emptest but you + can, if required, supply full path names for the databases. The + following shows an example of the above being executed. + + tux> # Clone a test database to a different server, without requiring a dump file. +tux> gbak -backup employee stdout | \ +ssh firebird@tuxrep "gbak {...} -replace stdin emptest" + +firebird@tuxrep's password: + + + As you can see, there's not much in the way of output, but you can + connect remotely and check: + + tux> isql {...} tuxrep:emptest + +Database: tuxrep:emptest + +SQL> show database; + +Database: tuxrep:emptest + Owner: SYSDBA +PAGE_SIZE 4096 +... + + + The next example, shows a remote database being backed up to a + local one, in a similar manner. + + tux> ssh firebird@tuxrep "gbak -backup {...} emptest stdout" | \ +gbak -create stdin data/tuxrep_emptest.fdb + +firebird@tuxrep's password: + +tux> ls data + +employee.fdb tuxrep_emptest.fdb + + + You can see that a new tuxrep_emptest.fdb + database has been created. Does it work? Checking with + isql shows that it does. + + tux> isql data/tuxrep_emptest.fdb + +Database: data/tuxrep_emptest.fdb + +SQL> quit; + + + The final example shows how to backup a remote database on one + server, to a remote database on another. + + tux> ssh firebird@tuxrep "gbak -backup {...} emptest stdout" | \ +ssh firebird@tuxqa "gbak -create {...} stdin data/tuxrep_empqa.fdb" + +firebird@tuxrep's password: +firebird@tuxqa's password + +tux> ssh firebird@tuxqa "ls data" + +employee.fdb tuxrep_empqa.fdb + +
+
Using External Tools @@ -1615,112 +1773,133 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log userlevel="">http://firebird.cvs.sourceforge.net/viewvc/firebird/ manual/src/docs/firebirddocs/fbutil_gbak.xml?view=log - - - 1.0 + + + 1.0 + + 10 October 2009 + + ND + + + Created as a chapter in the Command Line Utilities + manual. + + + + + 1.1 + + 20 October 2009 - 10 October 2009 + ND - ND + + More minor updates and converted to a stand alone + manual. + + - - Created as a chapter in the Command Line Utilities - manual. - - + + 1.2 - - 1.1 + 24 November 2009 - 20 October 2009 + ND - ND + + Corrected the section on -y + Suppress_output plus corrected the formatting of + various screen dumps. They had been reformatted as text at some + point. + + - - More minor updates and converted to a stand alone - manual. - - + + 1.3 - - 1.2 + 24 June 2010 - 24 November 2009 + ND - ND + + Added a bit more details to the + -o[ne_at_a_time] restore option to explain + transactions. + + - - Corrected the section on -y - Suppress_output plus corrected the formatting of various - screen dumps. They had been reformatted as text at some - point. - - + + 1.4 - - 1.3 + 09 August 2010 - 24 June 2010 + ND - ND + + Noted that gbak defaults to + running a backup or recover according to the first file name + parameter supplied. - - Added a bit more details to the - -o[ne_at_a_time] restore option to explain - transactions. - - + A few minor formatting errors, URLs and some examples were + corrected. - - 1.4 + Also added an example of a meta data only backup and + restore. + + - 09 August 2010 + + 1.5 - ND + 31 March 2011 - - Noted that gbak defaults to running - a backup or recover according to the first file name parameter - supplied. + ND - A few minor formatting errors, URLs and some examples were - corrected. + + Updated the -z option to indicate + that it does carry out a backup. + + - Also added an example of a meta data only backup and - restore. - - + + 1.6 - - 1.5 + 11 October 2011 - 31 March 2011 + ND - ND + + Updated to cover Firebird 2.5 changes. - - Updated the -z option to indicate that - it does carry out a backup. - - + Corrected description of + -g[arbage_collect] switch. - - 1.6 + Lots of spelling mistakes corrected. + + - 11 October 2011 + + 1.7 - ND + 11 January 2013 - - Updated to cover Firebird 2.5 changes. + ND - Corrected description of - -g[arbage_collect] switch. + + Updated to document the use of the stdin and stdout file + names in backups and restores, which allow backups to be written + to or read from standard input and standard output. - Lots of spelling mistakes corrected. - - - + A section was added on the use of the above to clone + databases without requiring an intermediate dump file. An + additional section was also added to show how, using the above in + conjunction with SSH, backup and/or restore operations could be + carried out on databases where one or both of the databases in + question, are remote. + + + From dcddd4d1233751207a9b885132ba0e5ff5fc08cf Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Mon, 14 Jan 2013 11:32:47 +0000 Subject: [PATCH 13/33] Added a section to the Caveats for gbak giving better detail of the stdin and stdout file names and their use. --- src/docs/firebirddocs/fbutil_gbak.xml | 47 ++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/src/docs/firebirddocs/fbutil_gbak.xml b/src/docs/firebirddocs/fbutil_gbak.xml index e82d9d0c..05f271e6 100644 --- a/src/docs/firebirddocs/fbutil_gbak.xml +++ b/src/docs/firebirddocs/fbutil_gbak.xml @@ -15,7 +15,7 @@ Dunbar - 11 January 2013 - Document version 1.7 + 14 January 2013 - Document version 1.8
@@ -1760,6 +1760,36 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log you now need to introduce a housekeeping system to tidy away old, unwanted backups to prevent your backup area filling up.
+ +
+ Use of 'stdin' or 'stdout' File Names + + Gbak recognizes the literal strings + 'stdin' and 'stdout' as source or destination filenames. In POSIX + systems, when the standard input and/or standard output channels are + used, it is not permitted to execute seek operations on these channels. + Using 'stdin' or 'stdout' as file names with + gbak will force + gbak to use processing that will not seek on + the input or output channels, making them suitable for use in pipes - as + per the examples in the recipes section above. + + These file names, while they appear to be POSIX names, are + definitely not synonyms for /dev/stdin or + /dev/stdout, they are simply literals that + gbak checks for while processing its + parameters. Do not attempt to use names /dev/stdin + or /dev/stdout in a piped process as it will most + likely fail. + + If you wish to create a dump file actually named either stdin or + stdout, then you should specify the filename as a full, or relative, + path name such as ./stdin or + ./stdout, which causes + gbak to treat them as a literal file name + rather than a special file name that causes different to normal + processing.during the dump or restore process. +
@@ -1899,6 +1929,21 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log question, are remote. + + + 1.8 + + 14 January 2013 + + ND + + + Further updates to document the use of the stdin and stdout + file names in backups and restores. A section has been added to + Gbak Caveats giving more in depth detail about these two special + file names. + + From c18327dbe37173514229925395b6204fa5fa50d8 Mon Sep 17 00:00:00 2001 From: Popa Adrian Marius Date: Mon, 11 Feb 2013 16:39:14 +0000 Subject: [PATCH 14/33] Merge updated papers and docs : docbuilding, migration from mssql , ubuntu setup with with firebird 2.5.x , firebird enterprise and last quick compile setup for php on linux --- src/docs/firebirddocs/docbuilding-howto.xml | 63 +++--- src/docs/firebirddocs/migrationmssql.xml | 121 ++--------- src/docs/firebirddocs/ubuntu-setup.xml | 221 ++++++++++---------- src/docs/papers/firebird_enterprise.xml | 30 +-- src/docs/papers/firebird_php_linux.xml | 38 ++-- 5 files changed, 221 insertions(+), 252 deletions(-) diff --git a/src/docs/firebirddocs/docbuilding-howto.xml b/src/docs/firebirddocs/docbuilding-howto.xml index d2444b64..a9d08a3e 100644 --- a/src/docs/firebirddocs/docbuilding-howto.xml +++ b/src/docs/firebirddocs/docbuilding-howto.xml @@ -1,4 +1,6 @@ +
Getting and building the Firebird manual module @@ -11,7 +13,7 @@ Vinkenoog - 26 Oct 2009 – Document version 1.6.1 + 10 February 2013 – Document version 1.6.2
@@ -47,13 +49,13 @@ http://www.firebirdsql.org/index.php?op=doc – the + url="http://www.firebirdsql.org/en/documentation/">http://www.firebirdsql.org/en/documentation/ – the Firebird Documentation Index. http://www.firebirdsql.org/index.php?op=doc&id=othersites + url="http://www.firebirdsql.org/en/external-documentation/">http://www.firebirdsql.org/en/external-documentation/ – a listing of other sites with valuable Firebird documentation. @@ -124,8 +126,9 @@ Command-line CVS is often pre-installed. If it isn't, use the admin tools of your distribution to install it – you'll typically find it in the development - category. If that doesn't work for you, get it at http://www.cvshome.org + category (in ubuntu/debian you can install it from terminal with apt-get install cvs). + If that doesn't work for you, get it at http://www.nongnu.org/cvs @@ -141,7 +144,7 @@ Command-line CVS at http://www.cvshome.org + url="http://www.nongnu.org/cvs/">http://www.nongnu.org/cvs @@ -208,7 +211,7 @@ Try your luck at http://www.cvshome.org, http://www.nongnu.org/cvs, google for it, or ask in the gnu.cvs.help newsgroup or on the firebird-docs mailing list. @@ -550,13 +553,13 @@ Building the Firebird docs Several Java tools are used to produce the HTML and PDF docs from the DocBook XML source. - Therefore, you need a recent version of Java 2 installed on your system. + Therefore, you need a recent version of Java installed on your system. In the next subsections we will show you: - Where to get Java 2 + Where to get Java @@ -572,17 +575,17 @@ - If you already have a recent version of Java 2 installed, you may If you already have a recent version of Java installed, you may skip the first step. -
- Where to get Java 2 +
+ Where to get Java Download and install only one of the following: - Java 2 Runtime Environment, Standard Edition – often abbreviated as J2RE SE. + Java Runtime Environment, Standard Edition – often abbreviated as JRE SE. Go to http://www.java.com/ and follow the links to the download pages. Get the version for your own OS. Clicking on a "Download" or @@ -593,18 +596,18 @@ - Java 2 Software Development Kit, Standard Edition – or J2SDK SE. + Java Software Development Kit, Standard Edition – or JSDK SE. - This is a much larger package, and it also contains the J2RE SE. If you want the - SDK, go to http://java.sun.com/j2se/ and + This is a much larger package, and it also contains the JRE SE. If you want the + SDK, go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and get the latest stable version. When you have to choose between JRE and SDK, take the SDK. - (Yes, you can also get the J2RE from here, but you can get it easier and quicker from the + (Yes, you can also get the JRE from here, but you can get it easier and quicker from the link in the first option.) Download the installation program and run it. If you don't understand the difference between the two, go for the first option: the - Java 2 Runtime Environment. You don't need the SDK to build the Firebird docs. + Java Runtime Environment. You don't need the SDK to build the Firebird docs.
@@ -630,19 +633,19 @@ How to set up the environment for the build The build scripts need an environment variable JAVA_HOME pointing to the - Java 2 install directory. + Java install directory. On Windows, this is typically something of the form C:\Program - Files\Java\j2re1.4.2_01. To be sure, check if there's a directory called + Files\Java\jre1.6.0_39. To be sure, check if there's a directory called bin underneath it, and if this bin subdir contains the file java.exe On Linux, it may be /usr/lib/java/jre or - /usr/java/j2sdk, or... well, it can be a lot of things. The same + /usr/java/jsdk, or... well, it can be a lot of things. The same check applies: it should have a subdir bin containing an executable file java (without the .exe extension here). @@ -651,7 +654,7 @@ If you're lucky, the JAVA_HOME envar is already present and correct. If not, you have to set it yourself, e.g. under Windows with set JAVA_HOME=C:\Program - Files\Java\j2re1.4.2_01 or under Linux/bash with export + Files\Java\jre1.6.0_39 or under Linux/bash with export JAVA_HOME=/usr/lib/java/jre. (Note: these paths are just examples; they may or may not be the same as yours.) @@ -897,7 +900,7 @@
If things go wrong - If the build process fails, this may be due to a too old Java 2 version. See + If the build process fails, this may be due to a too old Java version. See for more info on getting the latest version. @@ -1788,6 +1791,18 @@ therefore illegal. + + 1.6.2 + + 10 Feb 2013 + + PMA + + + Fixed some old links for Java JRE, replaced Java 2 reference with just Java, cvs home page is now fixed + + + @@ -1816,4 +1831,4 @@ Portions created by Norman Dunbar are Copyright (C) 2006. All Rights Reserved. Contributor contact: normandunbar at users dot sourceforge dot net. -
\ No newline at end of file +
diff --git a/src/docs/firebirddocs/migrationmssql.xml b/src/docs/firebirddocs/migrationmssql.xml index e446315a..12068d96 100644 --- a/src/docs/firebirddocs/migrationmssql.xml +++ b/src/docs/firebirddocs/migrationmssql.xml @@ -1,9 +1,6 @@ - - +
Migration from MS-SQL to Firebird @@ -11,7 +8,7 @@ Marcelo Lopez Ruiz - 24 July 2011 - Document version 1.3 + 21 January 2013 - Document version 1.4 Introduction @@ -45,10 +42,6 @@ Why migrate to <application>Firebird</application> This depends mostly on what version you are currently using and what you are using MS SQL for. - For example, if using MS SQL 6.5, it is a simple matter of considering the features and - ease of use. MS SQL 6.5 will work with fixed devices rather than dynamically expanding files, - which makes it very difficult to balance ease of administration vrs. available space. There - are numerous bugs and annoying behaviours which If you are using MS SQL 7, you know a lot of the little quirks have been removed, but you are still missing some great features, such as updateable views, greater control over identity fields, user-defined functions, and selectable stored procedures. You also don't get @@ -64,16 +57,18 @@ reports. One can only wonder about the need for a data warehouse in an integrated environment with cross-database query capabilities. Another reason to migrate is to avoid vendor lock-in. MS SQL will only run on Windows - NT/2000 (there are so-called personal editions, but these are limited in available connections + Only (there are so-called personal editions, but these are limited in available connections and features). This means you are tied to Microsoft for your operating system and your database server. Firebird will run on many platforms, including - Microsoft Windows, Linux, Solaris, MacOS X, and others. - Yet another reason to consider is price. Firebird is free; MS SQL will require a - considerable amount of money on a per-processor basis. For example, a database accessed - through the Internet on a dual cpu - Intel Xeon/Opteron machine will cost $54,990 (prices - obtained from - Microsoft's site on 14 Sep 2010). - Last, but certainly not least, is the fact that Firebird is open source. This not only + Microsoft Windows, Linux, Solaris, MacOS X, Android and others.(From Mainframes to Phones and Embedded devices) + Yet another reason to consider is price. Firebird is forever free; MS SQL will require a + considerable amount of money on a per-processor basis. For example, MS Datacenter License Price + Per Processor on a multi cpu host Intel Xeon/Opteron machine will cost $54,990.00 (prices + obtained from + Microsoft's site on 16 Nov 2011).(And that didn't included the host OS licenses/Virtualizations + costs compared to a Linux host using an open source virtualization solution : KVM-Linux/LXC) + In 2012 Microsoft hiked prices for SQL server going from counting processors to counting cores + Last, but certainly not least, is the fact that Firebird is open source and libre. This not only means that there are hundreds of developers willing to help you use it, improve on it, find bugs, etc., but that you can even modify it and rebuild it yourself to "scratch your itches". Adding features such as an integrated e-mail system or logging is a matter of understanding @@ -82,23 +77,15 @@ Why not migrate to Firebird - The first, overriding reason should be because your system is working fine as it is. If - this is the case, consider Firebird for future projects, but do not break what is currently - working. - There are a number of features MS SQL 7 has that you will not find in + There are a number of features MS SQL has that you will not find in Firebird, such as integrated replication support (this is available - as an add-on to Firebird), temporary tables, and integration with + as an add-on to Firebird), and integration with other database systems through OLE DB. It also has an OLAP Analysis services built into it, and native full-text search (this is available as an add-on to Firebird). - On Microsoft environments, MS SQL 7 and above can have its security integrated with the - operating system's. However, this should be discouraged for portability and performance - issues. - MS SQL 2000 also has the ability to work with XML directly, and supports partitioned + MS SQL also has the ability to work with XML directly, and supports partitioned views for better performance on tables which span several servers. - In general, it would seem that MS SQL has better performance on Windows than - Firebird on Windows does. It also has better integration with - Microsoft Visual Studio. + It also has better integration with Microsoft Visual Studio. @@ -131,8 +118,7 @@ Firebird and MS SQL. Database Files Administration - MS SQL 6.5 uses devices, which can be files or raw partitions, to manage data. This - resulted in a hard-to-maintain system. MS SQL 7 and MS SQL 2000 corrected this by using normal + MS SQL uses devices, which can be files or raw partitions, to manage data. Usually you are using normal files in place of devices. For each database, you will have at least two files: one with the database information itself, and one with a log of transactions performed. Firebird does not rely on a log to keep track of transactions, and therefore uses a @@ -488,10 +474,6 @@ END MS SQL has more environment variables than Firebird does, but the most common ones (identity retrieval and user name retrieval) can be found. The only important variable missing is the row count of the latest operation. - An important difference is that Firebird 1.0 does not support - the MS SQL CASE statement. You can sometimes use a stored procedure in its - stead, which promotes reusability and eases maintenance. Starting at 1.5, Firebird fully - supports CASE. A minor difference is that MS SQL does not use a delimiter between statement. This can be the source of some tricky bugs, specially when using many parenthesis. Firebird requires that every statement end in a semicolon ; so errors @@ -567,63 +549,6 @@ END THEN something = 'uuhhh.....'; ELSE something = 'I know! I know!'; - - <database>CASE</database> - Firebird 1.0 doesn't have a CASE statement, so you'll need to do - some manual conversion work if it is used in your MS-SQL database. - You can skip this section if - you're using Firebird 1.5 or up, since these versions fully support the - CASE syntax. - The CASE statement can be used as a switch statement - in C or a case statement in Pascal to change one value for another. This can - usually be translated to Firebird 1.0 as a stored procedure - returning some value. - /* This is the original MS SQL - statement, using the * traditional pubs database. */ -CREATE PROCEDURE list_states -AS -SELECT - CASE state - WHEN 'CA' THEN 'California' - WHEN 'UT' THEN 'Utah' - ELSE 'unknown' - END -FROM authors - /* This is how it can be converted to Firebird. */ -/* Isolate the CASE statement. */ -CREATE PROCEDURE get_state_name ( state_code char(2) ) -RETURNS ( state_name varchar(64) ) -AS -BEGIN - IF (state_code = 'CA') THEN state_name = 'California'; - ELSE IF (state_code = 'UT') THEN state_name = 'Utah'; - ELSE state_name = 'unknown'; -END - -/* This is the selectable stored procedure. */ -CREATE PROCEDURE list_states -RETURNS (state varchar(64)) -AS -DECLARE VARIABLE short_state CHAR(2); -BEGIN - FOR SELECT state FROM authors INTO :short_state DO - BEGIN - EXECUTE PROCEDURE get_state_name :short_state - RETURNING_VALUES :state; - SUSPEND; - END -END - - Three things should be noted from the example above. First, the conversion is trivial. - Second, it is however quite verbose. Third, using a stored procedure allows for greater - flexibility, and makes maintenance easier. Suppose the CASE statement - for the state occurs in twelve different procedures, and a new state was added; or that you - misspelled a state name; or any other change. It is clearly beneficial to abstract this - conversion, trivial as it may seem, into its own stored procedure. - Again: as from version 1.5, Firebird fully supports the CASE - statement, so no conversion is needed there. - <database>WHILE</database> WHILE exists in Firebird as it does in @@ -795,7 +720,7 @@ DECLARE VARIABLE au_lname VARCHAR(40); The standard command-line utility is isql. This is used usually when executing large scripts, or when writing batch files. When a graphical user interface (GUI) is available, the administration tool will most - probably be IBConsole. This tool is similar to MS SQL's + probably be Flamerobin. This tool is similar to MS SQL's Enterprise Manager. @@ -875,11 +800,11 @@ DECLARE VARIABLE au_lname VARCHAR(40); Client Network Utility No need to; connection strings are fully self-described. Test with - IBConsole. + Flamerobin. Enterprise Manager - IBConsole + Flamerobin Enterprise Manager @@ -907,11 +832,11 @@ DECLARE VARIABLE au_lname VARCHAR(40); Query Analyzer - IBConsole + Flamerobin Server Network Utility - IBConsole + Flamerobin Service Manager diff --git a/src/docs/firebirddocs/ubuntu-setup.xml b/src/docs/firebirddocs/ubuntu-setup.xml index 75f53d77..a0d68849 100644 --- a/src/docs/firebirddocs/ubuntu-setup.xml +++ b/src/docs/firebirddocs/ubuntu-setup.xml @@ -1,6 +1,6 @@ - +
Setting up Firebird on Ubuntu Linux @@ -12,13 +12,13 @@ - Marius + Adrian Marius Popa - 14 May 2011 – Document version 2.3 + 8 February 2013 – Document version 2.5
@@ -26,14 +26,16 @@ This article describes the process of installing and running Firebird on Ubuntu Linux. It should also work without modification in the Debian GNU/Linux distribution - (stable version named Squeeze and unstable version named Sid). - Ubuntu is based on Debian core packages. Installing software with Ubuntu (or Kubuntu) is very + (testing version named Wheezy and unstable version named Sid). + Ubuntu is based on Debian core packages. Installing software with Ubuntu is very straightforward and Firebird is no exception. This guide is based on - Ubuntu 10.04 LTS Lucid Lynx. + Ubuntu 12.04 LTS The Precise Pangolin but it can be used with a current supported stable release. - The version of Firebird packaged with Ubuntu Lucid Lynx - is 2.1.3 and is included by default and is the latest stable. For other Ubuntu releases there is - a Firebird stable ppa repository from where you can install it. + The version of Firebird packaged with Ubuntu Precise Pangolin + is 2.5.1 and is included by default . For stable Ubuntu releases there is + a Firebird stable ppa repository + from where you can install the stable versions latest LTS and current stable + . With administrator privileges on the target machine, issue the @@ -42,7 +44,7 @@
$ sudo su - # apt-get install firebird2.1-super + # apt-get install firebird2.5-superclassic
@@ -51,19 +53,20 @@ output:
- - The following extra packages will be installed: - firebird2.1-common firebird2.1-server-common libedit2 - libfbclient2 libicu38 - Suggested packages: - firebird2.1-doc - The following NEW packages will be installed: - firebird2.1-common firebird2.1-server-common firebird2.1-super - libedit2 libfbclient2 libicu38 - 0 upgraded, 6 newly installed, 0 to remove and 1 not upgraded. - Need to get 11.7MB of archives. - After unpacking 28.4MB of additional disk space will be used. - Do you want to continue [Y/n]? y + + Reading package lists... Done + Building dependency tree + Reading state information... Done + The following extra packages will be installed: + firebird2.5-classic-common firebird2.5-common firebird2.5-common-doc firebird2.5-server-common libfbclient2 libfbembed2.5 libib-util + Suggested packages: + firebird2.5-doc + The following NEW packages will be installed: + firebird2.5-classic-common firebird2.5-common firebird2.5-common-doc firebird2.5-server-common firebird2.5-superclassic libfbclient2 libfbembed2.5 libib-util + 0 upgraded, 8 newly installed, 0 to remove and 0 not upgraded. + Need to get 3,370 kB of archives. + After this operation, 14.9 MB of additional disk space will be used. + Do you want to continue [Y/n]? Y
@@ -74,18 +77,35 @@
- Selecting previously deselected package firebird2.1-super. - (Reading database ... 542436 files and directories currently - installed.) - Unpacking firebird2.1-super - (from .../firebird2.1-super_2.1.3.18185-0.ds1-6build1_i386.deb) ... - Processing triggers for ureadahead ... - Setting up firebird2.1-super (2.1.3.18185-0.ds1-6build1) ... - Created default security.fdb - * Firebird 2.1 server manager not running. - * Not starting Firebird 2.1 server manager - * Use `dpkg-reconfigure firebird2.1-super' to enable. - + Selecting previously unselected package firebird2.5-common-doc. + Unpacking firebird2.5-common-doc (from .../firebird2.5-common-doc_2.5.2~svn+54698.ds4-1_all.deb) ... + Selecting previously unselected package firebird2.5-common. + Unpacking firebird2.5-common (from .../firebird2.5-common_2.5.2~svn+54698.ds4-1_all.deb) ... + Selecting previously unselected package libfbclient2:amd64. + Unpacking libfbclient2:amd64 (from .../libfbclient2_2.5.2~svn+54698.ds4-1_amd64.deb) ... + Selecting previously unselected package firebird2.5-server-common. + Unpacking firebird2.5-server-common (from .../firebird2.5-server-common_2.5.2~svn+54698.ds4-1_amd64.deb) ... + Selecting previously unselected package libfbembed2.5. + Unpacking libfbembed2.5 (from .../libfbembed2.5_2.5.2~svn+54698.ds4-1_amd64.deb) ... + Selecting previously unselected package libib-util:amd64. + Unpacking libib-util:amd64 (from .../libib-util_2.5.2~svn+54698.ds4-1_amd64.deb) ... + Selecting previously unselected package firebird2.5-classic-common. + Unpacking firebird2.5-classic-common (from .../firebird2.5-classic-common_2.5.2~svn+54698.ds4-1_amd64.deb) ... + Selecting previously unselected package firebird2.5-superclassic. + Unpacking firebird2.5-superclassic (from .../firebird2.5-superclassic_2.5.2~svn+54698.ds4-1_amd64.deb) ... + Setting up firebird2.5-common-doc (2.5.2~svn+54698.ds4-1) ... + Setting up firebird2.5-common (2.5.2~svn+54698.ds4-1) ... + Setting up libfbclient2:amd64 (2.5.2~svn+54698.ds4-1) ... + Setting up firebird2.5-server-common (2.5.2~svn+54698.ds4-1) ... + Setting up libfbembed2.5 (2.5.2~svn+54698.ds4-1) ... + Setting up libib-util:amd64 (2.5.2~svn+54698.ds4-1) ... + Setting up firebird2.5-classic-common (2.5.2~svn+54698.ds4-1) ... + Setting up firebird2.5-superclassic (2.5.2~svn+54698.ds4-1) ... + Created default security2.fdb + * Firebird 2.5 superclassic server not running + * Not starting Firebird 2.5 superclassic server + * Use `dpkg-reconfigure firebird2.5-superclassic' to enable +
If you want Firebird to start automatically, run dpkg-reconfigure on the package and click the Yes button. @@ -93,7 +113,7 @@
- # dpkg-reconfigure firebird2.1-super + # dpkg-reconfigure firebird2.5-superclassic
@@ -101,9 +121,10 @@
- * Firebird 2.1 server manager not running. - * Starting Firebird 2.1 server manager... [ OK ] - * Firebird 2.1 server manager already running. + * Firebird 2.5 superclassic server not running + * Starting Firebird 2.5 superclassic server... [ OK ] + * Firebird 2.5 superclassic server already running +
@@ -114,80 +135,72 @@
- # dpkg -L firebird2.1-super + # dpkg -L firebird2.5-classic-common /. - /etc - /etc/init.d - /etc/init.d/firebird2.1-super - /etc/default - /etc/default/firebird2.1-super - /usr - /usr/share - /usr/share/doc - /usr/share/lintian - /usr/share/lintian/overrides - /usr/share/lintian/overrides/firebird2.1-super - /usr/bin - /usr/bin/nbackup - /usr/bin/qli - /usr/bin/gbak - /usr/bin/gfix - /usr/bin/gpre - /usr/bin/isql-fb - /usr/bin/gsec - /usr/bin/fbstat - /usr/bin/gdef - /usr/lib - /usr/lib/firebird - /usr/lib/firebird/2.1 - /usr/lib/firebird/2.1/bin - /usr/lib/firebird/2.1/bin/fbmgr - /usr/lib/firebird/2.1/bin/fbmgr.bin - /usr/lib/firebird/2.1/bin/fb_lock_print - /usr/lib/firebird/2.1/bin/fbguard - /usr/lib/firebird/2.1/bin/fbserver - /usr/lib/firebird/2.1/UDF - /usr/lib/firebird/2.1/UDF/fbudf.so - /usr/lib/firebird/2.1/UDF/ib_udf.so - /usr/share/doc/firebird2.1-super +/usr +/usr/share +/usr/share/doc +/usr/share/lintian +/usr/share/lintian/overrides +/usr/share/lintian/overrides/firebird2.5-classic-common +/usr/lib +/usr/lib/firebird +/usr/lib/firebird/2.5 +/usr/lib/firebird/2.5/UDF +/usr/lib/firebird/2.5/UDF/fbudf.so +/usr/lib/firebird/2.5/UDF/ib_udf.so +/usr/sbin +/usr/sbin/fb_lock_print +/usr/bin +/usr/bin/fbsvcmgr +/usr/bin/gsec +/usr/bin/gpre +/usr/bin/gbak +/usr/bin/gdef +/usr/bin/fbstat +/usr/bin/fbtracemgr +/usr/bin/nbackup +/usr/bin/isql-fb +/usr/bin/qli +/usr/bin/gfix +/usr/share/doc/firebird2.5-classic-common + +
As mentioned, a new user firebird is created on the target - machine. With administrator access, set a password for this new - user: + machine. -
+ Now you can switch to the firebird user with the + su command if required. +
- # passwd firebird - Enter new UNIX password: - Retype new UNIX password: + # su firebird
- - Now you can switch to the firebird user with the - su command if required. + Install the examples and dev files:
- # apt-get install firebird2.1-examples firebird2.1-dev + # apt-get install firebird2.5-examples firebird2.5-dev
The example databases will wind up in the directory tree - /usr/share/doc/firebird2.1-examples/examples/. + /usr/share/doc/firebird2.5-examples/examples/empbuild/. Now you can test your Firebird installation by connecting to an example database. Decompress the employee.fdb example database:
- # cd /usr/share/doc/firebird2.1-examples/examples/empbuild/ - gunzip employee.fdb.gz - chown firebird.firebird employee.fdb - mv employee.fdb /var/lib/firebird/2.1/data/ + # cd /usr/share/doc/firebird2.5-examples/examples/empbuild/ + # gunzip employee.fdb.gz + # sudo chown firebird.firebird employee.fdb + # mv employee.fdb /var/lib/firebird/2.5/data/
@@ -197,7 +210,7 @@
isql-fb - SQL> connect "/var/lib/firebird/2.1/data/employee.fdb" user 'SYSDBA' + SQL> connect "localhost:/var/lib/firebird/2.5/data/employee.fdb" user 'SYSDBA' password 'SYSDBApassword';
@@ -210,7 +223,7 @@
- Database: "/var/lib/firebird/2.1/data/employee.fdb", User: SYSDBA + Database: "localhost:/var/lib/firebird/2.5/data/employee.fdb", User: SYSDBA SQL>
@@ -225,15 +238,12 @@ PROJECT PROJ_DEPT_BUDGET SALARY_HISTORY SALES SQL> show version; - ISQL Version: LI-V2.1.3.18185 Firebird 2.1 - Server version: - Firebird/linux Intel (access method), - version "LI-V2.1.3.18185 Firebird 2.1" - Firebird/linux Intel (remote server), - version "LI-V2.1.3.18185 Firebird 2.1/tcp (borkstationx32)/P11" - Firebird/linux Intel (remote interface), - version "LI-V2.1.3.18185 Firebird 2.1/tcp (borkstationx32)/P11" - on disk structure version 11.1 + SQL Version: LI-V2.5.2.26508 Firebird 2.5 +Server version: +Firebird/linux AMD64 (access method), version "LI-V2.5.2.26508 Firebird 2.5" +Firebird/linux AMD64 (remote server), version "LI-V2.5.2.26508 Firebird 2.5/tcp (Lorkstation64)/P12" +Firebird/linux AMD64 (remote interface), version "LI-V2.5.2.26508 Firebird 2.5/tcp (Lorkstation64)/P12" +on disk structure version 11.2 SQL> quit;
@@ -249,13 +259,13 @@ If you get an error message like Statement failed, SQLCODE = -551 no permission for read-write access to database - /var/lib/firebird/2.1/data/employee.fdb, then the + /var/lib/firebird/2.5/data/employee.fdb, then the server process doesn't have read or write access to the database file. Change the ownership of the database to the user firebird with:
- # cd /var/lib/firebird/2.1/data/ + # cd /var/lib/firebird/2.5/data/ # chown firebird:firebird employee.fdb
@@ -293,7 +303,7 @@ - 2.3 + 2.5 14 May 2011 PV @@ -330,7 +340,8 @@ Contributors: Marius Popa, Paul Vinkenoog. - Modifications applied by Contributors are Copyright (C) 2009-2011 by their respective authors. All Rights Reserved. + Modifications applied by Contributors are Copyright (C) 2009-2013 by their respective authors. All Rights Reserved.
+ diff --git a/src/docs/papers/firebird_enterprise.xml b/src/docs/papers/firebird_enterprise.xml index 4848b204..a92b93c0 100644 --- a/src/docs/papers/firebird_enterprise.xml +++ b/src/docs/papers/firebird_enterprise.xml @@ -31,7 +31,7 @@ - 28 November 2006 v.1.2.2 + 8 February 2013 v.1.2.3
@@ -185,7 +185,7 @@ may also want to know whether the DBMS is under active development or is near th development life. We expect regular sub-releases and signs that the next major release is on the way. When we are ready, will it be easy to upgrade? Can our existing databases be migrated painlessly to a new release or will it be a lengthy, do-or-die logistical exercise? - Now in its sixth year, the Firebird Project team continues confidently on its track towards planned + Now in its twelve year, the Firebird Project team continues confidently on its track towards planned releases that will implement architectural enhancements to meet hardware advances and satisfy a demanding community of developers, users and supporters. The openness of the code and the renowned willingness of the community to share what they know ensures a continual supply of @@ -218,10 +218,16 @@ such as availability and interoperability (q.v.). offerings that respond to demand for upscaling capability by adding weight and ever more prolific file-bound mechanisms, Firebird's upscaling is merely a question of adapting the environment. The same engine comfortably handles anything from being embedded in -a stand-alone client application, through to a classical two-tier client/server LAN of around 750 -potential users, to incorporation in a multi-tier solution for thousands of potential clients. Database +a stand-alone client application, through to a classical two-tier client/server LAN of around 1000 +potential users, to incorporation in a multi-tier solution for hundred of thousands of potential clients. Database growth is effectively limited only by the disk storage available and can be split across multiple hard disks. + +Firebird is running in production on large big iron servers: +2TB of ram 100000 concurrent users and runs to power larger systems (for 12 government agencies and 3 banks). +It has approximately 100000 end users multiplexed through 2500 (max) pooled connections on a FusionIO drive (SSD). + + Through smart replication and good connection management in the access layers, the workload of a busy system can be distributed across multiple servers. For example, a well-resourced central @@ -262,9 +268,9 @@ backup, which can be scheduled throughout the day to suit the loads.
Capacity The largest Firebird database we have heard of is about 11 Terabytes and growing. Tables are -limited to about 2,000,000,000 rows and, up to version 1.5.x, a maximum of about 30 Gigabytes per -table. The maximum table byte-size limit disappears in v.2.0, due in mid-2006. -
+not limited to the number of rows but we know is more than 16 billion, the size can be up to a maximum of about 32 TB per +table for Firebird 2.x. Consult Firebird Technical Specifications page for up to date numbers +
Interoperability @@ -310,7 +316,7 @@ a sparsely-configured Linux with fast disk systems for load-balancing and failov application programming interfaces (APIs), one for database-level operations and the other for server-level services such as backup and user authentication. Driver support is available for a large number of programming and standard interface environments, -including Java/JDBC, ODBC, .NET, Delphi, Python, PHP and Perl. +including Java/JDBC, ODBC, .NET, Delphi, Python, PHP, Ruby, Node.js, C++ and Perl.
@@ -490,7 +496,8 @@ copied it. More recently, Microsoft has introduced MGA in the latest evolution Transaction Logging and Firebird Firebird does not need transaction logging for recovery purposes and it does not include any transaction logging facilities in the engine. However, where enterprises require logging for auditing -purposes, some excellent logging service software is available from third party vendors. +purposes in Firebird 2.5 were introduced the new trace and audit facilities that enable various events performed inside the engine, such as statement execution, connections, disconnections, +etc., to be logged and collated for real-time analysis of the corresponding performance characteristics.
@@ -814,8 +821,7 @@ resulting in a see-saw effect, whereby performance will continual at busy times, while the system waits for the OS to shift all of the Superserver's active memory resources from one CPU to another when it detects unevenness in CPU utilisation. Superserver is configured by default to be pinned to a single CPU to avoid this. - On Linux, multiprocessor handling does not cause this see-saw effect on 2.6 kernels and higher, -although it has been reported on some 2.4 kernels on older SMP hardware. However, SMP does + On Linux, multiprocessor handling does not cause this see-saw effect on 2.6 kernels and higher. However, SMP does not gain any significant performance benefit for Superserver on Linux, either. Support for configurable levels of SMP-aware, fine-grained multi-threading has been architected into the Vulcan engine and will become a feature of Firebird 3. It has already demonstrated @@ -1072,4 +1078,4 @@ as a way to put something back into the development. - \ No newline at end of file + diff --git a/src/docs/papers/firebird_php_linux.xml b/src/docs/papers/firebird_php_linux.xml index eb138db1..3eaa1845 100644 --- a/src/docs/papers/firebird_php_linux.xml +++ b/src/docs/papers/firebird_php_linux.xml @@ -16,33 +16,33 @@ - 4 March 2008 v.1.0.1 + 8 Feb 2013 v.1.1.1
Setting up PHP and Firebird on Linux - This paper offers a succinct description of the steps we took to set up PHP 5 + This paper offers a succinct description of the steps we took to set up PHP 5 and Apache Http server 2.4.x on Linux to work with Firebird.
Preparation - Obtain the source code of Apache HTTP Server (2.2.8): - http://apache.wildit.net.au/httpd/httpd-2.2.8.tar.bz2 + Obtain the source code of Apache HTTP Server (2.4.3): + http://apache.wildit.net.au/httpd/httpd-2.4.3.tar.bz2 - Obtain the source code of PHP (5.2.5): - http://au.php.net/get/php-5.2.5.tar.bz2/from/au2.php.net/mirror + Obtain the source code of PHP (5.4.11): + http://www.php.net/get/php-5.4.11.tar.bz2/from/au1.php.net/mirror Unpack httpd to, e.g. - /yourhome/apps/httpd-2.2.8. + /yourhome/apps/httpd-2.4.3. - Unpack php to, e.g. /yourhome/apps/php-5.2.5. + Unpack php to, e.g. /yourhome/apps/php-5.4.11. @@ -58,15 +58,25 @@
Build and Installation - Adjust the paths to suit your own configuration. + Adjust the paths to suit your own configuration (You need to apr and apr-utils extracted in the srclib folder with these exact names + apr and apr-utils, In Debian/Ubuntu you can bring all dependencies with apt-get build-dep apache2, and you can skip the --with-included-apr configuration option) .
Apache -cd /yourhome/apps/httpd-2.2.8 +cd /yourhome/apps/httpd-2.4.3 -./configure --enable-so --prefix=/yourhome/inst/httpd +cd srclib +wget http://mirrors.hostingromania.ro/apache.org/apr/apr-1.4.6.tar.bz +wget wget http://mirrors.hostingromania.ro/apache.org/apr/apr-util-1.5.1.tar.bz +tar -jxf apr-1.4.6.tar.bz +tar -jxf apr-util-1.5.1.tar.bz +mv apr-1.4.6 apr +mv apr-util-1.5.1 apr-util +cd .. + +./configure --with-included-apr --enable-so --prefix=/yourhome/inst/httpd make @@ -77,10 +87,12 @@ make install
PHP -cd /yourhome/apps/php-5.2.5 +cd /yourhome/apps/php-5.4.11 ./configure --with-interbase=/opt/firebird/ \ +--with-pdo-firebird=/opt/firebird/ \ + --with-apxs2=/yourhome/inst/httpd/bin/apxs --disable-libxml \ --disable-dom --disable-simplexml --disable-xml \ @@ -200,4 +212,4 @@ ibase_close($res) or die(ibase_errmsg()); - \ No newline at end of file + From 60aaa31236c8c9bf42c097f698e557acf77cf057 Mon Sep 17 00:00:00 2001 From: Popa Adrian Marius Date: Thu, 14 Feb 2013 15:47:47 +0000 Subject: [PATCH 15/33] Add apache 2.4.x mpm safe notice --- src/docs/papers/firebird_php_linux.xml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/docs/papers/firebird_php_linux.xml b/src/docs/papers/firebird_php_linux.xml index 3eaa1845..9154e623 100644 --- a/src/docs/papers/firebird_php_linux.xml +++ b/src/docs/papers/firebird_php_linux.xml @@ -16,7 +16,7 @@ - 8 Feb 2013 v.1.1.1 + 14 Feb 2013 v.1.1.2
@@ -59,7 +59,12 @@ Build and Installation Adjust the paths to suit your own configuration (You need to apr and apr-utils extracted in the srclib folder with these exact names - apr and apr-utils, In Debian/Ubuntu you can bring all dependencies with apt-get build-dep apache2, and you can skip the --with-included-apr configuration option) . + apr and apr-utils, In Debian/Ubuntu you can bring all dependencies with apt-get build-dep apache2, and you can skip the --with-included-apr configuration option) . + The safest mpm module to configure with Apache and php is prefork --with-mpm=prefork , if you want to use the threaded + module you can add --with-mpm=worker.The event module (default one) combined with php module is considered experimental ,it can lead to silent crashes , some page request will never return. + Usually is good for static content and not for dynamic pages. Prefork is safest because for each request a new process will be created and it runs in it's own process space, + the worker option leads to thread creation instead of a child, it can be faster when you use it with mod_fastcgi+php-fpm also it uses less memory. +
@@ -76,7 +81,7 @@ mv apr-1.4.6 apr mv apr-util-1.5.1 apr-util cd .. -./configure --with-included-apr --enable-so --prefix=/yourhome/inst/httpd +./configure --with-included-apr --enable-so --prefix=/yourhome/inst/httpd --with-mpm=prefork make From 3e8778db8582f299deaf3dbb23859466feaa6e99 Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Tue, 9 Apr 2013 14:24:20 +0000 Subject: [PATCH 16/33] Updated to reflect error exits since release 2.1 RC1 --- src/docs/firebirddocs/fbutil_gfix.xml | 31 ++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/src/docs/firebirddocs/fbutil_gfix.xml b/src/docs/firebirddocs/fbutil_gfix.xml index a7f411fd..0444edac 100644 --- a/src/docs/firebirddocs/fbutil_gfix.xml +++ b/src/docs/firebirddocs/fbutil_gfix.xml @@ -15,7 +15,7 @@ Dunbar - 11 October 2011 – Document version 1.3 + 09 April 2013 – Document version 1.4
@@ -1706,6 +1706,15 @@ gfix version LI-V2.0.0.12748 Firebird 2.0 fail to complete without an error, return a response of 0 to the operating system. + + This problem was fixed in Firebird 2.1 RC1. It has been tested + and a successful operation returns zero to the shell while a failure + returns 1. + + This section will remain in the manual as there are still a + large number of users with older versions of Firebird. + + For example, the following shows two attempts to shut down the same database, the second one should fail - it displays an error message - but still returns a zero response to the operating system. This makes @@ -1721,6 +1730,12 @@ Target shutdown mode is invalid for database - "/home/norman/firebird/my_employee.fdb" linux> echo $? 0 + + + As mentioned above, this is no longer a problem from release 2.1 + RC1 onwards. The second attempt to close the database will correctly + return 1 to the shell. +
@@ -1876,6 +1891,20 @@ has been prepared. Updated for Firebird 2.5. + + + 1.4 + + 09 April 1013 + + ND + + + Updated to note that gfix returns + correct error codes to the shell from release 2.1 RC1 + onwards. + + From 2613c81fd6a466824b253a3ac701cd851fd1eb8a Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Thu, 11 Apr 2013 11:46:47 +0000 Subject: [PATCH 17/33] Added scetion on speeding up the backups --- src/docs/firebirddocs/fbutil_gbak.xml | 68 ++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 7 deletions(-) diff --git a/src/docs/firebirddocs/fbutil_gbak.xml b/src/docs/firebirddocs/fbutil_gbak.xml index 05f271e6..7da7d5af 100644 --- a/src/docs/firebirddocs/fbutil_gbak.xml +++ b/src/docs/firebirddocs/fbutil_gbak.xml @@ -15,7 +15,7 @@ Dunbar - 14 January 2013 - Document version 1.8 + 11 April 2013 - Document version 1.9
@@ -432,7 +432,7 @@ gbak:general options are: Normally gbak connects to the database as any other connection would and garbage collection runs normally. Using this switch prevents garbage collection from running during - the course of the backup. + the course of the backup. This can help speed up the backup. @@ -503,6 +503,13 @@ gbak:general options are: to be created on the remote server, so the path format and filename must be valid on the remote server. The servicename is currently always the text service_mgr. + + + You can use this option to connect to a locally hosted + database as well. If you do, taking a backup using this option can + run quicker than accessing the database directly. See the section + below on speeding up backups. + @@ -866,6 +873,38 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test For further proof of reliability, the application may be tested against this clone of the live database to ensure all is well. + +
+ Speeding up the Backup + + There are a couple of tricks you can use to speed up the backup. + The first is to prevent the garbage collection from being carried out + while the backup is running. Garbage collection clears out old record + versions that are no longer required and this is usually covered by a + sweep - manual or automatic - or by a full table scan of any affected + table. As gbak accesses all the rows in the + tables being backed up, it too will trigger the garbage collection and, + if there have been a large number of updates, can slow down the backup. + To prevent garbage collection during the backup, use the + -g[arbage_collect] option. + + tux> gbak -backup -garbage_collect employee /backups/employee.fbk + + The second option is to backup the database using the + -se[rvice] option. Although this is used to + perform remote backups, it can be used locally as well. Using this + option can help speed up your backups. + + tux> gbak -backup -service tux:service_mgr employee /backups/employee.fbk + + The example above backs up the employee database, on the tux + server, "remotely" using the service manager. The tux server is, of + course, where the command is running, so it isn't really running + remotely at all. + + You can, of course, combine the -g[arbage_collect] + and -se[rvice] options. +
@@ -888,7 +927,7 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test a database onto any version of Firebird. - You can change the SQL Dialect using + You can, if you wish, change the SQL Dialect using gfix. Under normal circumstances, restoring a database takes place as a @@ -1772,7 +1811,7 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log gbak will force gbak to use processing that will not seek on the input or output channels, making them suitable for use in pipes - as - per the examples in the recipes section above. + per the examples in the recipes section above. These file names, while they appear to be POSIX names, are definitely not synonyms for /dev/stdin or @@ -1780,7 +1819,7 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log gbak checks for while processing its parameters. Do not attempt to use names /dev/stdin or /dev/stdout in a piped process as it will most - likely fail. + likely fail. If you wish to create a dump file actually named either stdin or stdout, then you should specify the filename as a full, or relative, @@ -1944,6 +1983,21 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log file names. + + + 1.9 + + 11 April 2013 + + ND + + + A section has been added to explain how to speedup your + backups. A note has been added to the + -service option to explain that it's use is + not restriced to remote databases.. + + @@ -1965,7 +2019,7 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log The Initial Writer of the Original Documentation is: Norman Dunbar. - Copyright (C) 2009. All Rights Reserved. Initial Writer contact: - NormanDunbar at users dot sourceforge dot net. + Copyright (C) 2009-2013. All Rights Reserved. Initial Writer + contact: NormanDunbar at users dot sourceforge dot net. From 7828473748632fc9a6708d43c213949f59c37b28 Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Thu, 11 Apr 2013 12:14:24 +0000 Subject: [PATCH 18/33] Some examples had incorrect syntax. --- src/docs/firebirddocs/fbutil_gbak.xml | 58 ++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/src/docs/firebirddocs/fbutil_gbak.xml b/src/docs/firebirddocs/fbutil_gbak.xml index 7da7d5af..ae525e89 100644 --- a/src/docs/firebirddocs/fbutil_gbak.xml +++ b/src/docs/firebirddocs/fbutil_gbak.xml @@ -751,6 +751,13 @@ gbak:general options are: Use the services manager on a remote database to restore a remote database. The servicename is currently always the text service_mgr. + + + You can use this option to connect to a locally hosted + database as well. If you do, restoring a backup using this option + can run quicker than accessing the database directly. See the + section below on speeding up restores. + @@ -893,7 +900,9 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test The second option is to backup the database using the -se[rvice] option. Although this is used to perform remote backups, it can be used locally as well. Using this - option can help speed up your backups. + option can help speed up your backups. It simply avoids the data being + copied over the TCP network which can slow down the actions of the + backup. tux> gbak -backup -service tux:service_mgr employee /backups/employee.fbk @@ -1009,6 +1018,27 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test process of restoring a database for upgrade.
+ +
+ Speeding up the Restore + + The restoration of a database, from a backup, can be made to + execute quicker if the -se[rvice] option is used. + Although this is used to perform remote restores, it can be used locally + as well. It simply avoids the data being copied over the TCP network + which can slow down the actions of the restore. + + tux> gbak -replace -service tux:service_mgr /backups/employee.fbk employee + + + The example above backs up the employee database, on the tux + server, "remotely" using the service manager. The tux server is, of + course, where the command is running, so it isn't really running + remotely at all. + + You can, of course, combine the -g[arbage_collect] + and -se[rvice] options. +
@@ -1122,19 +1152,25 @@ tux> gbak -replace -verify -y restore.log employee.fbk employee.restore.test of 60 seconds, the shutdown will timeout and the database will remain open. - After the restore of the database has completed, the database will - automatically be opened again for use. + + After the restore of the database has completed, the database + will automatically be opened again for use. +
A Simple Backup & Restore + This example takes a backup, then immediately overwrites the + original database using the new backup. This is not normally a good idea + as the first action of a restore is to wipe out the database. + tux> # Backup the database. tux> gbak -backup employee /backups/employee.fbk tux> # Restore the database. tux> gfix -shut -tran 60 employee -tux> gbak -replace overwrite /backups/employee.fbk employee +tux> gbak -replace /backups/employee.fbk employee
@@ -1152,7 +1188,8 @@ tux> gbak -replace overwrite /backups/employee.fbk employee tux> #Backup only the database metadata. tux> gfix -shut -tran 60 employee -tux> gbak -backup -meta_data employee employee.meta.fbk +tux> gbak -backup -meta_data employee employee.meta.fbk + When the above dump file is restored on the production server, only the meta data will be present. @@ -1242,7 +1279,7 @@ Firebird environment set for version 2.1. tux> # Recreate the database and upgrade the ODS. tux> gfix -shut -tran 60 employee -tux> gbak -replace overwrite /backups/employee.2_0.fbk employee +tux> gbak -replace /backups/employee.2_0.fbk employee tux> # Check new ODS version (as root user!) tux> gstat -h employee|grep ODS @@ -1272,7 +1309,7 @@ tux> gstat -h employee | grep -i buffer tux> # Restore the database & change the cache size. tux> gfix -shut -tran 60 employee -tux> gbak -replace overwrite -buffer 200 /backups/employee.fbk employee +tux> gbak -replace -buffer 200 /backups/employee.fbk employee tux> # Check the new cache size (as root user!) tux> gstat -h employee | grep -i buffer @@ -1299,7 +1336,7 @@ tux> gstat -h employee | grep -i "page size" tux> # Restore the database & change the page size. tux> gfix -shut -tran 60 employee -tux> gbak -replace overwrite -page_size 8192 /backups/employee.fbk employee +tux> gbak -replace -page_size 8192 /backups/employee.fbk employee tux> # Check the new page size (as root user!) tux> gstat -h employee | grep -i "page size" @@ -1337,7 +1374,7 @@ employee.fbk | 19 kB | 19.3 kB/s | ETA: 00:00:00 | 100% tuxrep> # Restore the employee database as read-only. tuxrep> gfix -shut -tran 60 employee -tuxrep> gbak -replace overwrite -mode read_only employee.fbk employee +tuxrep> gbak -replace -mode read_only employee.fbk employee tuxrep> # Check database mode (as root user) tuxrep> gstat -h employee|grep -i attributes @@ -1995,7 +2032,8 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log A section has been added to explain how to speedup your backups. A note has been added to the -service option to explain that it's use is - not restriced to remote databases.. + not restriced to remote databases. Syntax errors in some examples + corrected. From 386238860a7a4ee9280ab7cc0468d9b10236b380 Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Wed, 1 May 2013 15:09:08 +0000 Subject: [PATCH 19/33] Updated -use_all_space switch details. --- src/docs/firebirddocs/fbutil_gbak.xml | 28 ++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/src/docs/firebirddocs/fbutil_gbak.xml b/src/docs/firebirddocs/fbutil_gbak.xml index ae525e89..ccbc4f65 100644 --- a/src/docs/firebirddocs/fbutil_gbak.xml +++ b/src/docs/firebirddocs/fbutil_gbak.xml @@ -15,7 +15,7 @@ Dunbar - 11 April 2013 - Document version 1.9 + 1 may 2013 - Document version 1.10
@@ -764,10 +764,14 @@ gbak:general options are: -USE_[ALL_SPACE] This switch forces the restore to use 100% of each database - page and thus not leave room for changes. By default, 80% of a page - is used and 20% kept for changes. This switch is likely to be only - of practical use where the database is created and used in read-only - mode. + page and thus not leave room for changes. If you omit this switch, + 80% of a page will be used and 20% kept for changes. Using this + switch is likely to be only of practical use where the database is + created and used in read-only mode and no updates to existing data + are required. + + Once the database has been restored, normal usage of database + pages will continue for any new pages created. @@ -2036,6 +2040,20 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log corrected. + + + 1.10 + + 1 May 2013 + + ND + + + Slight update to the -use_[all_space] + command line switch, to explain how it works in a more + understandable manner. + + From 84c6014eeebfdc887e5cb9c9d5c4c1e8bbc24a1e Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Wed, 1 May 2013 16:29:23 +0000 Subject: [PATCH 20/33] Corrected -use_all_space switch details. --- src/docs/firebirddocs/fbutil_gbak.xml | 46 +++++++++++++++++++++------ 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/src/docs/firebirddocs/fbutil_gbak.xml b/src/docs/firebirddocs/fbutil_gbak.xml index ccbc4f65..2272b3e4 100644 --- a/src/docs/firebirddocs/fbutil_gbak.xml +++ b/src/docs/firebirddocs/fbutil_gbak.xml @@ -15,7 +15,7 @@ Dunbar - 1 may 2013 - Document version 1.10 + 1 may 2013 - Document version 1.11
@@ -764,14 +764,27 @@ gbak:general options are: -USE_[ALL_SPACE] This switch forces the restore to use 100% of each database - page and thus not leave room for changes. If you omit this switch, - 80% of a page will be used and 20% kept for changes. Using this - switch is likely to be only of practical use where the database is - created and used in read-only mode and no updates to existing data - are required. - - Once the database has been restored, normal usage of database - pages will continue for any new pages created. + page and thus not leave any room for changes. If you omit this + switch, some space will be kept free for subsequent changes. Using + this switch is likely to be only of practical use where the database + is created and used in read-only mode and no updates to existing + data are required. + + + Once a database has been restored with this option + specified, all database pages will be filled + to 100% and no free space will be left for updates. Use of this + switch set a flag in the database header page to signal that + all pages are to be filled to 100% - this + applies to any new pages created after the restore. + + You can override this setting, using gfix -use full + | reserve database_name where + full uses 100% of each page and + reserve reserves some space for subsequent + updates. See the gfix manual for more + details. + @@ -2054,6 +2067,21 @@ tux> gbak -backup employee /backups/${FILENAME}.fbk -y /logs/${FILENAME}.log understandable manner. + + + 1.11 + + 1 May 2013 + + ND + + + A correction to the above change to the + -use_[all_space] command line switch - it + affects all subsequent pages as well as the ones created during + the restore. + + From 65c3a1f01e6877c3b3453e36a4a2330a33146ca9 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Wed, 28 Aug 2013 16:20:55 +0000 Subject: [PATCH 21/33] =?UTF-8?q?New=20German=20translations=20by=20Martin?= =?UTF-8?q?=20K=C3=B6ditz=20committed=20to=20release=20branch.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/docs/firebirddocs-de.xml | 24 +- .../firebirddocs-de/docwriting-howto-de.xml | 4052 +++++++++++++++++ .../firebirddocs-de/fb-docwriters-info-de.xml | 16 + src/docs/firebirddocs-de/fbdoc_vpn-de.xml | 509 +++ .../firebirddocs-de/font-embedding-de.xml | 695 +++ 5 files changed, 5289 insertions(+), 7 deletions(-) create mode 100644 src/docs/firebirddocs-de/docwriting-howto-de.xml create mode 100644 src/docs/firebirddocs-de/fb-docwriters-info-de.xml create mode 100644 src/docs/firebirddocs-de/fbdoc_vpn-de.xml create mode 100644 src/docs/firebirddocs-de/font-embedding-de.xml diff --git a/src/docs/firebirddocs-de.xml b/src/docs/firebirddocs-de.xml index d04299e1..3a3d0b91 100644 --- a/src/docs/firebirddocs-de.xml +++ b/src/docs/firebirddocs-de.xml @@ -3,6 +3,10 @@ + + + + ]> Firebird Dokumentation @@ -19,10 +23,10 @@ Teil des Firebird Projekts erstellt haben. Die Dokumentation wurde im DocBook XML Format erstellt und danach nach HTML und PDF transformiert. - So wie das Universum, wird auch diese Zusammenstellung laufend erweitert. - Dies bedeutet, dass bis datto nur ein Teil der Firebird Dokumentation zur Verfügung steht, vor allem + So wie das Universum, expandiert auch unsere Zusammenstellung der Dokumente. + Dies bedeutet, dass bis dato nur ein Teil der Firebird-Dokumentation zur Verfügung steht, vor allem in deutscher Sprache. - Wenn Ihnen etwas Bestimmtes abgeht, dann besuchen + Wenn Ihnen etwas Bestimmtes fehlt, dann besuchen Sie die folgenden URLs um mehr zu finden (vor allem in englischer Sprache):
http://www.firebirdsql.org/index.php?op=doc @@ -40,7 +44,7 @@ Portugiesisch | Russisch
- Für PDF Versionen, besuchen Sie den Dokumentationsindex (erster Link oben) oder + Für PDF-Versionen, besuchen Sie den Dokumentationsindex (erster Link oben) oder durchsuchen Sie die Verzeichnisse hier http://www.firebirdsql.org/pdfmanual/. Fremdsprachige Versionen befinden sich in den Unterordnern en, fr usw. Die Homepage des Firebird Dokumentationsunterprojekts befindet sich hier: @@ -77,15 +81,21 @@ &coexist-article-de; --> &nbackup-de; + + + - + + &fb-docwriters-info-de; + + +
+ Einleitung + +
+ Gegenstand dieses Dokuments + + Dieser Leitfaden behandelt die verschiedenen Aspekte des Schreibens von Dokumentation für Firebird. + Er ist gedacht für Menschen, die helfen, Dokumentation für das Firebird-Projekt zu schreiben, oder dies zumindest in Erwägung ziehen. + Nach der Lektüre dieses Leitfadens, besitzen Sie alle notwendigen Kenntnisse, + um mit dem Schreiben von Firebird-Dokumenten in unserem gewählten Format, DocBook XML, beginnen zu können. +
+ +
+ Vorausgesetzte Kenntnisse + + Bevor Sie dieses Handbuch lesen, prüfen Sie, ob Sie bereits folgendes wissen: + + + + Was das Firebird manual Modul ist. + + + + Was CVS ist und wie ein CVS-Client verwendet wird, um das aktuelle manual Modul herunterzuladen. + + + + Wie die aktuelle Firebird-Dokumentation mittels des heruntergeladenen manual Modul funktioniert. + + + + + Dieses Wissen ist wichtig, wenn Sie sich daranmachen wollen, Daten zu unserem Dokumentations-Projekt beizutragen. + Wenn Sie sich unsicher an einem oder mehreren dieser Punkte fühlen, lesen Sie zunächst das Firebird + Docbuilding Howto, und kehren Sie dann hierher zurück. +
+ +
+ Themen dieses Handbuchs + + Wir starten mit ein paar kurzen Kapiteln über: + + + + Die firebird-docs mailing list. + + + + Auswahl eines Themas. + + + + Erstellung eines Abrisses für Ihr Dokument. + + + + Danach werden wir einige Zeit benötigen, + um die Grundlagen der DocBook XML zu erörtern, denn das ist das Format, dass wir gern von Ihnen bekommen möchten. Dies bezieht folgendes ein: + + + + DocBook XML – was ist das? + + + + Gründe weshalb wir DocBook anderen Formaten vorziehen. + + + + Werkzeuge, die Sie verwenden können, um DocBook-Texte zu erstellen. + + + + Nicht tragisch, wenn Ihnen DocBook bis jetzt nichts sagt: + das benötigte Wissen können Sie innerhalb kürzester Zeit (weniger als eine Stunde) aneignen, + und die Chancen, dass Sie hiervon bei anderen Projekten profitieren ist sehr hoch. + + Der nächste Abschnitt behandelt das Schreiben der Dokumente selbst - das Docwriting: + + + + Erstellen des eigentlichen Dokuments. + + + + Nutzung der DocBook-Elemente. + + + + Ein, zwei Worte zu Sprache und Schreibstil. + + + + Copyrights und die Public Documentation License. + + + + Abschließend, werden wir Ihnen zeigen, wie Sie Ihr fertiges Dokument zum Firebird-Projekt hinzufügen. Hauptthemen dieses Abschnitts sind: + + + + Commiting des fertiggestellten Dokuments zum manual Modul. + + + + Wo Sie die Commit-Rechte erhalten, wenn Sie noch keine besitzen sollten. + + + + Was man tut oder besser nicht tut, sobald man die Commit-Rechte hat. + + + + Veröffentlichung von HTML- und PDF-Versionen auf der Firebird-Webseite. + + +
+
+ +
+ Wo treffen sich die Dokumentenersteller? + +
+ Die Homepage des Unterprojekts + + Die Homepage des Dokumentations-Unterprojektes ist hier zu finden: + +
+ http://www.firebirdsql.org/index.php?op=devel&sub=doc +
+ + Es stellt Neuigkeiten über unsere Aktivitäten, Links zu unseren bereits veröffentlichten Dokumenten, Zukunftspläne, etc. +
+ +
+ Die firebird-docs list + + Wenn Sie ernsthaft daran interessiert sind, Dokumente für Firebird zu schreiben, sollten Sie sich in der Mailing-Liste einschreiben, wo wir unsere Pläne und Arbeiten + diskutieren. Diese Liste ist für jeden offen und einschreiben kostet Sie nichts. Senden Sie eine E-Mail an: + +
+ firebird-docs-request@lists.sourceforge.net +
+ + mit den Worten subscribe entweder als Betreff oder als die erste und einzige Zeile im E-Mail-Text. Alternativ können Sie auch das + Formular auf der Webseite verwenden: + +
+ http://lists.sourceforge.net/lists/listinfo/firebird-docs +
+ + Welche Methode Sie auch verwenden, Sie erhalten innerhalb weniger Minuten eine E-Mail von der Liste. + Folgen Sie den Anweisungen der E-Mail und schon stehen Sie mit auf der Liste. +
+ +
+ Die Atkin news-Schnittstelle + + Es gibt außerdem eine News-Schnittstelle für diese und andere Firebird-bezogenen Mailinglisten. + Manchmal arbeitet diese etwas problematisch - oder gar nicht, obwohl das selten vorkommt. + Ich empfehle, die Schnittstelle nicht für das Posten von Nachrichten zu verwenden, sondern zum Archivieren und Durchsuchen - dafür ist die wirklich großartig. + Wenn Sie alle vorliegenden Meldungen vom Server + holen, haben Sie eine schöne Historie aus der Zeit vor Ihrer Teilnahme. + + Um auf die Newsgroup zuzugreifen, verweisen Sie Ihren Newsreader auf: + +
+ news.atkin.com +
+ + und holen Sie sich die Grouplist. Schreiben Sie sich bei den gewünschten Groups ein. + Beachten Sie, dass die Liste firebird-docs list auf + sourceforge.firebird-doc (ohne s) auf dem Atkin News Server verweist. + + Abhängig vom verwendeten Newsreader oder Browser, kann Sie auch folgender Link direkt zur Newsgroup führen: + +
+ news://news.atkin.com/sourceforge.firebird-doc +
+ + Sie können auch an die Newsgroup schreiben (posten), wenn Sie sich nicht in die Liste eingeschrieben haben. + Jedoch muss die Freigabe für die Mailing list durch einen menschlichen Moderator erfolgen. Das bedeutet natürlich, dass + die Veröffentlichung bis zu einem Tag (oder mehr Tage) verzögert wird. +
+
+ +
+ Auswahl eines Themas + + Diese Richtlinien sollen Ihnen helfen ein Thema zu finden, über das Sie schreiben können: + + + + Machen Sie sich zunächst klar, was es bereits gibt – niemand wartet auf drei Migrations-Anleitungen von MS-SQL zu Firebird. + + + + Fragen Sie sich selbst, was fehlt und was hilfreich für Firebird-Anwender im Allgemeinen oder im Speziellen sein kann. + + + + Fragen Sie sich außerdem worüber Sie gern schreiben möchten. + Die logischste Wahl trifft auf ein Thema mit dem Sie vertraut sind, aber Sie können natürlich + auch eines wählen, über das Sie mehr lernen möchten (das ist natürlich deutlich mehr Arbeit, aber + eine großartige Lernerfahrung, sofern Sie bereit sind die Zeit zu investieren). + + + + + Sie müssen nicht zwangsläufig ein ganzen Buch, eine riesige Anleitung oder Artikel schreiben. + Vielleicht arbeiten bereits andere an einem größeren Dokument, zu dem Sie etwas beisteuern können. Vielleicht schreiben + Sie ein oder mehrere Kapitel für ein Buch. Sie können aber auch Rohdokumente für ein Thema, über das Sie eine Menge wissen, bereitstellen. + + + + + Sprechen Sie über Ihre Ideen - oder suchen Sie danach - in der + firebird-docs list. Es kann passieren, dass der Antwortryhtmus der Liste sehr niedrig ist, aber seien Sie versichert, dass die Nachrichten gelesen + werden und auch beantwortet. + + +
+ +
+ Vorbereitung aufs Schreiben: Erstellung eines Abrisses! + + Es ist immer eine gute Idee einen Abriss zu erstellen, bevor man anfängt zu schreiben. + Dies hilft Ihnen sich zu organisieren. + Außerdem verringert er das Risiko etwas wichtiges zu vergessen und es macht das Schreiben deutlich leichter. + + Folgen Sie diesen Schritten, um einen Abriss zu erstellen: + + + + Definieren Sie genau, was Ihre Leser von Ihrem Werk lernen sollen. + + + + Teilen Sie das Thema in logische Einheiten auf - Kapitel und/oder Bereich bzw. Unterbereiche. + + + + Stellen Sie sicher, dass die Reihenfolge der Einheiten Sinn macht. Insbesondere für Howtos, Tutorials oder Anwenderhandbücher. + Das heißt: Arrangieren Sie die Einheiten so, dass der Benutzer das was er als erstes tun oder lernen muss auch zuerst liest. + + + + Legen Sie den Abriss der Mailinglist firebird-docs auf + sourceforge.net vor und fordern Sie Kommentare hierzu. + + + + Sobald Sie zufrieden mit Ihrem Abriss sind, + schauen Sie sich diesen nochmals genau an und entscheiden Sie, ob alle notwendigen (Roh-)Informationen + vorhanden sind, die Sie zum Schreiben benötigen. Idealerweise sollten Sie diese + vorliegen haben, bevor Sie beginnen, da manchmal ein fehlendes Stück Info ausreicht, Ihre gesamte Dokumentenstruktur zu überarbeiten. + Also ist es besser diese Information schon vorher zu haben. +
+ +
+ DocBook XML – Eine Einleitung + + Das Format der Wahl für die Dokumentation innerhalb des Firebird manual Modul ist + DocBook XML. Sollten Sie bisher nicht vertraut mit XML und/oder DocBook sein, folgen noch kurze Einleitungen in XML + und DocBook. + Beachten Sie, dass diese Einleitungen nur einen vereinfachtes Bild zeigen können. + Aber das ist auch der Vorteil: Sie müssen kein DocBook-Experte sein um Firebird-Dokumente zu schreiben. Sie benötigen lediglich Basiswissen - welches + Sie in innerhalb einer halben Stunde von den u.a. Absätzen erlernen können - und ein wenig Erfahrung bei der Zuweisung von DocBook XML-Tags zu Ihren Texten + (diese werden Sie aber schnell während des Schreibens erlernen). + + Überspringen Sie die allgemeinen XML-Grundlagen, + wenn Sie bereits alles über XML-Element, -Tags, -Attribute, -Rendering und -Multichannel-Publishing wissen. + + Überspringen Sie beide Grundlagen, + wenn Sie auch schon Erfahrungen als DocBook-Author haben. + + + Obwohl wir strikt empfehlen, dass Sie zumindest versuchen sollten, Ihre Dokumente im DocBook-Format abzugeben, + akzeptieren wir natürlich auch, dass einige Leute nicht die Zeit haben sich einzuarbeiten (oder ihre existieren Dokus ins DocBook-Format zu konvertieren). + Wenn dies auf Sie zutrifft, sprechen Sie dies bitte in der firebird-docs list an. Wir werden sicherlich keine nützliche Dokumentation ablehnen, weil sie im falschen Format vorliegt. + + +
+ Sehr allgemeine XML-Grundlagen + + XML steht für Extensible Markup Language, + was vereinfacht ausgedrückt soviel bedeutet wie, Standardtext mit Markup-Tags versehen. Ein + typisches XML-Text-Fragment könnte so aussehen: + + <paragraph> +<loud>'No!'</loud> she screamed. <scary>But the bloody hand +<italics>kept on creeping</italics> towards her.</scary> +<picture file="bloody_hand.png"/> +</paragraph> + +
+ Tags und Attribute + + Im obigen Beispiel werden die Wörter und Sätze in spitze Klammern eingeschlossen. Dies sind die Markup-Tags. + italics ist ein Start-Tag + , italics ist ein + End-Tag, und picture + file="bloody_hand.png" ist ein alleinstehender Tag, offiziel + empty-element tag genannt. XML-Tags werden immer wie folgt formatiert: + +
+ Format of XML tags + + + + + Tag-Typ + + Beginnt mit + + Endet mit + + + + + + Start tag + + < + + > + + + + End tag + + </ + + > + + + + Empty-element tag + + < + + /> + + + +
+ + Immer noch unserem Beispiel folgend, sind + paragraph, loud, + scary, italics and + picture Tag-Namen. Im + Tag picture... ist file="bloody_hand.png" ein + Attribut, mit file als Attributnamen + und bloody_hand.png als Attributwert. + Attributwerte stehen immer in Anführungszeichen; einfache und doppelte sind beide erlaubt. + + XML erlaubt Ihnen beliebige Tags zu definieren, solange Sie diese korrekt erstellen. Somit sind thistag, + thattag, und this_is_not_a_tag wohlgeformte (well-formed) XML-Tags. + (XML welches dem Standard folgt, nennt man + wohlgeformte (engl. well-formed); Der Begriff + valid wird nur in spezifisch definierten Implementationen verwendet – DocBook XML zum Beispiel). + + Natürlich sollen die Tags selbst nicht im finalen Dokument erscheinen (das Dokument wird ja von den Lesern angeschaut). + Vielmehr kümmern sie sich um die Ausgabe, die durch die Tags beeinflusst wird. XML, wenn es zum Schreiben von Dokumentationen Verwendung findet, ist ein typisches + Quellformat, vorgesehen für die Verarbeitung durch Software, welche hübsch formatierte Ausgaben generiert. Die Ausgabe wird häufig als + Rendering bezeichnet. + + Einige Tags sind unmissverständliche Make-Up-Anweisungen: + + <italics>kept on creeping</italics> + + was natürlich bedeutet, dass die Wörter kept on + creeping kursiv dargestellt werden sollen. + Andererseits ist + + <loud>'No!'</loud> + + weniger offensichtlich zu verstehen. Soll das Wort No! + in Fettdruck erscheinen? Oder unterstrichen? Oder wieder kursiv? Vielleicht soll dieser + Text von einem Sprachprogramm laut vorgelesen werden, und das Tag + loud weist es an die Stimme zu heben. Diese Dinge sind alle möglich, und noch mehr: + Häufig wird ein einzelnes XML Quelldokument in verschiedene Ausgabeformate gewandelt + – sagen wir, ein PDF-Dokument, eine HTML-Webseite und eine Audio-Datei. Dies wird Multichannel-Publishing (engl. multichannel publishing) genannt. + Hiermit könnte loud im PDF als Fettdruck angezeigt werden; in der HTML-Seite wird es zu einem fetten, roten Text; und das Audioprogramm erhöht die Lautstärke um 50%. + + Schauen wir uns die anderen Tags an. picture... ist offensichtlich die Anweisung das Bild + bloody_hand.png einzufügen, und scary, + gut... das ist wieder weniger klar, genauso wie loud. + Vielleicht soll der Satz zwischen scary + zitternt mit Blutstropfen dargestellt werden. Vielleicht wird angsteinflößende Musik gespielt. + Dies hängt alles von den Leuten ab, die die Tags definieren und der Software die diese Interpretiert, also das Rendering. + + Abschließend haben wir noch das Tag paragraph, + welches ein Strukturtag ist. Es erzählt uns etwas über den Platz, den die Zeilen innerhalb der internen Dokumenthierarchie einnehmen. + Im endgültigen Dokument können Absätze mit Leerzeilen getrennt dargestellt werden. + Aber nochmal, dies hängt von der Rendering-Software ab, und denkbar sind auch Benutzerkonfigurations-Einstellungen. + Andere Strukturtags sind z.B. chapter, section und subdocument. +
+ +
+ Sonderzeichen und Entitäten + + Da das Zeichen < eine spezielle Bedeutung als Start eines Tags besitzt, können Sie dies nicht direkt als + literalen Wert (wörtlich) verwenden. Wenn Ihre Leser eine spitze Klammer sehen sollen, müssen Sie folgendes eintippen: + +
+ lt +
+ + Dies ist ein kaufmännisches Und, gefolgt von den Buchstaben + l und t (kleiner + als), gefolgt von einem Semikolon. Sie können außerdem gt (größer gleich) als schließende spitze Klammer + > verwenden, müssen dies aber nicht. + + XML hat viele dieser Codes; Sie heißen + entities. Einige repräsentieren Zeichen, wie + lt und auml (ä, kleines a mit Umlaut) und andere dienen ganz andeen Zwecken. + Aber alle beginnen mit einem kaufmännischen Und und enden mit einem Semikolon. + + Aber einen Moment... wenn alle Entitäten mit einem kaufmännischen Und starten, wie packen Sie dann ein + literales kaufmännisches Und in Ihren Text? Tja, dafür gibt es ebenfalls eine Entität: + +
+ amp +
+ + Somit wird diese Zeile XML: + + Kernigan &amp; Ritchie chose '&lt;' as the less-than operator for C. + + schlussendlich im Dokument zu: + + Kernigan & Ritchie chose '<' as the less-than + operator for C. + + Und hier noch die gute Nachricht: wenn Sie einen guten XML-Editor verwenden, dann können Sie wahrscheinlich einfach + < und + & eintippen wo Sie diese auch immer als Literale verwenden möchten. + Der Editor wird sicherstellen, dass sie als + lt und amp im XML gespeichert werden. + An späterer Stelle werden wir einige XML/DocBook-Editoren auflisten. + +
+ +
+ Elemente + + Es gibt ein weiteres wichtiges XML-Konzept über das Sie bescheid wissen sollten: + Das Element. Ein Element ist die Kombination aus Start-Tag, einem passenden End-Tag und das ganze dazwischen. + Dieses + ganze dazwischen wird als Element-Inhalt (engl. + content) bezeichnet, und es kann wiederum andere Elemente enthalten. + Elemente werden nach ihren Tags benannt. Somit können wir über Absatzelemente, Kursivelemente, etc. sprechen. + + + Elemente sind ein grundlegenderes Konzept als Tags. Tags sind bloß die Dinger, die Elemente identifizieren. + Somit wäre es besser zu sagen, dass Tags nach ihren Elementen benannt werden. Aber da Tags leichter zu erkennen sind als ein ganzes Element, werde ich diese zuerst erläutern. + + + Das ist ein Element: + + <loud>'No!'</loud> + + Das ist auch ein Element: + + <paragraph>This is an element containing <bold>another</bold> + element!</paragraph> + + Ein Leerelement-Tag (engl. empty-element tag) stellt das Element selbst dar. + Solche Elemente haben natürlich keinen Inhalt, da sie kein Tag-Paar besitzen: + + + <picture file="bloody_hand.png"/> + + + Verwechseln Sie Inhalt nicht mit Attributen. Inhalt liegt + zwischen den Tags, Attribute + innerhalb der Tags. Das Leerelement des letzten Beispiels besaß ein Attribut, aber keinen Inhalt. + + + Ich überstrapaziere das Konzept der Elemente etwas, da die meisten Dokumentationen + dazu tendieren von Kapitelelementen, + Titelelementen, etc. zu sprechen. Richtiger wären aber Kapitel-Tags + und Title-Tags. Die Begriffe werden oft synonym verwendet, + aber an manchen Stellen ist es wichtig die Unterschiede zu kennen. +
+ +
+ XML Zusammenfassung + + So – das war alles was Sie über XML wissen müssen. Sie sollten nun eine grundlegende Idee haben + was XML ist, wie es aussieht, was und wofür Tags sowie Elemente sind. + Wie ich schon sagte: Das Gesamtbild ist deutlich vereinfacht, aber für unsere Zwecke ausreichend. + + Es sollte außerdem klar sein, dass reines Schreiben von selbsterstelltem XML + relativ sinnlos ist, solange Sie keine Software besitzen, die + Ihre Tags verstehen. Wie sonst können Sie Ihre XML-Quellen in ein hübsch formatiertes Dokument umwandeln? + + Glücklicherweise müssen wir uns hierüber keine Sorgen machen. + Es stehen uns bereits einige formalisierte XML-Typen zu Verfügung, wovon jedes einen + Satz Tags und, genauso wichtig, einen Satz Regeln beinhaltet. Letztere sagen uns wie die Tags zu verwenden sind. + DocBook XML ist einer dieser XML-Typen. +
+
+ +
+ Eine DocBook XML Einleitung + + DocBook wurde entworfen, um das Schreiben strukturierter Dokumente unter Verwendung von SGML oder XML zu + verbessern (machen Sie sich keine Gedanken über SGML - wir nutzen den XML-Stamm). + Dies betrifft insbesondere das Schreiben technischer Dokumente und Artikel, vor allem für Computer-relevante Themen. + DocBook ist durch seine Document Type Definition bzw. + DTD definiert: Ein Satz von Definitionen und Regeln, die genau beschreiben, + wie ein gültiges DocBook-Dokument strukturiert ist. DocBook wurde schnell zum de facto-Standard für Computer-technische + Dokumente und wird durch eine wachsende Anzahl von Werkzeugen und Anwendungen unterstützt. + +
+ DocBook XML-Charakteristiken + + Wichtige Eigenschaften von DocBook - im Gegensatz zum + allgmeinen XML – sind: + + + + Die DocBook DTD definiert eine begrenzte Anzahl Tags und gibt genaue Regeln aus, wie diese zu verwenden sind: + Welche Attribute sind möglich für Tag A, ob Element B in Element C verschachtelt werden kann, u.s.w.. Wenn Sie undefinierte Tags benutzen + oder den Regeln nicht folgen, ist Ihr Dokument auch kein DocBook mehr (und DocBook-unterstützende Anwendungen versagen möglicherweise Ihren Dienst). + + + + DocBook-Tags vermitteln immer die Struktur und Semantiken + (Bedeutungen), niemals Aussehen. In DocBook werden Sie Struktur-Tags finden wie + book, part, chapter, section, para, table; and semantic tags like filename, warning, emphasis, postcode; but nothing like font, bold, center, indent, backgroundcolor – nichts was mit dem Layout oder Aussehen zu tun hat. + + + + Deshalb muss irgendwo eine Entscheidung getroffen werden, + wie die DocBook-Tags in ihr endgültiges Aussehen übersetzt werden sollen. + Diese Entscheidung (oder besser: die Rendering-Regeln) können statisch in die Tools einprogrammiert werden, + aber dies würde die Dinge sehr unflexibel gestalten. Darum sind die Regeln meistens + in den Stylesheets definiert. Ein Stylesheet ist ein Dokument, welches + dem Tool Zeug wie dieses erzählt: + +
+ Zeige Kapitelüberschriften als 24 Punkte großer, schwarzer Schrift an; + beginne jedes Kapitel auf einer neuen Seite; benutze kursiv für Betonungen; zeige Warnungen in fett und 12 Punkten an; + benutze Großschreibung für Abkürzungen; etc., etc. +
+ + Dieser Ansatz ermöglicht es dem Benutzer die Stylesheets nach seinen + Bedürfnissen zu verändern. Es würde deutlich aufwändiger sein - wenn nicht unmöglich - + die Tools selbst anzupassen. + + + Stylesheets die benutzt werden, um DocBook XML in andere + Formate zu wandeln, werden + transformation + stylesheets genannt. Sie werden in einer anderen Art XML geschrieben, + XSLT (eXtensible Stylesheet + Language for Transformations) genannt. + + + +
+ +
+ Vorteile von DocBook XML + + DocBook hat eine Menge Vorteile für alle, die technische Dokumentationen erstellen. + Dies sind die wichtigsten: + + + + Ein DocBook XML-Dokument besteht aus reinem, unverfälschtem + Inhalt. Sie werden sich niemals Gedanken über das + Aussehen machen müssen, während Sie schreiben. Sie können sich ganz auf + die Struktur und Information konzentrieren. Diese Praxis mag Ihnen etwas + altertümlich vorkommen, wenn Sie Text sonst in z.B. Word + verfassen, aber ich verspreche Ihnen: Sie werden es lieben lernen. + + + + Da sich DocBook nur um die Struktur und Bedeutung kümmert, + wird es überraschend einfach sein, Ihren kleinen Abriss in ein + DocBook-Skelett zu konvertieren. + + + + Viele Leute erstellen Dokumente für das manual Modul. + Wenn sie alle verschiedene Formate, oder gar ein einheitliches Format + wie Word oder HTML verwendeten, würden Ihre Ergebnisse sehr unterschiedlich + aussehen, da jeder sein eigenes Aussehen präferiert. + Natürlich könnten wir einen Satz Regeln hierfür erstellen, aber dann + müsste jeder Schreiber sich dieser Regeln annehmen und diese auch noch selbst + implementieren. Es ist also besser die Regelsätze an einem zentralen + Ort zu halten: Die Stylesheets, und somit den Dokumenterstellern Zeit + für ihre Dokumentation zu lassen. Sie müssen sich nicht um das Aussehen kümmern. + Die Stylesheets werden sicherstellen, dass alle unsere Dokumentationen gleich + Aussehen. + + + + Wenn wir das Aussehen unserer Dokumente nicht mögen, können + wir dieses einfach ändern, wenn die Regeln hierfür in Stylesheets + vorliegen. Nichts muss in den DocBook-Quellen selbst geändert werden; + alles was wir zu tun haben, nachdem die Stylesheets angepasst wurden, + ist die Dokumente neu zu rendern. Neu erstellte Dokus werden automatisch + das neue Aussehen erhalten. Versuchen Sie das mal zu erreichen, wenn Sie + Anweisungen für Aussehen und Styling in den Dokumenten verstreut sind! + + + + Ein weiterer Vorteil ist das DocBook ein offener Standard ist, + nicht an kommierzielle Belange oder ein bestimmtes System gekoppelt. + Wenn Sie das Firebird manual Modul herunterladen, können Sie die HTML- + und PDF-Dokumente aus den DocBook-Quellen unter Linux und Windows erstellen - + und wir können mehr Betriebssysteme unterstützen, wenn notwendig. + + + + Ein DocBook-Dokument ist reiner text, welcher ideal für + die Nutzung im CVS ist. Ja, ein CVS-Baum kann natürlich auch Binärdateien + enthalten, aber viele nützliche Eigenschaften, die CVS bietet (z.B. die Anzeige der Unterschiede + zwischen zwei Versionen einer Datei) funktionieren nur mit Text. + + + + Zugegebenermaßen, keiner der beschriebenen Vorteile gilt einzig und allein für DocBook. + Aber DocBook hat sie alle. Und es wird weitreichend unterstützt. Das macht es zur perfekten Wahl für + unsere Firebird-Dokumentationen. +
+ + +
+ + +
+ DocBook XML Schreibwerkzeuge + +
+ Text-Editoren + + Da DocBook ein nicht-binäres Format ist, können + Sie reine Texteditoren wie emacs, + pico, Windows + Notepad oder vi zum Schreiben + nutzen. Und in der Tat machen einige genau das, weil sie hiermit volle + Kontrolle über ihren Text haben und die handgeschriebenen Tags jederzeit + sichtbar sind. Auf der anderen Seite können diese Text-Editoren keine + Validierung Ihres DocBook-Dokuments durchführen: + Sie bemerken Ihre Fehler erst während des Erstellvorgangs. Und die Struktur eines + Dokuments - insbesondere große Dokumente - ist ebenfalls schwer im Textmodus zu analysieren. + Etwas Abhilfe schafft hier die Einrückung mehrerer Ebenen. + + Wenn Sie diesen Weg einschlagen wollen oder zumindest ausprobieren möchten, dann ist es eine + gute Idee einen Editor zu wählen, der zumindest XML Syntax-Highlighting unterstützt. + Ein guter Editor, der auch noch frei verfügbar ist, ist + ConText, zu finden unter http://www.fixedsys.com/context/. + Unglücklicherweise kann ConText nicht im UTF-8-Format speichern. Für US-ASCII-Dokumente + stellt dies kein Problem dar (speichern Sie den Text als DOS oder Unix und alles ist gut), aber sobald + Sie irgendwas oberhalb von ASCII 127 verwenden, wird ConText so gut wie nutzlos. Eine gute, freie + Alternative ist SciTE unter + http://scintilla.sourceforge.net/SciTEDownload.html. + Es ist weniger intuitiv, aber sehr mächtig. + + + Speichern Sie Dokumente, die + keinen US-ASCII-Inhalt besitzen, niemals in 8 Bit, weder in ConText noch einem anderen Editor! + Alles was über US ASCII hinaus geht, muss in einer Unicode-Kodierung, wie UTF-8 (für + die meisten Sprachen) oder UTF-16 (für einige Sprachen, falls die UTF-16-Dateilänge geringer + oder zumindest nicht viel größer als UTF-8 ist), gespeichert werden. Die Kodierungsprobleme stellen + weitere gute Gründe dar, einen XML-Editor zu nutzen: Sie werden die Daten + normalerweise automatisch in der korrekten Codierung speichern. + + +
+ +
+ XML-Editoren + + Dedizierte XML-Editoren haben häufig grafische Benutzeroberflächen, + die Tags schön (und manchmal irritierend) hervorheben; viele erlauben es Ihnen + die Elemente ein- und auszuklappen, so dass Sie die Struktur Ihres Dokumentes + sehen und gleichzeitig in das aktuelle Element hineinzoomen können. + Die meisten können Ihr Dokument gegen das DocBook DTD validieren und einige haben + einen speziellen DocBook-Bearbeitungsmodus, der es Ihnen ermöglicht, fast wie + in einer Textverarbeitung zu schreiben. + + Der Autor dieser Anleitung hat einige der Werkzeuge + ausprobiert (freie, günstige und Evaluierungsversionen) und empfand + XMLMind XML Editor als am nützlichsten. + Das ist eine persönliche Einschätzung; Ihre Erfahrung kann natürlich ganz anders aussehen. + + Einige XML-Editoren die Sie versuchen sollten: + + + + XMLMind XML Editor, kurz + XXE. Die Standard-Edition ist kostenfrei. + + http://www.xmlmind.com/xmleditor/ + + Läuft unter: Linux, Windows, Mac OS X. Benötigt Java, aber Sie benötigen Java eh, + da Sie die Dokumente sonst nicht aus den Quellen erstellen können – mehr unter Firebird + Docbuilding Howto. + + Features: Baumansicht (alle Elemente einklappbar) und gestylte Ansichten + (Kapitel und Bereiche klappbar). Ich arbeite normalerweise mit letzterem: + Die Ansicht zeigt das Dokument in grundlegendem, aber klarem Textverarbeitungsähnlichen + Layout, das in einem Stylesheet definiert ist, dass mit der Anwendung ausgeliefert wird. + Beide Ansichten können gleichzeitig aktiviert werden. Der DocBook-Modus lässt Sie nur DocBook-Anweisungen + einfügen. Element-Wähler. Attribut-Editor. Suchen und ersetzen. Rechtschreibprüfung. + Sonderzeichenauswahl. Schnellzugriffsfunktionen um häufig verwendete Elemente, wie sections, lists, tables, etc., + aufzurufen. Was ich vermisse ist eine Klartextansicht des XML-Quellcodes. + + + + Oxygen XML Editor. $ 48 für nichtkommerzielle Zwecke. Freie 30-Tage-Testversion. + + http://www.oxygenxml.com + + Läuft unter: Windows, Mac OS X, Linux, Eclipse. Benötigt + Java. + + Features: XML-Quellcode-Editor. Baumansicht. Attribut-Editor. + Gliederungsbereich. Tooltips für DocBook-Tags. XSLT-Debugger (ein leistungsfähiges + Tool, irrelevant für das Schreiben, aber großartig, wenn Sie mit unseren + Transformations-Stylesheets arbeiten wollen). + Validierung, Refactoring, Rechtschreibprüfung, etc.. Ein sehr guter XML-Editor. + + + + epcEdit. € 89 für nichtkommerzielle Nutzung. + 60-Tage Probierversion. + + http://www.epcedit.com + + Läuft unter: Linux, Windows, Solaris. Benötigt Tcl/Tk 8.1 oder höher + (im Paket enthalten). + + Features: Struktur-Baumansicht. Element-Wähler. Attributeditor. + Documentbereich kann zwischen Klartext und grafischen XML-Modus umschalten. + Kein spezieller DocBook-Modus, kann aber jedes XML-Dokument validieren, dass auf DTD basiert. + + + + Altova XMLSpy. The Home Edition ist mittlerweile frei. + + http://www.altova.com/products_ide.html + + Läuft unter: Windows, Eclipse. (Läuft angeblich auch mit Wine unter Linux + und auf Mac OS X mittels Virtual PC 6.) + + Features: Text- und Browseransichten. Alle Elemente klappbar in der Browseransicht. + Browseransicht nur lesbar. Elementwähler. Bearbeitungs- und Suchfunktionen. Attributwähler. + Sonderzeichenauswahl. + + Es gibt eine Feature-Matrix, die die Versionen Home, Professional und + Enterprise miteinander vergleicht http://www.altova.com/matrix_x.html. + + + + Diese Liste erhebt keinen Anspruch auf Vollständigkeit, + aber wenn Sie einen guten XML-Editor kennen + (gut aus der Perspektive eines Firebird-Dokumentenschreibers), der hier fehlt, + lassen Sie es uns über die Mailingliste wissen. +
+
+ +
+ Bereiten Sie Ihr DocBook-Dokument vor + + Hallo – Sie sind ja noch da! Ich weiss, ich habe viel Zeit darauf verwendet, + XML und DocBook zu erklären, aber ich hatte wirklich das Gefühl, dies tun zu müssen, + da dies für viele Menschen neue Konzepte sind. Einfach nur ein paar Links in den Raum zu + werfen und Sie dann allein zu lassen, würde vermutlich dazu führen, dass uns ein paar + brauchbare Schreiber verloren gingen. + + Egal, nun sind wir hier: Schlussendlich bereit loszulegen. Schreiben wir unser Dokument. + Dieser Abschnitt klärt die Einrichtung Ihres DocBooks; der nächste zeigt wie die korrekten + Tags und Attribute an den richtigen Stellen gesetzt werden. + +
+ Erstellung des Dokuments + + Jedes Stück der Dokumentation in unserem manual Modul ist Teil eines Dokumentensatzes, + engl. set. Dies ist das allererste Element in der + the DocBook-Hierarchie. Ein Dokumentensatz enthält eine Anzahl an Büchern (books), welche wiederum Kapitel (chapters) enthalten, und so weiter. + + Ein Vorteil Bücher in einem Dokumentensatzes zu platzieren, ist, dass Sie diese untereinander + referenzieren können. Das heißt, Sie könnten beispielsweise Links einfügen, die auf einen + Bereich eines anderen Buchs verweisen. Dieser Vorteil wird dadurch relativiert, dass diese Links nicht im PDF + funktionieren (im Gegensatz zu HTML). Ein anderer Vorteil ist die automatische Erstellung eines + Inhaltsverzeichnisses. + + Glücklicherweise bedeutet die Platzierung von Büchern im gleichen Satz nicht, dass + diese alle in der gleichen, großen Datei liegen müssen. DocBook erlaubt es Ihnen, + ein Hauptdokument, wie im Anschluss gezeigt, anzulegen. (Machen Sie sich keine Gedanken über + den Bereich, der mit "<!DOCTYPE" startet – Sie müssen keines + dieser fürchterlichen Dinge selbst schreiben. Im schlimmsten Fall müssen Sie diesen Teil nur + kopieren und anpassen, wenn Sie einen existierenden Dokumentensatz übersetzen.) + + + <?xml version="1.0" encoding="UTF-8"?> + +<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "docbookx/docbookx.dtd" [ + <!ENTITY preface SYSTEM "firebirddocs/preface.xml"> + <!ENTITY fb-intro SYSTEM "firebirddocs/firebirdintro.xml"> + <!ENTITY ...> + <!ENTITY ...> +]> + +<set id="firebird-books"> + &preface; + &fb-intro; + ... + ... +</set> + + Mit dem Einrichten des Hauptdokumentes, wie gerade beschrieben, werden die Bücher in je eigenen + Dateien vorgehalten: preface.xml, + firebirdintro.xml, etc.. Diese können nun unabhängig voneinander bearbeitet werden. + Eine solche Datei - Ihre zum Beispiel - ist allgemein so strukturiert: + + <?xml version="1.0" encoding="UTF-8"?> + +<book id="fbintro"> + <chapter id="fbintro-preface"> + ... + ... + </chapter> + <chapter id="fbintro-installing-firebird"> + ... + ... + </chapter> + ... + ... +</book> + + Natürlich muss das neue Dokument dem Haupt-Dokumentensatz bekannt gemacht werden, aber + das ist etwas worüber wir mit Ihnen sprechen werden, wenn Sie mit dem Schreiben starten. + (Wir geben hier keine allgemeine Richtlinie aus, da dies davon abhängt, was Sie schreiben wollen - + ein Buch, Artikel, ein oder mehrere Kapitel... - und Ihr Werk soll ja zum Rest passen.) + + + Jede DocBook-Datei muss mit der folgenden Zeile beginnen: + + <?xml version="1.0" encoding="UTF-8"?> + + (Hinweis: für einige Sprachen wird UTF-16 eine bessere Wahl sein.) + + Wenn Sie Ihre Dokumentation händisch schreiben, z.B. mit einem + Texteditor, müssen Sie diese Zeile selbst hinterlegen. Wenn Sie einen speziellen XML-Editor verwenden, + wird dies automatisch eingefügt, sobald Sie ein neues Dokument erstellen. + +
+ Dateipfade für verschiedene Dokumentensätze + + Dateien für das englische Benutzerdokumentations-set liegen im Verzeichnis manual/src/docs/firebirddocs. Nicht-englische Dokumente werden im sprachabhängigen Baum wie z.B. manual/src/docs/firebirddocs-fr, + manual/src/docs/firebirddocs-es, + etc. abgelegt. + + Seit Januar 2006 haben wir die Möglichkeit weitere Basis-Dokumentensätze anzulegen, das erste war + rlsnotes, der Satz für Release Notes. Die gleiche Logik finden wir auch + hier wieder: Englisches Zeug für die Release Notes liegt unter manual/src/docs/rlsnotes, französisches in + manual/src/docs/rlsnotes-fr, + und so weiter. + + Jeder dieser Verzeichnisbäume – firebirddocs, firebirddocs-es, firebirddocs-nl, rlsnotes, rlsnotes-fr, etc. – beinhaltet ein eigenes + set, mit einem Hauptdokument und eine beliebige Anzahl Dateien. +
+
+ +
+ Texte schreiben + + Wenn Sie Ihr DocBook-XML in einem Texteditor wie + Notepad, emacs oder + ConText bearbeiten, können Sie Zeilenumbrüche, Einrückungen und mehrere Leerzeichen + verwenden, wenn Sie möchten. Jedes Auftreten eines Leerraums (engl. + whitespace, eine Sequenz von einem oder mehreren + Leerzeichen, Tabs, + Zeilenvorschüben oder Steuerzeichen) + wird in ein einzelnes Leerzeichen in der Ausgabe umgewandelt. So wird aus: + + <section><title>Firebird Architectures</title><para>Now let's have a +look at Firebird's different architectures.</para><itemizedlist> +<listitem><para>First, there's the so-called <firstterm>Classic Server +</firstterm>.</para></listitem><listitem><para>Then there is <firstterm> +Superserver</firstterm> architecture.</para></listitem><listitem><para> +And finally, with the release of Firebird 1.5 we also have the +<firstterm>embedded server</firstterm>.</para></listitem></itemizedlist> +</section> + + diese Ausgabe: + + <section> + <title>Firebird Architectures</title> + <para>Now let's have a look at Firebird's different + architectures.</para> + <itemizedlist> + <listitem> + <para>First, there's the so-called + <firstterm>Classic Server</firstterm>.</para> + </listitem> + <listitem> + <para>Then there is <firstterm>Superserver</firstterm> + architecture.</para> + </listitem> + <listitem> + <para>And finally, with the release of Firebird 1.5 we also + have the <firstterm>embedded server</firstterm>.</para> + </listitem> + </itemizedlist> +</section> + + Nicht nötig zu sagen, dass die zweite Variante deutlich leichter + zu lesen und zu verstehen ist. Wenn Sie also Ihr XML mit der Hand schreiben sollten, + formatieren Sie den Text so, dass die Struktur so klar wie möglich ist. + + + Wenn Sie einen speziellen XML-Editor verwenden, beachten Sie bitte, dass + Enter möglicherweise automatisch das aktuelle para-Tag schließt und ein neues öffnet. Stellen Sie sicher, dass + Sie wissen, wie sich Ihr Editor in diesem Bezug verhält. Prüfen Sie außerdem wie sich der + Editor bei zu vielen Leerzeichen verhält. Manche nutzen spezielle Tricks um diese zu behalten. +
+
+ +
+ Häufig verwendete Elemente + + Dieser Abschnitt behandelt die am häufigsten verwendeten DocBook-Elemente. + Er beinhaltet viele Beispiele im DocBook XML-Format. Wenn Sie einen XML-Editor verwenden, + wird die Ausgabe vermutlich nichts mit diesen Beispielen zu tun haben. Öffnen Sie Ihre + Datei hingegen in einem Texteditor - oder wählen die reine Textansicht in Ihrem XML-Editor - + werden Sie den aktuellen XML-Code sehen. Sehen Sie auch die vorhandenen XML-Quellen + des manual Modul ein, um herauszufinden wie andere Autoren ihre Dokumente zusammenbauen + und Tags zuweisen. + + Lesen Sie bitte den Unterabschnitt über hierarchische Elementstrukturen, auch wenn Sie ein + professioneller DocBook-Schreiber sind, da es ein paar spezifische Projektvorgaben enthält. + Danach können Sie den Rest der DocBook-Unterabschnitte überspringen. + + Wenn Sie erstmalig mit DocBook arbeiten, seien Sie nicht von der Länge dieses Abschnitts + entmutigt. Mein Rat ist, dass Sie den Abschnitt über hierarchische Elemente + gründlich lesen und den Rest überfliegen. Es ist kein Problem, + wenn Sie nicht gleich alles verstehen. Das Verständnis kommt bei der Anwendung. + Haben Sie diesen Leitfaden nur zur Hand, wenn Sie ihr Dokument schreiben, und + schauen Sie immer mal wieder in die Elementabschnitte rein (so wie sie es gerade brauchen). + +
+ Hierarchische Elemente + + Die allgemeinste Hierarchie, startet mit: set – book – chapter – section – para. Ein Buch (book) besteht möglicherweise aus Artikeln (articles) anstatt aus Kapiteln (chapters). + + Der nächste Unterabschnitt wird einige Aspekte bezüglich der Dokumentstruktur + erklären. + +
+ Das <sgmltag class="attribute">id</sgmltag>-Attribut + + Sets, books, chapters, articles und Top-Level-Abschnitte sollten + immer ein id-Attribut besitzen. + Andere Elemente können ebenfalls eines haben. Die ID erlaubt es uns ein Element + von anderen Stellen des Dokuments zu referenzieren, sogar aus anderen Dokumenten + innerhalb des Satzes (set). IDs sind nicht sichtbar im gerenderten Dokument (mit Ausnahme + des HTML-Quelltextes), aber sie werden verwendet für die Namensvergabe der HTML-Dateien. + + Alle id-Attribute müssen + eindeutig innerhalb des Buchsatzes (bookset). Beachten Sie, dass die + verschiedenen Sprachversionen in je einem eigenen set liegen, wodurch es OK ist, die originalen + ids in der Übersetzung zu behalten. + + Innerhalb eines Buchs (book) oder Artikels (article), sollten die ids mit den gleichen kleingeschriebenen Wörtern beginnen, + z.B. usersguide, gefolgt von einem Trennzeichen, gefolgt von einem + oder mehreren kleingeschriebenen Wörtern. Beispiele hierfür sind + usersguide-intro und + usersguide-download-install. Dies ist keine DocBook-Voraussetzung, + sondern unsere eigene Konvention. +
+ +
+ Die <sgmltag class="attribute">lang</sgmltag>-Attribute + in nicht-englischen Dokumentensätzen + + Wenn Sie einen neuen Dokumentensatz erstellen, oder einen vorhandenen übersetzen, + müssen Sie das Sprachattribut lang + im Hauptelement verwenden: + + <set id="firebird-books-fr" lang="fr"> + + Hiermit wird sichergestellt, dass die korrekten Beschriftungen + für Hinwise, Warnung, etc. erstellt werden und dass die sprachabhängigen + Anführungszeichen verwendet werden. Es ist außerdem eine gute Praxis, diese + Attribute für die individuell gestalteten Dokumente zu verwenden, + wenn diese jemals außerhalb Ihres Sets erstellt werden. + + Für englische Dokumentensätze ist das lang-Attribut + optional. +
+ +
+ Titles + + set, book, chapter, article und section müssen immer ein + title-Attribut besitzen – entweder als direktes Kindelement oder + innerhalb eines xxxinfo-Elementes + (siehe unten). Es ist außerdem möglich diesen in beiden Elementen anzugeben, in diesem Fall jedoch + müssen die zwei title identisch sein, unabhängig davon, ob id ein Attribut oder title ein Element ist. Und auch unabhängig davon, ob title in der Ausgabe erscheinen wird. + + Wenn title zu lang ist, sollten Sie + ein titleabbrev-Element direkt dahinter hinzufügen. + Dieses enthält eine gekürzte Fassung des Titels. Der Hauptgrund hierfür ist, dass + jede erstellt HTML-Seite eine sogenannte Hierarchieleiste enthält. So eine Art + Sie befinden sich hier-Zeile am Beginn und Ende. + Diese Hierarchieleiste zeigt Ihnen jede Abstufung vom höchsten Element (dem + set) bis runter zu Ihrer aktuellen Seite. + Da die Namen auch anklickbar sind, gibt Ihnen die Leiste jederzeit + bekannt, wo sich sich gerade innherhalb der Hierarchie befinden. Außerdem + ist die Navigation zu höheren Elemente hierdurch kinderleicht. Am besten sieht die Leiste + aus, wenn die Namen von der Größe her in eine Zeile passen, gleiches gilt + für titleabbrev, welches nur angezeigt wird, wenn es auch + vorhanden ist. Ist dies nicht der Fall wird + title + verwendet. Das gleiche Schema setzt sich für die Lesezeichen (die Navigation im + linken Bereich) im PDF-Dokument fort. +
+ +
+ Info-Elemente + + Wenn Sie ein Buch oder Artikel verfassen, müssen Sie ein bookinfo- oder articleinfo-Element am the Start definieren. + Innerhalb dieser können Sie Autoreninformationen und mehr erstellen. + Weitere xxxinfo-Elemente + existieren, aber Sie werden diese selten benötigen. + + <book id='usersguide' lang='en'> + <bookinfo> + <title>Firebird Users Guide</title> + <author> + <firstname>William</firstname> + <surname>Shakespeare</surname> + </author> + <edition>25 January 2006 – Document version 1.2</edition> + </bookinfo> + ... + ... +</book> + + Wenn der Autor einer Firma oder anderen Organisation oder Gruppe angehört, + auf die Sie verweisen möchten, nutzen Sie + corpauthor anstelle von author: + + <corpauthor>IBPhoenix Editors</corpauthor> + + Gibt es mehrere Autoren und Sie möchten diese einzeln aufführen, + erstellen Sie ein author (oder + corpauthor)-Element für jeden von ihnen und + fassen Sie diese in einem authorgroup-Element zusammen – alles innerhalb des + xxxinfo-Elements. +
+ +
+ Abschnittsarten + + Abschnittselemente unterscheiden sich etwas vom Rest in zwei Arten: + + + + Erstens, das section-Element + wie zuvor beschrieben. Es kann rekursiv genutzt werden, beispielsweise könnten + Sie ein section innerhalb eines anderen + section wiederum innerhalb eines anderen section... verschachteln. Dies hat den Vorteil, dass Sie den + gesamten Unterbaum hoch und runter wandern können, ohne die Tags zu ändern. + + + + Zweitens gibt es den sect1, + sect2 ... sect5-Bereich. Diese Elemente werden + üblicherweise verschachtelt, mit sect1 am + Anfang, sect2 innerhalb von sect1 etc. Sie können sect3 nicht direkt in sect1 einbinden. Das ist weniger flexibel als + section und in der Praxis auch + nervenaufreibend. Nichtsdestotrotz trifft die gleiche Rigidität auf die Elemente + set, book und chapter zu und wir können auch damit leben. + + + + + In früheren Versionen diese Leitfadens, wurde die sectN-Methode + bevorzugt. Aufgrund von Verbesserungen der Stylesheets ist die jedoch + nicht mehr länger der Fall. Nutzen Sie was immer Sie möchten. + +
+ +
+ Anhänge + + Sie können einen oder mehrere appendix-Elemente nach dem letzten Kapitel eines Buches (book) + oder nach dem letzten Abschnitt (section) eines Artikels (article) einfügen. Anhänge können + alles beinhalten, was auch section beinhalten darf, somit auch weitere Abschnitte. +
+ +
+ Beispielstruktur + + Das folgende Beispiel soll Ihnen einen Anhaltspunkt geben, wie Ihr Dokument aufgebaut sein sollte: + + <?xml version="1.0" encoding="UTF-8"?> + +<book id="usersguide"> + + <bookinfo> + <title>Firebird Users Guide</title> + <author> + <firstname>William</firstname> + <surname>Shakespeare</surname> + </author> + <edition>25 January 2006 – Document version 1.2</edition> + </bookinfo> + + <chapter id="usersguide-intro"> + <title>Introduction</title> + <para>Hello! This is the introductory text to the Firebird + Users Guide.</para> + </chapter> + + <chapter id="usersguide-download-install"> + <title>Downloading and installing Firebird</title> + <para>In this chapter we'll demonstrate how to download and + install Firebird.</para> + <section id="usersguide-download"> + <title>Downloading Firebird</title> + <para>To download Firebird from the Internet, first go to the + following URL: etc. etc. etc.</para> + ...more paragraphs, possibly subsections... + </section> + <section id="usersguide-install"> + <title>Installing Firebird</title> + <para>Installing Firebird on your system goes like this: + etc. etc.</para> + ...more paragraphs, possibly subsections... + </section> + </chapter> + + ...more chapters... + + <appendix id="usersguide-dochist"> + <title>Document history</title> + ...to be discussed later! + + <appendix id="usersguide-license"> + <title>License notice</title> + ...to be discussed later! +</book> +
+ +
+ Zu beachtende Punkte + + + + Beachten Sie zunächst wieder, dass Attribute in Anführungszeichen stehen. (Wenn + Sie diese mit einem Attributeditor einsetzen, werden diese vom Programm selbst gesetzt.) + + + + Wie Sie im Beispiel sehen, können chapters und sections direkt mit einem oder mehreren + para-Elementen starten. + Sobald Sie aber Abschnitte (section) in einem Kapitel einbinden, oder Unterabschnitte + in einem Abschnitt, können Sie keine weiteren para-Elemente + danach verwenden - nur noch innerhalb dieser. Gute DocBook-XML-Editoren werden Sie dies + auch nicht tun lassen. Wenn Sie Ihr DocBook-XML jedoch händisch erstellen, sollten Sie hierauf achten. + + + + Wenn Sie einen XML-Editor einsetzen, werden Sie vermutlich selten + para-Elemente selbst erstellen. + Füge ich beispielsweise ein chapter oder ein section im XMLMind XML + Editor ein, wird automatisch ein – zunächst leerer – para erstellt. Und wenn ich dann Text im Absatz eingebe + und ENTER drücke, wird dieser Absatz automatisch mit einem para geschloseen und der nächste wird erstellt. + + + + Überspringen Sie den Rest des Elemente-Unterabschnitts + , sollten Sie schon alles über DocBook-Elemente wissen. +
+
+ +
+ Listen + + DocBook bietet verschiedene Listenelemente. Dies sind die gebräuchlichsten: + + + + itemizedlist + + + Ein itemizedlist wird verwendet, um eine ungeordnete Aufzählungen + zu erstellen: + + <itemizedlist spacing="compact"> + <listitem><para>Oranges are juicy</para></listitem> + <listitem><para>Apples are supposed to be healthy</para></listitem> + <listitem><para>Most people find lemons way too sour</para> + </listitem> +</itemizedlist> + + Listeneinträgen werden allgemein mit Punkten vorangestellt angezeigt: + + + + Oranges are juicy + + + + Apples are supposed to be healthy + + + + Most people find lemons way too sour + + + + Wenn Sie das spacing-Attribut weglassen, wird der Standard + normal genutzt, was bedeutet, das vertikale Leerräume + (typischerweise eine Zeilenhöhe) zwischen den Listeneinträgen eingefügt wird. + + + + + orderedlist + + + Ein orderedlist erzeugt eine geordnete Aufzählung, auch Nummerierung genannt: + + <orderedlist spacing="compact" numeration="loweralpha"> + <listitem><para>Sumerians 3300 BC – 1900 BC</para></listitem> + <listitem><para>Assyrian Empire 1350 BC – 612 BC</para></listitem> + <listitem><para>Persian Empire 6th century BC – 330 BC</para> + </listitem> +</orderedlist> + + Standardmäßig werden Zahlen (1, 2, 3, ...) verwendet, die vor den Listeneinträgen erscheinen, aber + diese können Sie mit dem Attribut numeration ersetzen lassen. Ausgabe: + + + + Sumerians 3300 BC – 1900 BC + + + + Assyrian Empire 1350 BC – 612 BC + + + + Persian Empire 6th century BC – 330 BC + + + + + + + procedure + + + Ein procedure wird häufig wie ein + orderedlist dargestellt, ist semantisch + aber etwas anderes: ein procedure beschreibt eine bestimmte Schrittfolge: + + <procedure> + <step><para>Pick the lock</para></step> + <step><para>Rob the house</para></step> + <step><para>Get arrested</para></step> +</orderedlist> + + So sieht die Ausgabe aus: + + + + Pick the lock + + + + Rob the house + + + + Get arrested + + + + Innerhalb eines step, können Sie einen Unterschritt + substeps erstellen, welcher wiederum weitere + step-Elemente enthalten kann. + + + + + variablelist + + + Ein variablelist besteht aus Einträgen der Art + varlistentry, welche jeweils ein + term beinhalten, gefolgt von einem + listitem: + + <variablelist> + <varlistentry> + <term>Tag</term> + <listitem> + <para>A piece of text enclosed in angle brackets</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Element</term> + <listitem> + <para>A start tag, a matching end tag, and everything in + between</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Content of an element</term> + <listitem> + <para>Everything between the matching tags</para> + </listitem> + </varlistentry> +</variablelist> + + Die Liste, die Sie gerade lesen, besteht aus verschiedenen Listentypen und ist selbst ein variablelist mit den Elementnamen + (itemizedlist, orderedlist, etc.) als Einträge. + Der nächste Abschnitt – Links – + besteht ebenfalls aus einem Einleitungssatz gefolgt von einem variablelist. + + + +
+ + + +
+ Programm-Listings, Bildschirmausgaben, literales Layout und Beispiele + + + + programlisting (Programm-Listings) + + + Wenn Sie Code-Fragmente in Ihrem Dokument unterbringen wollen, + packen Sie diese in ein + programlisting-Element. + Alles, was Sie innerhalb eines Programm-Listings schreiben, + wird wörtlich, inklusive Zeilenumbrüche, Leerzeichen, etc., in die Ausgabe übernommen. + Des weiteren wird eine Schriftart mit fester Zeichenbreite verwendet. Der Begriff + Programm-Listing ist im weiteren Sinne zu verstehen: + Sie sollten das Element auch für SQL- und DocBook XML-Anweisungen und -Beispiele nutzen. + Dieser Leitfaden - und insbesondere der Abschnitt über Elemente, welchen Sie gerade lesen - + ist zugemüllt mit programlistings, also wissen Sie bereits wie diese aussehen: + + Programlistings are rendered like this. + + + In Programm-Listings sollten Sie die Zeilenweite auf 70 Zeichen beschränken. + Andernfalls wird der Text in PDFs rechts über den Rand laufen. Das gleiche gilt + für andere Elemente wie screen, literallayout, etc. + + + + + + screen (Bildschirmausgaben) + + + Verwenden Sie ein Element screen, + um zu zeigen, was ein Anwender sieht oder sehen sollte, wenn sich im + Textmodus oder Terminalmodus befindet. + Hier wird das Layout ebenfalls durch eine Festbreitenschrift dargestellt, aber die + Semantic ist eine andere. In der Ausgabe unterscheided sie sich nicht vom Programm-Listing. + Hier ein kurzes Beispiel, was passiert, wenn Sie versuchen ein nichtexistierendes Ziel im manual-Baum + zu erstellen: + + <screen> +D:\Firebird\manual_incl_howto\src\build>build ugh +java version "1.4.2_01" +Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06) +Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode) + +Buildfile: build.xml + +BUILD FAILED +Target `ugh' does not exist in this project. +</screen> + + Und so sieht die Ausgabe aus: + + D:\Firebird\manual_incl_howto\src\build>build ugh +java version "1.4.2_01" +Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06) +Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode) + +Buildfile: build.xml + +BUILD FAILED +Target `ugh' does not exist in this project. + + + + + literallayout (wörtliches Layout) + + + literallayout, wie + screen und programlisting hält Ihr Layout intakt und ändert + die Schriftart normalerweise nicht - es sei denn Sie setzen das Attribut + class auf + monospaced. Es ist ein allgemeineres Element, + als die zwei vorhergehenden. Seinem Inhalt wird keine Bedeutung zugemessen: Sie können + irgendeine Art Text hier platzieren, wenn Sie das Layout erhalten wollen. + + Beispiel (Quelltext): + + <literallayout> +The Sick Rose + +Oh Rose, thou art sick! +The invisible worm +That flies in the night, +In the howling storm, + +Has found out thy bed +Of crimson joy, +And his dark secret love +Doth thy life destroy. + + — William Blake +</literallayout> + + Beispiel Ausgabe: + + The Sick Rose + +Oh Rose, thou art sick! +The invisible worm +That flies in the night, +In the howling storm, + +Has found out thy bed +Of crimson joy, +And his dark secret love +Doth thy life destroy. + + — William Blake + + + + + example (Beispiel) + + + Ein example stellt ein formales + Beispiel samt Titel dar. Es wird normalerweise mit einem id-Attribut verwendet, womit + es an anderen Dokumentstellen referenziert werden kann. Ein Beispielverzeichnis + wird automatisch erstellt, wenn das Dokument gerendert wird. Sie werden häufig + programlistings ein einem example finden, aber es kann auch + screens, paras, lists, etc. enthalten. + + Hier ist ein Beispiel für die Verwendung von example: + + <example id="docwritehowto-sql-example"> + <title>Ein SQL-Beispiel</title> + <para>Mit diesem Befehl können Sie alle Datensätze der Tabelle COUNTRY auflisten:</para> + <programlisting>SELECT * FROM COUNTRY;</programlisting> +</example> + + In der Ausgabe sieht dies so aus: + +
+ + Ein SQL-Beispiel + + Mit diesem Befehl können Sie alle Datensätze der Tabelle COUNTRY auflisten: + + SELECT * FROM COUNTRY; + +
+ + Wenn Sie ein Beispiel ohne zwingenden Titel erstellen möchten, + verwenden Sie + informalexample. Informelle Beispiele + sind nicht Bestandteil des Beispielverzeichnisses. + + + +
+ +
+ Tabellen + + Wenn Sie schonmal eine Tabelle in HTML erstellt haben, + werden Sie auch keine großen Schwierigkeiten bei der Erstellung von Tabellen + mittels DocBook haben. Es gibt ein paar Unterschiede, und DocBook-Tabellen sind + weit mächtiger. + + Ein Element table besteht aus einem title und einer oder mehreren tgroups – übrlicherweise eine. Das tgroup-Element besitzt ein notwendiges Attribut: + cols. Hierfür sind die Anzahl der Spalten innerhalb des tgroup anzugeben. Innerhalb eines tgroup können Sie die Elemente thead, tfoot und tbody platzieren. Jedes dieser Elemente hat ein oder mehrere Zeilen (engl. + rows), welche wiederum so viele Zellen (engl. + entrys) beinhalten, wie Sie zuvor im Attribut + cols angegeben haben. (Sie können Zellen verbinden, aber das + wird hier nicht behandelt.) + + Soviel zu Basisstruktur. Jetzt werden wir Ihnen ein Beispiel zeigen; + Erst als DocBook XML-Quelltext, und dann die resultierende Tabelle in der gerenderten + Ausgabe. Machen Sie sich keine Gedanken über die colspecs; Dies sind keine Pflicht-Unterlemente. Sie sind nur zum Feintuning da. + + <table id="docwritehowto–table–dboftheyear"> + <title>LinuxQuestions.org poll: Database of the year 2003</title> + + <tgroup cols="3"> + <colspec align="left" colname="col–dbname" colwidth="2*"/> + <colspec align="right" colname="col–votes" colwidth="1*"/> + <colspec align="right" colname="col–perc" colwidth="1*"/> + + <thead> + <row> + <entry align="center">Database</entry> + <entry align="center">Votes</entry> + <entry align="center">Percentage</entry> + </row> + </thead> + + <tfoot> + <row> + <entry>Total</entry> + <entry>1111</entry> + <entry>99.99</entry> + </row> + </tfoot> + + <tbody> + <row> + <entry>MySQL</entry> + <entry>405</entry> + <entry>36.45</entry> + </row> + <row> + <entry>Firebird</entry> + <entry>403</entry> + <entry>36.27</entry> + </row> + + ... 5 more rows not shown here .... + + </tbody> + </tgroup> +</table> + + Und hier ist die resultierende Tabelle: + + + LinuxQuestions.org poll: Database of the year 2003 + + + + + + + + + + + Database + + Votes + + Percentage + + + + + + Total + + 1111 + + 99.99 + + + + + + MySQL + + 405 + + 36.45 + + + + Firebird + + 403 + + 36.27 + + + + Postgres + + 269 + + 24.21 + + + + Oracle + + 25 + + 2.25 + + + + Berkeley DB + + 4 + + 0.36 + + + + Sybase + + 3 + + 0.27 + + + + DB2 + + 2 + + 0.18 + + + +
+ + Nebenbei ist dies ein reeller Auszug von + LinuxQuestions.org. Wie Sie sehen können, fehlen lediglich drei Leute, die zum Sieg für + Firebird hätten stimmen müssen. Wenn Sie diese drei Personen kennen, kontaktieren Sie bitte + unseren Chef-Inquisitor. Er würde gern ein kleines, + ähm... Gespräch mit ihnen führen :–) + + Tabellen werden automatisch inidziert. Ein informaltable hat die gleiche Struktur wie ein + table, benötigt aber keinen Titel und wird nicht + im Tabellenverzeichnis geführt. Wenn Sie Tabellen verschachteln wollen, nutzen Sie entweder + table/informaltable innerhalb eines + entry oder ein entrytbl anstelle eines + entry. + + Tabellen haben deutlich mehr Eigenschaften als hier gezeigt, + aber dies sei nun an Ihnen herauszufinden. + +
+ HTML-Tabellen + + DocBook in den Versionenen 4.3 und höher erlaubt es Ihnen, Tabellen + im HTML-Stil zu erstellen. Somit ist die Verwendung von trs anstelle von + rows und td/th + anstelle von entry erlaubt. Warum sollten Sie das tun? + Es gibt zwei Situationen, in denen die Verwendung der HTML-Tabellen vorteilhaft ist: + + + + Sie haben bereits eine vorhandene HTML-Tabelle und möchten nicht die Zeit investieren, diese + zu konvertieren; + + + + Sie möchten verschiedene Hintergrundfarben in der Tabelle verwenden. Dies kann zwar + auch in der DocBook-Tabelle getan werden, aber nur mit Verarbeitungsanweisungen, also den + processing instructions – eine für jedes Ziel jedes Elementes, das eine + eigene Farbe erhalten soll. In einer HTML-Tabelle können Sie das Attribut bgcolor des Kindelements verwenden. + + + + Eine HTML-Tabelle darf keine tgroups enthalten; verwenden Sie trs entweder direkt in der Tabelle oder im Tabellenkopf + thead / Tabellenkörper tfoot / Tabellenfuß tbody. Diese sind direkte Kindelemente der Tabelle selbst. + Außerdem hat die HTML-Tabelle das Element caption + anstelle von title. (Ein informaltable-Element hat weder caption noch title.) + + Hier ist der Quelltext einer HTML-Tabelle: + + <table bgcolor="blue" border="1"> + <caption align="bottom">An HTML-style table</caption> + + <tr bgcolor="#FFE080"> + <th>First column</th> + <th bgcolor="#FFFF00">Second column</th> + </tr> + <tr align="center"> + <td bgcolor="orange" colspan="2">Table cell spanning two + columns</td> + </tr> + <tr> + <td bgcolor="#00FFC0">Yes, here I am</td> + <td align="right" bgcolor="#E0E0E0" rowspan="2" valign="bottom">And + there I go!</td> + </tr> + <tr> + <td bgcolor="#FFA0FF">Another row...</td> + </tr> +</table> + + Und hier ist das Ergebnis: + + + + + + + + + + + + + + + + + + + + + + + +
An HTML-style table
First columnSecond column
Table cell spanning two + columns
Yes, here I amAnd there I go!
Another row...
+ + Nicht alle HTML-Tabellenelemente und -attribute werden von den Stylesheets unterstützt. + So werden beispielsweise Eigenschaften, die in col und colgroup definiert wurden, nicht berücksichtigt. + Definieren Sie diese stattdessen in td-/th-Elementen - oder erweitern Sie die Stylesheets! + + + + In XMLMind können Sie eine HTML-Tabelle über das Menü in der Werkzeugleiste erstellen. + Über den Bearbeiten-Bereich können Sie lediglich DocBook-Tabellen erstellen. + +
+ +
+ PDF-Ausgabe großer Tabellen + + DocBook tables gehören zu den sogenannten + formalen Elementen (engl. formal elements). Formale Elemente + werden automatisch in Verzeichnisse aufgenommen (Tabellenverzeichnis, Abbildungsverzeichnis, etc.); + wenn ein formales Element kein Attribut id besitzt, weist ihm das Stylesheet eines zu. + Die Vorlage, die die XSL-FO-Ausgabe generiert (den Zwischenschritt hin zum PDF), + weist jedem formalen Objekt auch das Attribut keep-together.within-page="always" zu, + was verhindert, dass Seitenumbrüche innerhalb eines Objekts stattfinden. + Dies ist normalerweise gewünscht, aber was passiert, wenn das Objekt nicht + auf eine Seite passt? Bis vor kurzem nutzten wir Apache FOP 0.20.5 um die + XSL-FO-Ausgabe zu erstellen. Dieser Prozessor ignorierte das keep-together-Attribut, wenn das Objekt zu groß war. + Aber die derzeitige Version (0.93 oder höher) "drückt" diese Eigenschaft + immer durch. Das Ergebnis ist, dass das Obejekt in diesem + Falle abgeschnitten (oder in irgendeiner anderen Art passend gemacht) wird, damit es + auf die Seite passt. Dies ist ein Feature, kein Bug. Somit gibt es auch keinen + Grund sich hierüber zu beschweren. + + Es gibt zwei Workarounds, sollte eine Tabelle zu groß für eine Seite sein: + + + + Wenn die Tabelle keinen Titel benötigt und es Ihnen nichts ausmacht, dass + diese nicht im Tabellenverzeichnis aufgelistet wird, verwenden Sie stattdessen + informaltable. + + + + Fügen Sie eine Verarbeitungsanweisung (processing instruction) am Anfang der Tabell ein: + + <table frame="all" id="ufb-about-tbl-features"> + <?dbfo keep-together='auto'?> + <title>Summary of features</title> + + In XMLMind wird dies folgendermaßen umgesetzt: + + + + Setzen Sie den Cursor in das Titelelement. + + + + Wählen Sie Edit -> Processing Instruction -> + Insert Processing Instruction Before aus dem Menü. + Eine grüne Zeile erscheint oberhalb des Titels. + + + + Geben Sie keep-together='auto' in diese Zeile ein. + + + + Lassen Sie den Cursor auf der grünen Zeile, wählen Sie dann + Edit -> Processing Instruction -> Change + Processing Instruction Target aus dem Menü. Nun erscheint eine Dialog-Box. + + + + Ändern Sie target in + dbfo und klicken Sie auf OK. + + + + Natürlich können Sie das Gleiche für kleinere Tabellen tun, + wenn Sie dort Zeilenumbrüche bevorzugen. + Die gegenteilige Anweisung dbfo keep-together='always' wird Seitenumbrüche + in informaltables verhindern. + Stellen Sie sicher, dass die Elemente auf eine Seite passen, bevor Sie dies verwenden! + + +
+
+ +
+ Bilder + + Um Bilder einzubinden, verwenden Sie mediaobject welches ein imageobject beinhaltet, das wiederum ein imagedata beinhaltet: + + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/services.png" + format="PNG"/> + </imageobject> +</mediaobject> + + Vielleicht wundern Sie sich, dass 3 verschachtelte Elemente benötigt werden, + um ein simples Bild einzubinden. Hierfür gibt es einen guten Grund, den werde ich + Ihnen aber nicht erzählen ;-) - der ist für uns nicht von Belang. Wir müssen nur wissen, dass es + so gemacht wird. + + Ungeachtet des Bildverzeichnisses, welches relativ zur DocBook-Quelle steht, + sollte + fileref + immer in der Form + images/filename.ext angegeben werden. + Die geschieht, weil die HTML- und die FO-Ausgabe die Bilddateien aus ihren Quellverzeichnissen + zu einem Unterverzeichnis namens + images im Ausgabepfad kopieren werden. + (Die FO-Ausgabe ist eine Zwischenform. Sobald dies zum PDF gewandelt wurde, ist das Bild in der + Datei selbst enthalten.) + + Wenn die Dateireferenz nicht korrekt aus Sicht der + Dateiquellen ist, werden Sie das Bild in XMLMind auch nicht sehen. + Sollte Sie das stören, erstellen Sie einen Symlink auf den Bildordner (Linux) oder + kopieren Sie diesen in das gleiche Verzeichnis wie die Quelldatei (Windows). + Eine Verknüpfung scheint unter Windows nicht zu funktionieren. Nutzen Sie die Kopien nur in + Ihrer lokalen Kopie - erstellen Sie keinen Commit mit doppelten Bilddaten ins CVS! + + Ein mediaobject wird als separater Block formatiert. + Wenn Sie das Bild mit Text eibinden wollen, nutzen Sie stattdessen + inlinemediaobject; die verschachtelten Element + bleiben wie sie sind. + + + Hinweis für Übersetzer + + Übersetzer: Alle Bilder, die Sie nicht für Ihre Sprache überarbeiten oder ersetzen, + sollten nicht in Ihren sprachabhängigen Dokumentensatz (set) übernommen werden. Seit + Januar 2006 sehen die build tools erst in Ihrem Sprachverzeichnis + (z.B. manual/src/docs/firebirddocs-fr/images), + und danach in manual/src/docs/firebirddocs/images. Somit wird kein + CVS-Speicher verschwendet, wenn Sie die Originalbilder verwenden. + + Das gleiche Verhalten ergibt sich für die anderen Sätze: + Wenn ein Bild von, sagen wir mal spanischen Release Notes, referenziert wird, und dieses nicht + in + rlsnotes-es/images vorliegt, wird dieses aus + rlsnotes/images verwendet. Es funktioniert nicht + sprach-übergreifend. + +
+ +
+ Hinweise + + DocBook besitzt mehrere Tags, um einen Textblock als Hinweis, Warnung, Tipp, etc. zu + markieren. In der Ausgabe werden solche Blöcke eingerückt und mit einem Symbol oder Wort + zur Kennzeichnung ihres Zwecks markiert. Die verwendbaren Tags in alphabetischer Reihenfolge: + +
+ caution, important, note, tip, und warning +
+ + Ich werde Ihnen einen Tipp (tip) als + Beispiel zeigen; Die anderen werden genauso verwendet: + + <tip> + <para>If you insert a caution, important, note, tip, or warning + element in your text, don't start it with the word caution, + important, note, tip, or warning, because these words are usually + automatically generated by the rendering engine.</para> +</tip> + + Und dies ist die Ausgabe: + + + If you insert a caution, + important, note, tip, or warning element in your text, don't start + it with the word caution, + important, note, + tip, or warning, because these + words are usually automatically generated by the rendering + engine. + + + Sie haben vielliecht bemerkt, dass die Wörter caution, + important etc. sich vom Aussehen des restlichen Tipp-Textes + unterscheiden. Wie kommt das? Um Ihnen die Wahrheit zu sagen, habe ich diese mit + speziellen Tags umschlossen (erst mit sgmltags, zweitens mit literals) damit sie nun so aussehen wie sie hier erscheinen. + Aber das ließ den XML-Quelltext sehr unsauber aussehen. Deshalb entschied ich mich + diese Tags aus den Beispielquellen zu entfernen. + + Optional können Sie den Hinweisen ein Element title mitgeben. Wenn Sie dies nicht tun, + wird ein Standardkopf (in Dokumentsprache) für die Ausgabe erstellt. + + Möchten Sie einen Textblock erstellen ohne diesen als Tipp oder anderes zu kennzeichnen, + nutzen Sie blockquote. +
+ +
+ Absatzköpfe + + Wenn Sie einen Absatzkopf oder Titel ohne Unterabschnitt erstellen möchten, + gibt es ein paar Möglichkeiten. + + + + bridgehead + + + Ein bridgehead ist ein flussfreier Titel + zwischen Absätzen, der keinem Anfang eines Kapitels oder Abschnitts zugeordnet ist. + Das Attribut renderas gibt an, wie es gerendert wird. + + <para>You may remember that Mr. Hardy started with this firm as + elevator boy and with grim determination worked his way up to + the top. And after the wedding today he becomes General Manager + of this vast organisation.</para> + +<bridgehead renderas="sect5">Mr. Laurel's comments</bridgehead> + +<para>We also spoke to his lifetime friend and companion Mr. Laurel. + Mr. Laurel says that after viewing the situation from all sides, + he is thoroughly reconciled to the fact that the moving picture + industry is still in its infancy. Mr. Laurel also states that + technology, whilst it may appear to be the center of all—</para> + + Der oben angegebene Quelltext erscheint so in der Ausgabe: + +
+ You may remember that Mr. Hardy started with this firm as + elevator boy and with grim determination worked his way up to + the top. And after the wedding today he becomes General Manager + of this vast organisation. + + Mr. Laurel's comments + + We also spoke to his lifetime friend and companion Mr. + Laurel. Mr. Laurel says that after viewing the situation from + all sides, he is thoroughly reconciled to the fact that the + moving picture industry is still in its infancy. Mr. Laurel also + states that technology, whilst it may appear to be the center of + all— +
+ + Sie können frei wählen, welchen Level Sie für renderas nutzen wollen, aber logischerweise + wird dies meist die derzeitige Ebene plus (mindestens) eins sein. + + + + + formalpara + + + Ein formalpara ist ein Absatz mit Titel. + Unsere Stylesheets rendern den Titel als mitlaufenden Kopf. + + <formalpara> + <title>Motherly love:</title> + <para>This is the love your mother has for you, not to be + confused with brotherly or otherly love.</para> +</formalpara> + + In der Ausgabe erscheint damit: + +
+ + Motherly love: + + This is the love your mother has for you, not to be + confused with brotherly or otherly love. + +
+ + Eine Abgrenzung wird zum Titel hinzugefügt, sofern es nicht bereits auf ein Satzzeichen (Doppelpunkt) endet. + + + +
+ +
+ Verschiedene inline-Elemente + + Zum Abschluss dieses Abschnitts zu DocBook-Elementen, + werde ich noch eine Kurzbeschreibung zu einigen Inline-Elementen (inline elements) geben. + Sie heißen inline, da sie den Fluss des Textes nicht beeinflussen. + Wenn ich zum Beispiel das Element emphasis benutze: + + Don't <emphasis>ever</emphasis> call me fat again! + + ist das Ergebnis: + +
+ Don't ever call me fat again! +
+ + Das Wort ever wird betont, aber es behält seinen Platz + im Satz. Wir haben bereits einige Inline-Elemente kennengelernt: + die verschiedenen Linkarten. Andere Elemente - wie table, warning, blockquote und programlisting – werden immer als Block dargestellt, abgesetzt + vom umlaufenden Text (selbst wenn Sie diese als + inline in Ihrem XML-Quelltext setzen). Nicht überraschend ist somit, + dass diese Block-Elemente (block elements) genannt werden. Block-Elemente beinhalten + häufig Inline-Elemente; andersherum ist es nicht möglich. + + OK, starten wir mit diesen Inline-Elementen. + Ich werde Beispiele - jeweils mit XML-Quelltext und als gerenderte Ausgabe - für die meisten + zeigen: + + + + filename – command – application – envar + + + Verwenden Sie das Tag filename um einen Dateinamen + im weitesten Sinne zu markieren. Optionale Attribute können außerdem anzeigen, ob es sich hierbei + um eine Headerdatei, ein Verzeichnis, etc. handelt. + + Place your doc in the <filename +class="directory">src/docs/firebirddocs</filename> subdirectory. + + Die Ausgabe: + +
+ Place your doc in the src/docs/firebirddocs + subdirectory. +
+ + command und application kennzeichnen beide ausführbare Programme. + command wird üblicherweise für kleinere Programme und + interne Befehle verwendet; sein Inhalt sollte der exakt einzugebende Befehl sein; application wird grundsätzlich für größere Programme verwendet. + Der Name der ausführbaren Datei wird nicht benötigt. Beide können auf das gleiche Programm verweisen: + + Type <command>netscape&amp;</command> in a terminal window to start +<application>Netscape Navigator</application>. + + Dies ist die Ausgabe: + +
+ Type netscape& in a terminal window + to start Netscape Navigator. +
+ + envar kennzeichnet eine Umgebungsvariable. + + + + + subscript – superscript + + + Die zwei Elemente im Einsatz: + + After inventing the formula e = mc<superscript>2</superscript>, I +really felt like a glass of liquid H<subscript>2</subscript>O ! + + Ausgabe: After inventing the formula e = + mc2, I really felt like a glass of + liquid H2O ! + + + + + varname – constant – database + + + Die Verwendung von varname und + constant sollte offensichtlich sein. Das Tag + database kann für Datenbankobjekte verwendet werden, muss aber nicht: + + The <database class="table">COUNTRY</database> table has two fields: +<database class="field">COUNTRY</database> and +<database class="field">CURRENCY</database>. + + Ausgabe: The COUNTRY table has two fields: COUNTRY and CURRENCY. + + + + + function – parameter – returnvalue + + + Diese drei sprechen für sich selbst, glaube ich. + + The <function>log</function> function takes parameters +<parameter>a</parameter> and <parameter>b</parameter>. + + Ausgabe: The log + function takes parameters a und + b. + + + + + prompt – userinput – computeroutput + + + prompt wird für eine Zeichenkette verwendet, die anzeigt, + dass der Benutzer eine Eingabe tätigen soll; userinput verweist auf den eingegebenen Text (nicht zwangsweise + in der Befehlszeile!); computeroutput ist der Text, der vom Computer ausgegeben wurde: + + Type <userinput>guest</userinput> at the <prompt>login:</prompt> +prompt and the server will greet you with a <computeroutput>Welcome, +guest user</computeroutput>. + + Ausgabe: Type + guest at the login: prompt + and the server will greet you with a Welcome, + guest user. + + + + + keycap + + + Der Text einer Taste, oder allgemeiner: + + Hit the <keycap>Del</keycap> key to erase the message, or +<keycap>SPACE</keycap> to move on. + + Ausgabe: Hit the Del + key to erase the message, or SPACE to move + on. + + + + + sgmltag + + + Dieses Element wird innerhalb dieses Leitfadens ausführlich genutzt: + Es markiert + marks SGML und XML-Tags, Elemente, + Attribute, Einträge, etc.: + + If it concerns a directory, set the +<sgmltag class="attribute">class</sgmltag> attribute of the +<sgmltag class="element">filename</sgmltag> element to +<sgmltag class="attvalue">directory</sgmltag>. + + Ausgabe: If it concerns a directory, set + the class attribute of the + filename element to directory. + + Andere mögliche Werte für sgmltag.class sind: starttag, endtag, emptytag, und genentity (für einen Eintrag). + + + + + emphasis – citetitle – firstterm + + + Verwenden Sie emphasis um Wörter zu betonen, + citetitle für Buchtitel, etc., und + firstterm + wenn Sie Ihren Lesern ein neues Wort oder Konzept vorstellen: + + We use <firstterm>DocBook XML</firstterm> for our Firebird +documentation. A short introduction follows; +<emphasis>please</emphasis> read it carefully! If you want to know +more about the subject, buy <citetitle>DocBook – The Definitive +Guide</citetitle>. + + Ausgabe: We use DocBook + XML for our Firebird documentation. A short + introduction follows; please read it + carefully! If you want to know more about the subject, buy + DocBook – The Definitive Guide. + + + + + quote – literal + + + Verwenden Sie quote für einen + Inline-Bereich, der in Anführungszeichen steht (im Gegensatz zu blockquote). Anführungszeichen werden automatisch + eingefügt. Die Nutzung von quote anstelle der Eingabe von Anführungszeichen durch Sie selbst (was + natürlich auch möglich ist), hat den Vorteil, dass wir die Art der Anführungszeichen jederzeit + durch unsere Stylesheets anpassen können, wenn wir wollen. Außerdem unterscheiden sich + die Anführungszeichen von Sprache zu Sprache: + + <para>An <quote lang="en">English quote</quote> + and a <quote lang="fr">French quote</quote>.</para> + + Ausgabe: An English + quote and a French quote. + + Bitte beachten Sie, dass Sie das Attribut lang nicht zusammen mit quotes innerhalb Ihres eigenen Dokuments verwenden. + Ihr Wurzelelements lang-Attribut wird + sicherstellen, dass das korrekte Anführungszeichen verwendet wird. + Wenn jemand Ihr Dokument übersetzt - und das Wurzel-lang-Attribut ändert – wird es mit den Anführungszeichen der + Zielsprache gerendert. Natürlich hatte ich dieses Attribut hier zu verwenden, um die Unterschiede zu + zeigen. + + Ein literal ist ein Wort + oder Textfragment, dass literal (buchstäblich) wiedergegeben wird. Es ist ein allgemeines Element, + häufig verwendet, um Wörter typografisch auszuweisen: + + At all costs avoid using the word <literal>humongous</literal> in +your documentation. + + Ausgabe: At all costs avoid using the + word humongous in your documentation. + + + + + Sollten Sie diese Elemente wann immer möglich verwenden? + Nunja, wenn Sie es tun, werden Sie Ihr Dokument sicherlich reichhaltiger machen; Sie machen es z.B. leichter, + nach Dateinamen zu scannen oder ein Verzeichnis aller genutzten Anwendungen zu erstellen. + Auf der anderen Seite gibt es so viele dieser semantischen Elemente (tatsächlich haben + wir nur einige hier besprochen), dass Sie die Segel streichen werden, wenn + Sie alle anwenden wollten. Das ist nicht unser Anliegen: Wenn Sie sich wirklich verrückt machen wollen, + tun Sie dies bitte nachdem Sie Ihr Dokument comitted haben :-) + + Somit gilt als allgemeiner Rat: gehen Sie behutsam mit diesen Elementen um; verwenden Sie sie dort, wo + es nach Ihrem ermessen Sinn macht, aber übertreiben Sie es nicht. +
+ +
+ Abschluss der Elemente + + Sie haben sicherlich bemerkt, dass in gerenderten Dokumenten + (Sie lesen gerade eins, sofern Sie nicht die XML-Version geöffnet haben) + viele Elemente das gleiche Aussehen besitzen: Ein filename, ein literal und ein application haben die gleiche Typografie; das gleiche gilt für emphasis, firstterm und citetitle. + + Was ist also der Sinn dieser verschiedenen Tags? + Warum nicht nur ein paar, wie emphasis und literal, wenn sie sowieso gleich aussehen. + Dafür gibt es zwei gute Gründe: + + + + Erstens, wenn wir die meisten unserer Inline-Elemente als + emphasis und literal kennzeichnen würden, ginge auch die Semantik verloren. + Rufen Sie sich in Erinnerung, dass es im DocBook-XML nur um die Struktur und Semantik geht. + firstterm und citetitle können genauso + aussehen + wie emphasis, sobald es gerendert wurde, aber + sie sind nicht das Gleiche. Die XML-Quellen kennen diesen Unterschied, auch wenn dies nicht immer + offensichtlich ist. Diese Information ist nützlich, und wir wollen diese nicht verlieren. + + + + Des weitern, können wir unsere Stylesheets für jedes Element individuell anpassen. Sobald wir also entscheiden, + dass ein firstterm anders als ein + citetitle aussehen soll, können wir das tun - aber + nur wenn sie tatsächlich als unterschiedliche Tags markiert wurden, nicht wenn + beide emphasis's im XML-Quelltext sind. + + + + Damit schließen wir die Abschnitte über DocBook ab. Mit dem bis hierher gezeigten Wissen, + sollten Sie nun in der Lage sein, DocBook XML-Dokumente für das Firebird-Projekt zu erstellen. + Wenn Sie einen dedizierten XML-Editor - was sehr ratsam ist - sollten Sie außerdem dessen + Dokumentation konsultieren, um den Umgang hiermit zu lernen; Dies können wir mit diesem Leitfaden nicht abbilden. + + +
+
+ +
+ Sprache und Stil + + Nach der Flut von DocBook-Informationen im vorigen Abschnitt, werden wir unsere + Aufmerksamkeit einem anderen wichtigen Aspekt des Schreibens widmen: + Sprache und Stil (in diesem Abschnitt) sowie Copyrights (im nächsten Abschnitt). + +
+ Sprache + + Die Firebird Community ist sehr verschieden und besteht aus + Menschen mit vielen verschiedenen Muttersprachen. Wenn Sie Ihre + Dokumentation in einer anderen Sprache als der eigenen schreiben, werden Sie wahrscheinlich einige Fehler machen. + Dies ist nicht katastrophal, aber man sollte zumindest versuchen, + die Anzahl der Fehler zu reduzieren. Einige Strategien, die Ihnen dabei helfen, + sind: + + + + Benutzen Sie ein Wörterbuch! Einfach, effektiv und erstaunlicherweise keine + Hightech. + + + + + Wenn Sie zwischen zwei Schreibweisen eines Wortes oder zwischen + mehrere mögliche Versionen eines Ausdrucks schwanken, googeln Sie nach + Alternativen und achten Sie auf deren Frequentierung. + Folgen Sie Links, um zu sehen wie Muttersprachler das Wort oder den Ausdruck + in ihren Texten verwenden. + + + + Lassen Sie einen Muttersprachler über Ihren Text sehen und ggf. korrigieren. + + +
+ +
+ Stil + + Erwarten Sie nicht, einen Style Guide hier zu finden - ich wüsste nicht, wie man einen schreibt. + Nur ein paar Hinweise und Tipps: + + + + Versuchen Sie, in einfacher, alltäglicher Sprache, wo immer möglich zu schreiben. + Vermeiden Sie schwierige Wörter, wenn es eine vertraute, einfache + Alternative gibt. + + + + Vermeiden Sie lange Sätze (über 25 Wörter), wenn Sie können. Vermeiden Sie + vor allem zwei oder mehr lange Sätze unmittelbar nacheinander. + + + + Seien Sie vorsichtig mit Konstrukten wie doppelter oder dreifacher Verneinung + (Ich kann nicht leugnen, dass ich nicht unzufrieden bin) und passiver Sprache + (Vorsicht sollte geboten sein...). Sie müssen diese nicht unter allen Umständen + vermeiden, aber sie machen einen Satz schwer verständlich. Um dies zu verhindern, nutzen Sie positive + (Ich bin zufrieden) und aktive (Seien Sie vorsichtig...) Sprache. + + + + Verwenden Sie Listen für Aufzählungen, z.B. für: + + + + Eine Sammlung von Hinweisen und Tipps. + + + + Eine Reihe Beispiele (wie dieses hier). + + + + Schritte, die in einer Nummerierung erscheinen. + + + + Alternative Lösungsansätze für ein Problem. + + + + Sind jedoch nur wenige Einträge zu nennen, verwenden Sie stattdessen reinen Text: + Meine Mutter liebt drei Männer: John, Dick und + Dave. + + + + Nutzen Sie nicht zu viele Ausrufezeichen. Verwenden Sie niemals mehrere + Ausrufezeichen oder Fragezeichen. Das ist ärgerlich!! Glauben Sie nicht auch?? + + + +
+ Docwriter-Block + + + Manchmal wissen Sie, was Sie schreiben wollen, Sie haben alle + Wörter, aber Sie bekommen den Satz nicht zusammen - Ihnen gelingt einfach kein + Fluss. Das ist sehr frustrierend und es + kann manchmal den Fortschritt Ihres Textes für viele Minuten blockieren. Und + es ist umso frustrierender, weil Sie ja wissen + was Sie Ihren Leser sagen wollen, aber Sie scheinen nicht in der Lage zu sein, einen + anständigen Satz zu produzieren. Nach vielen schmerzhaften Erfahrungen dieser + Art, habe ich die folgende Strategie entwickelt (nicht, dass ich glaube, ich wäre der + erste): + + + + + Notieren Sie, was Sie in losen Sätzen und Wortbrocken sagen möchten. + Machen Sie sich keine Gedanken über den Stil. Schreiben Sie einfach, was Sie dem Leser sagen wollen, + stellen Sie sicher, dass alles da ist und in der richtigen Reihenfolge. + Wenn Sie währenddessen merken, dass Sie bei einer Sache unsicher sind, machen Sie sich eine Bemerkung an diesem + Punkt. Heben Sie Ihre Bemerkungen vom restlichen Text ab + z. B. <<wie diesen>> oder !WIE DIESEN! + + + Dies kann in folgendem Text enden: + +
+ + CVS bedeutet Concurrent Versions System + (<<überprüfen!>>). Zweck: Verwaltung von Softwareversionen. + Sie können es verwenden, allein oder in einer Gruppe. Sie müssen einen CVS-Client benutzen. + Ein CVS-Client ist ein Programm, mit dem Sie + auf ein CVS-Repository (<<Begriff erklären?>>) zugreifen können. Um + herauszufinden, ob Sie einen CVS-Client auf Ihrem System installiert haben, geben Sie + cvs auf der Kommandozeile ein. Wenn Sie keinen installiert haben, rufen Sie diese URL + für den Download auf .... [etc., etc.] + +
+ + + + Wenn Sie Bemerkungen eingefügt haben, kümmern Sie sich erst um diese. + Prüfen Sie, ob CVS wirklich Concurrent Versions + System bedeutet (tut es). Entscheiden Sie, ob Sie wirklich den Begriff + CVS repository an diesem Punkt erklären sollten (sollten Sie). + + + + + Gehen Sie nun nochmals über den Absatz und versuchen Sie, den Text fließender zu gestalten. + Wahrscheinlich wird dies leichter sein als Sie glauben! + + + + Wenn es noch etwas holprig aussiet, egal - besser holprig und klar als + glatt-fließend und unpräzise. Vielleicht können Sie diese Passage bei einem späteren Besuch + etwas schöner gestalten. + + + + Dieser Ansatz funktioniert gut für mich. Wenn also auch mals auf diese Weise festhängen, + probieren Sie es aus, hoffentlich wird es auch Ihnen helfen. +
+
+
+ +
+ Fragen des Urheberrechts + + Viele Leute finden, rechtliche Fragen langweilig, aber dies ist ein wichtiger + Abschnitt. Bitte lesen Sie ihn gründlich. + +
+ Verwendung fremden Materials + + + Während wir unsere Handbücher schreiben, ziehen wir alle anderen Arten von + Dokumentation zu Rate - und das sollten wir auch, da wir das beste Ergebnis erzielen wollen. + Alle Informationen, die wir in öffentlich zugänglichen + Drittanbieter-Handbücher, Benutzerhandbücher, Lernprogramme usw. finden, können in + unseren eigenen Dokus frei verwendet werden. Aber aber es ist wichtig + Informationen nicht mit wörtlichen Text zu verwechseln. + Wir dürfen nicht einfach Text aus anderen Werken in unsere eigenen + Dokumentation kopieren und einfügen, sofern es uns nicht seitens des Autors ausdrücklich erlaubt ist. + + + + Wenn Sie einen Text von jemand anderem verwenden wollen, + überprüfen Sie den Urheberrechtsschutz der Arbeit. Gibt es keinen, + wird die Arbeit automatisch nach der Berner Konvention urheberrechtlich geschützt und Sie + müssen davon ausgehen, dass es illegal ist diese zu kopieren - auch + teilweise. Dies gilt auch, wenn die Arbeit frei verfügbar ist! Nicht für ein + Dokument zu bezahlen bedeutet nicht, dass Sie Texte hieraus frei kopieren + und in einer eigenen Arbeit veröffentlichen dürfen. + +
+ Borland InterBase-Handbücher + + + Die Borland InterBase 6 Beta docs - obwohl kostenlos - sind nicht Bestandteil + des InterBase-Pakets, das im Juli 2000 Open-Source wurde. Wir haben mehrmals bei + Borland angefragt, ob wir diese Dokumente nutzen könnten, da + sie unter die InterBase Public License fielen, aber sie haben sich nicht mal + die Mühe gemacht zu antworten. + Fühlen Sie sich frei, diese Dokumentation als + Informationsquellen zu verwenden, aber kopieren Sie keine Texte hieraus. + +
+ +
+ PostgreSQL-Dokumente + + PostgreSQL ist eine weitere wichtige Open-Source-Datenbank, mit (nicht + überraschend) vielen Ähnlichkeiten zu Firebird, es gibt aber auch viele + Unterschiede. Abhängig von der Art der Dokumentation, die Sie schreiben wollen, + kann es vorteilhaft sein, sich auf bestehende PostgreSQL-Dokumente zu stützen. + Beachten Sie aber, dass, wenn Sie PostgreSQL Material verwenden, MÜSSEN Sie + deren Copyright in Ihrem Dokument verwenden! + + Die Homepage der PostgreSQL-Dokumentationen ist hier: + +
+ http://www.postgresql.org/docs/ +
+ + Die aktuelle PostgreSQL-Lizenz finden Sie hier: + +
+ http://www.postgresql.org/about/licence +
+ + Eine nette Sache der PostgreSQL-Dokus ist, dass sie + ebenfalls in DocBook verfasst sind, genau wie unsere. Allerdings verwenden sie DocBook SGML + anstelle von XML, somit werden bestimmte Einstellungen erforderlich sein. Die DocBook SGML + Quellen finden Sie hier: + +
+ http://developer.postgresql.org/cvsweb.cgi/pgsql-server/doc/src/sgml/ +
+ + Oder schauen Sie sich den gesamten CVS-Baum, Dokus und alles weitere an. Für + weitere Anweisungen schauen Sie unter: + +
+ http://developer.postgresql.org/docs/postgres/cvs.html +
+
+
+ +
+ Ihr Copyright und die PDL + + + Wenn Sie etwas zum Firebird Dokumention-Teilprojekt beitragen, wird Ihre + Arbeit im Open-Source-Repository bei SourceForge einbezogen. Im + Januar 2005 beschloss das Firebird doc-Team, die Dokumentationen unter der Public Documentation + License zu veröffentlichen. Die Lizenzierung der Arbeiten unter der PDL bedeutet, dass Sie + das Urheberrecht behalten, anderen Benutzern jedoch bestimmte Rechte gewähren: + + + + + Kostenlose Nutzung: Jeder kann Ihre Arbeit verwenden und verteilen, + kostenlos oder gegen Geld, solange die Lizenzhinweise intakt gehalten werden. + + + + Recht auf Änderung: Jeder kann Ihre Arbeit modifizieren und + verteilen, solange alle modifizierten Versionen ebenfalls der + PDL unterliegen, der ursprüngliche Lizenzhinweis beibehalten wird, und + die Änderungen dokumentiert werden. + + + + Größere Werke: jeder darf Ihre Dokumentation in einem größeren Werk (modifiziert oder nicht) + integrieren. Die größeren Arbeiten als Ganzes müssen nicht unter der PDL veröffentlicht werden, aber die Lizenzvoraussetzungen + müssen für die PDL-lizenzierten Teile erfüllt sein. + + + + Das Schöne an der PDL ist, dass sie die gleichen Rechte + und Beschränkungen für die Nutzung unserer docs bietet wie es die IPL und IDPL + (Firebird Code-Lizenzen) für den Firebird-Quellcode tun. Den + vollständigen Text unserer Lizenz finden Sie über die Links in den Lizenzhinweisen weiter unten; der + DocBook-Quellcode liegt unter + src/docs/firebirddocs/licenses.xml + +
+ Wie wenden Sie die PDL auf Ihr Werk an? + + Um Ihre Arbeit unter der PDL freizugeben, fügen Sie ein appendix mit dem Titel License + Notice und folgendem Text an: + +
+ The contents of this Documentation are subject to the Public + Documentation License Version 1.0 (the License); you + may only use this Documentation if you comply with the terms of this + License. Copies of the License are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) and http://www.firebirdsql.org/manual/pdl.html + (HTML). + + The Original Documentation is _TITLE OF THE + WORK_. + + The Initial Writer of the Original Documentation is _INITIAL + AUTHOR'S NAME_. + + Copyright (C) _YEAR(S)_. All Rights Reserved. Initial Writer + contact(s): _EMAIL OR OTHER CONTACT ADDRESS(ES)_. +
+ + Alles, was wie _LIKE THIS_ aussieht, muss natürlich ersetzt werden. + + Wenn Sie nicht der ursprüngliche Autor sind, lassen Sie seine oder ihre Bekanntmachung + intakt und fügen Sie den folgenden Text ein: + +
+ Contributor(s): _NAME(S) + SHORT DESCRIPTION (COUPLE OF WORDS) + OF CONTRIBUTION_. + + Portions created by _CONTRIBUTOR'S NAME_ are Copyright (C) + _YEAR(S)_. All Rights Reserved. Contributor contact(s): _EMAIL OR + OTHER CONTACT ADDRESS(ES)_. +
+ + Es kann diverse Contributor's sections (Hinweise auf Beitragende Autoren) in den Lizenzhinweisen geben. +
+ +
+ Einfügen einer Dokumenthistorie + + Wenn Ihr Beitrag aus mehr als einer einfachen Änderung oder + Addition an einer Stelle besteht, fügen Sie einen Anhang ( appendix ) mit Namen Dokumenthistorie vor oder nach der Lizenz und Datenschutz ein. + Wenn ein solcher Anhang bereits vorhanden ist, geben Sie eine immer eine Beschreibung Ihrer + Modifikation(en) darin an. Bitte beachten Sie, dass selbst wenn es bereits eine Dokumenthistorie gibt, + Sie noch einen Mitwirkendenabschnitt in den Lizenzhinweisen hinzufügen müssen + - aber Sie können dann auch einen Hinweis siehe Dokumenthistorie + anstelle der Kurzbeschreibung angeben. + + Wenn Sie der ursprüngliche Autor sind, dann ist es auch völlig in Ordnung, eine Dokumenthistorie + in der ersten Version eines Dokuments für spätere Revisionen einzufügen. Vergleichen Sie das erste Revision-Element im Beispiel + unten. + + Gegenstand der Dokumenthistorie ist das Element revhistory mit seinen Unterelementen: + + <revhistory> + <revision> + <revnumber>1.0</revnumber> + <date>12 Sep 2005</date> + <authorinitials>PV</authorinitials> + <revdescription> + <para>First version</para> + </revdescription> + </revision> + <revision> + <revnumber>1.1</revnumber> + <date>5 Dec 2005</date> + <authorinitials>PV</authorinitials> + <revdescription> + <para>Added information on COALESCE</para> + <para>Corrected some spelling errors</para> + </revdescription> + </revision> +</revhistory> + + Bitte kürzen Sie die Monatsnamen im Date-Element, da die Datumsspalte im PDF + recht schmal ist. + + + Unten ist ein Beispiel zur Dokumenthistorie (Ausgabeansicht, nicht Quelle!), + welches ein + revhistory-Element darstellt. + Beachten Sie die Verweise im CVS-Baum: Wir sind gesetzlich verpflichtet, + alle Änderungen zu identifizieren und zu datieren. Aber da CVS dies bereits tut, können wir + einfach den Benutzer hierüber informieren und eine weniger umfangreiche, aber + schöner zu lesende Historie im Dokument selbst vorzeigen. + +
+ Die exakte Dateihistorie wird im CVS-baum des manual Modul festgehalten; siehe + http://sourceforge.net/cvs/?group_id=9028 + + + + 1.0 + + 2003 + + IBP + + + First publication of the free Quick Start + Guide. + + + + + 1.x + + June 2004 + + IBP + + + Donated to Firebird Project by IBPhoenix. + + + + + 2.0 + + 2004 + + PV + + + Downgraded to Firebird 1.0 + + Added Classic vs. Superserver section. + + Reorganised and corrected Disk Locations Table. + + Added (new) screenshots. + + Updated and completed information on Control Panel + applets. + + Added extra examples to Expressions involving + NULL. + + Various other corrections and additions. + + + +
+ + Wenn Sie den DocBook-Quellcode dieses Leitfadens in Ihrem XML-Editor öffnen + (src/docs/firebirddocs/docwriting-howto.xml), + können Sie ganz einfach die Dokumenthistorie und die Lizenzhinweise kopieren und in ihr eigenes Dokument einfügen. + Kopieren Sie nicht die + oben angeführten Beispiele; kopieren Sie die realen Anlagen am Ende der + Dokumente, und bearbeiten Sie diese. +
+ +
+ Ein Copyright zum Beginn + + Unsere Lizenz und Documenthistorie, erscheinen beide am Ende + des Dokument. Wenn Ihre Urheberrechte offensichtlich direkt am Beginn ausweisen möchten, + können Sie auch einen kurzen Copyright-Hinweis in der + xxxinfo des Dokuments einfügen, so z.B.: + + <bookinfo> + <title... + <author... + <edition... + <copyright> + <year>2003</year> + <year>2004</year> + <holder>Tootsie Griff</holder> + </copyright> +</bookinfo> + + Solch ein Hinweis ersetzt nicht die Lizenzhinweise und / oder Dokumenthistorie - es ist ein Extra. +
+ +
+ Anhängen der gesamten Pubic Documentation License + + + Anstelle der URL, können Sie auch die gesamte PDL + in Ihrem Dokument anhängen. Dies kann besonders nützlich sein, wenn Ihre Arbeit ein Buch + (book) oder langer Artikel (article) ist und Sie erwarten (oder hoffen), dass die Menschen + es drucken und in Papierform verteilen werden. Auf einem kurzen Dokument wird die gesamte PDL + ein wenig übertrieben wirken, aber es ist Ihre Entscheidung. + + Sie können die PDL DocBook-Quellen unter + src/docs/firebirddocs/licenses.xml erhalten. Bitte beachten Sie, + dass nur der Abschnitt mit dem Lizenztext selbst (einschließlich der + allgemeine Lizenzhinweis) zur PDL gehört. Die Einführung + ist nicht Bestandteil der Lizenz. + + Wenn Sie die PDL in Ihrem Dokument einbinden, können Sie die Leerstellen in Abschnitt 5.2 der Lizenz ausfüllen. + Sie können sie aber auch lassen, wie sie sind (vorausgesetzt, Ihr Name steht im Lizenzhinweis) oder geben Sie einfach den + Initial Writer oder den Urheberrechtshalter an. +
+ +
+ Hinweise für Übersetzer + + Die Übersetzung eines Dokuments ist eine Art der Bearbeitung. Wenn Sie also ein Übersetzer sind, sollten Sie folgende Dinge tun: + + + + Listen Sie sich selbst als Mitwirkender im Lizenzhinweis auf, mit einer + Beitragsbeschreibung wie z. B. "Übersetzung ins Russische". Sie können + den Lizenzhinweis in die Zielsprache übersetzen, wenn Sie + wollen, aber Sie können es auch in Englisch lassen oder in beiden + Sprachen führen. + + + + Fügen Sie ein Element Revision - + in der Zielsprache - zur revhistory der Dokumenthistorie ein. Für + die Revisionsnummer (revnumber), verwenden Sie die + Zahl der Revision, die Sie übersetzt haben, gefolgt von einer + Bindestrich und Ihrem Sprachcode, z. B. + 2.0-ES oder + 1.1-fr: + + <revhistory> + ...previous revisions... + <revision> + <revnumber>1.1</revnumber> + <date>5 Dec 2005</date> + <authorinitials>PV</authorinitials> + <revdescription> + <para>Added information on COALESCE</para> + <para>Corrected some spelling errors</para> + </revdescription> + </revision> + <revision> + <revnumber>1.1-fr</revnumber> + <date>13 Déc 2005</date> + <authorinitials>AM</authorinitials> + <revdescription> + <para>Traduction en français</para> + </revdescription> + </revision> +</revhistory> + + + + Fügen Sie ein othercredit-Element + zur xxxinfo am Anfang des Dokuments ein, z.B.: + + <articleinfo> + <title>Guía de NULL en Firebird</title> + <author> + <firstname>Paul</firstname> + <surname>Vinkenoog</surname> + </author> + <othercredit> + <firstname>Víctor</firstname> + <surname>Zaragoza</surname> + <contrib>Traducción al castellano</contrib> + </othercredit> + <edition>22 de julio de 2005 - Versión de documento 2.0-es</edition> +</articleinfo> + + Das contrib-Element für Mitwirkende beinhaltet die gleiche Information + wie die Mitwirkende-Beschreibung in den Lizenzhinweisen, sollte aber immer in der Zielsprache verfasst sein. + + + Kennzeichnen Sie die Dokumentversion im edition-Element – stellen Sie sicher, dass es die gleiche + wie in der Dokumenthistorie ist. + + +
+ +
+ Übersetzung der PDL + + Sie müssen die PDL nicht üebersetzen. Wenn Sie dies jedoch tun: + + + + Fügen Sie ein unabhängiges Dokument zum Dokumentensatz (set) Ihrer Sprache in einem + Buch mit Namen Licenses hinzu. (Aber übersetzen Sie + Licenses in Ihre + Sprache). + + + + In der übersetzten Einleitung der PDL, erklären Sie, dass nur die englische Version + rechtlich bindend ist und fügen Sie einen Link zur englischen Version ein. + + + + In allen Lizenzhinweisen, die zur übersetzten Version der PDL führen, ist auch ein Link zur + englischen Version zu hinterlegen und stellen Sie klar, dass nur die englische Version rechtlich + bindend ist. + + + + Optional können Sie die übersetzte PDL an Ihr Dokument anhängen, wenn Sie der Extraaufwand nicht stört. +
+
+
+ +
+ Fügen Sie Ihr Dokument dem manual Modul hinzu + + Hinzufügen Ihres Dokuments zum Modul + + Wenn Ihr Dokument abgeschlossen ist, und Sie überprüft haben, dass es + korrekt erstellt wird, möchten Sie es sicherlich in manual Modul hinzufügen. + Wenn dies Ihr erster Beitrag zum Dokumentationsprojekt ist, werden Sie sicherlich verstehen, + dass Sie Ihr Werk zuerst bei den Koordinatoren für die Überprüfung einreichen. Alternativ können Sie + die HTML-Version auch auf einer Webseite zugänglich machen, sodass das Ergebnis auf der Mailingliste diskutiert werden + kann. Danach - und vielleicht nach ein paar Korrekturen - kann das Dokument im Modul eingebunden werden. + Wenn Sie die erforderlichen Rechte besitzen, können Sie dies selbst tun, wenn nicht, übernimmt das einer der Koordinatoren + für Sie. + +
+ Anfordern der Commit-Berechtigungen + + Um die Commit-Rechte zu erhalten benötigen Sie zunächst einen Account für SourceForge. + Wenn Sie bisher keinen besitzen, registrieren Sie sich unter http://sourceforge.net/account/register.php. + Schicken Sie dann eine Mitteilung an die firebird-docs Mailingliste mit Ihrem + SF-Benutzernamen und der Bitte diesen zum Firebird-Projekt hinzuzufügen. + Der Leiter des manual-Unterprojekt und diverse Firebird-Projektadmins verfolgen die Liste; + Sie werden sich Ihrer Anfrage annehmen. Generell sollten Sie die Berechtigungen nach Ihrem + ersten Beitrag anfordern, da die Entscheidungsträger etwas in der Hand haben wollen. + + Die folgenden Phrasen sind gleichbedeutend: + + + + Projektmitglied sein. + + + + Commit-Rechte besitzen. + + + + Schreibenden und lesenden Zugriff für das Repository zu besitzen. + + +
+ +
+ Was sollten Sie tun und was nicht, sobald Sie Commit-Rechte besitzen? + + + Sobald Sie als Projekt-Mitglied angenommen werden, haben Sie Schreibzugriff + auf die gesamte Firebird-Repository, nicht nur auf das manual Modul. Es + ist kein technisches Hindernis, Änderungen für andere Module zu committen + - das firebird2-Kernmodul zum Beispiel, oder + sogar das CVSROOT -Modul, in dem wichtige Projektinformationen gespeichert sind. + + + Sie haben sich sicherlich schon gedacht, dass dies NICHT Sinn der Sache ist. + Halten Sie sich an folgende Regeln: + + + + Tätigen Sie niemals Eingaben zu anderen Modulen, es sei denn + die Verantwortlichen fordern Sie ausdrücklich dazu auf. + + + + + Committen Sie nur Arbeiten zum manual Modul, wenn es eine + Ihnen zugewiesenen Aufgabe betrifft. Selbst dann ist es eine gute Praxis, + Änderungen und Ergänzungen auf der Mailing-Liste anzukündigen, so dass die anderen + Schreiber eine Chance haben, sich dazu zu äußern. Immerhin ist dies eine + kollektive Anstrengung. + + + + Wenn Sie denken, dass ein neues Dokument oder ein Verzeichnis aufgenommen werden sollte, + erstellen und committen Sie es nicht einfach, schlagen Sie es vor auf der Liste. + + + + In der Praxis sind die Dinge ein bisschen entspannter als hier angegeben, + insbesondere dann, wenn es Ihre eigenen Aufgaben betrifft. Wir wollen nicht, dass Sie sich + beschränkt fühlen und sicherlich soll Ihnen nicht das Gefühl gegeben werden, dass man + für jede kleine Änderung um Erlaubnis fragen muss. Aber wir möchten, dass Sie + verantwortungsvoll handeln, und wir wollen von einander wissen, was wir tun. + Außerdem ist einander zu kontakieren oft inspirierend. + Gemeinsam können wir die Dinge am Laufen halten! +
+ +
+ Committen Sie Ihre Arbeit + + Selbst wenn Sie Projektmitglied sind, können Sie Änderungen Ihrer lokalen Kopie nur abgeben, wenn diese + auch mit Ihrem SF-Login ausgecheckt wurde. Wenn Sie immer noch mit einer Kopie arbeiten, die anonym + ausgecheckt wurde, müsen Sie erst einen frischen SSH-Checkout durchführen und die Änderungen erneut + zuweisen. Danach führen Sie den Commit aus. Bitte vgl. Sie auch Docbuilding + Howto, wenn Sie nicht mehr wissen, wie der SSH-Checkout durchzuführen ist. + + Wenn zwischen Ihrem letzten Checkout oder Update einige Zeit vergangen ist, + führen Sie erst ein Update vor dem Commit aus. Dies wird Ihre lokale Kopie mit dem + Repository synchonisieren und die Anzahl möglicher Konflikte reduzieren. + + Sobald Sie für einen Commit bereit sind, wechseln Sie in das manual-Verzeichnis. Wenn Sie command-line CVS verwenden, + tippen Sie folgendes ein: + +
+ cvs update -d [ nur wenn Sie erst ein Update durchführen wollen ] + + cvs add + path/to/mydocument.xml [ nur wenn ein neues Dokument + vorhanden ist, dass noch nicht im CVS liegt ] + + cvs commit -m "Kurze Informationsbeschreibung, die hier einzugeben ist" +
+ + Nach dem -m und innerhalb der Anführungszeichen, ist eine kurze + Information über diesen Commit anzugeben, z.B. "Neue Funktionen zur API-Referenz hinzugefügt" oder + "Fehler im isql-Handbuch gefixt". + + Geben Sie Ihr SF-Kennwort ein, wenn es abgefragt wird, damit alle Ihre durchgeführten Änderungen + - inlusive der Unterverzeichnisese - committed werden. Ihr CVS-Client weiß welcher Server zu kontaktieren ist; + diese und andere Informationen sind in den CVS-Unterverzeichnissen gespeichert, + die während des Checkout erstellt wurden. + + Wenn Sie einen anderen CVS-Client verwenden, konsultieren Sie hierzu bitte die Dokumentation. + + + Nachdem ein neues Dokument hinzugefügt wurde, müssen Sie einen separaten Commit durchführen. Dies + gilt für command-line CVS und die meisten (wenn nicht für alle) anderen CVS-Clients. + +
+
+ +
+ Veröffentlichung Ihres Dokuments auf der Firebird Website + + Veröffentlichung Ihres Doks auf der Website + + Möchten Sie Ihr Dokument veröffentlichen, müssen erst die HTML- und PDF-Ausgaben generiert werden. + Dieser Vorgang wird im Firebird + Docbuilding Howto besprochen. Wir gehen in diesem Abschnitt davon aus, dass dies erfoglreich + durchgeführt wurde. + +
+ Benennung der PDF-Datei + + Die Build-Tools benennen die Dateien automatisch nach ihrer ID + im obersten DocBook-Element. Wir ändern die Namen der Mehrseiten-HTML-Ausgabe nicht - + diese Seiten werden primär für die Onlinebetrachtung genutzt, und das Ändern eines einzigen Dateinamens + würde sofort diverse Links zerstören. PDFs hingegen werden häufig heruntergeladen und Dateinamen wie + qsg2.pdf oder ubusetup.pdf in einem Downloadverzeichnis + oder auf einem Desktop sind + wirklich nicht hilfreich bei der Identifizierung als Firebird-Handbücher. Deshalb sind + hier ein paar Richtlinien für die Dateinamen: + + + + Stellen Sie sicher, dass der Name das Wort + Firebird, bevorzugt am Anfang, verwendet; + + + + Versuchen Sie den Dokumenttitel zu nutzen, aber halten Sie es kurz; + + + + Nutzen Sie Bindestriche (-) um Wörter zu separieren; + + + + Wenn der Titel sehr lang ist, vermeiden Sie Teile wie Handbuch, + Leitfaden, Howto etc., es sei denn das Weglassen würde zu Konfusionen führen; + + + + Nutzen Sie die Dokumentsprache, verwenden Sie aber nur ASCII-Zeichen (keine Umlaute, etc.) + + + + Falls (und nur falls) die Anwendung der o.a. Regeln zu einem + bereits vorhandenen Dateinamen einer anderen Sprache führen, fügen Sie die Dokumentsprache (oder ihre Abkürzung) hinzu. + + + + Um die genannten Richtlinien zu verdeutlichen, werden einige existierende Beispiele unten aufgelistet: + + + + Firebird-2.0-QuickStart.pdf + + + + Firebird-Security.pdf + + + + MSSQL-to-Firebird.pdf + + + + Firebird-Generator-Guide.pdf + + + + Firebird-nbackup.pdf + + + + Firebird-2.0-Schnellanleitung.pdf + + + + Firebird-1.5-Arranque.pdf + + + + Firebird-et-Null.pdf + + + + Firebird-nbackup-fr.pdf + + + + Firebird-su-Ubuntu.pdf + + + + Firebird-nbackup-nl.pdf + + + + Guia-Escrita-Firebird.pdf + + + + Firebird-1.5-BystryjStart.pdf + + + + Firebird-Perehod-s-MSSQL.pdf + + +
+ +
+ Einseitiges HTML-Dateien + + + Falls und wenn wir mit der Veröffentlichung von einseitigen HTML-Dateien auf der + Website beginnen - mittels build monohtml erstellt - sollten + wir die gleichen Namen wie die entsprechenden PDFs verwenden, aber natürlich mit der Erweiterung + .html. +
+ +
+ Hochladen der PDF + + Wenn Sie Schreibrechte auf den Firebird Webserver besitzen, stellen Sie eine SFTP-Verbindung + zu web.firebirdsql.org und laden Sie die Dateien hoch: + + + + /srv/www/htdocs/pdfmanual (English + docs) + + + + /srv/www/htdocs/pdfmanual/fr (French + docs) + + + + /srv/www/htdocs/pdfmanual/ja (Japanese + docs) + + + + etc. + + + + Release Notes werden in den entsprechenden Verzeichnissen abgelegt: + + + + /srv/www/htdocs/rlsnotes + + + + /srv/www/htdocs/rlsnotes/fr + + + + etc. + + + + Wenn Sie keine Schreibrechte für den Server besitzen, fragen Sie jemanden, der diese + besitzt. Falls Sie ein Projektmitglied sind, können Sie auch nach einem Benutzer und Kennwort + für den Server fragen. +
+ +
+ Hochladen von mehrseitigen HTML-Dateien + + Stellen Sie sicher, dass Sie alle notwendigen Dateien hochladen: die HTML-Dateien, die + zusammengenommen Ihr Handbuch (oder Handbücher) darstellen, das Stylesheet + firebirddocs.css (wenn es seit dem letzten Upload geändert wurde), + und das Unterverzeichnis images mit allen geänderten oder hinzugefügten Inhalten. + Um alle Links funktionsfähig zu halten, kann es notwendig sein, das übergeordnete book + ebenfalls neuzuerstellen und hochzuladen (oder gar das gesamte set). Laden Sie das gesamte Drumherum nach: + + + + /srv/www/htdocs/manual + (English docs) + + + + /srv/www/htdocs/manual/fr (French + docs) + + + + etc. + + + + + + Wenn in Frage kommende Seiten zu einem anderen Basis-Set gehören als die standardmäßigen + firebirddocs (z. B. + papers oder rlsnotes), dann platzieren + Sie diese nicht in den erwähnten Verzeichnissen. Wir haben hierfür noch keine klaren Regeln definiert, + aber mehrseitige HTML-Builds sollten nicht mit anderen Sets gemischt werden. + Wenn diese Situation eintritt, melden Sie es bitte auf der + firebird-docs Liste. + +
+ +
+ Aktualisieren des Firebird Dokumentationsverzeichnisses + + Das Firebird Dokumentationsverzeichniss unter http://www.firebirdsql.org/index.php?op=doc + ist ein PHP-Skript, dass die meisten Inhalte aus den auf dem Server liegenden Dateien holt. + Wenn Sie existierende Dokumente aktualisiert haben, die bereits im Verzeichnis aufgeführt sind, + ist nichts weiter zu tun, sofern Sie den Dateinamen nicht geändert haben. Wenn Sie jedoch ein neues Dokument + oder eine neue Übersetzung erstellt haben, müssen sie dies dem Verzeichnis bekannt geben. Hier steht wie: + + + + Wenn Sie ein komplett neues Dokument erstellt haben + + + + + Schauen Sie sich das Dokumentationsverzeichnis an und entscheiden Sie welche Kategorie + am besten zu Ihrem Dokument passt. (Kategorien werden durch orange Köpfe gekennzeichnet.) + + + + Verbinden Sie sich zum Server, gehen Sie in Verzeichnis/srv/www/htdocs/doc und werfen Sie einen Blick + auf die Dateien, die mit Cat_ beginnen. Öffnen Sie die Datei, die + zu Ihrer gewählten Kategorie gehört. + + + + Lesen Sie die Anweisungen am Anfang der Datei. + + + + Erstellen Sie einen neuen Abschnitt, beginnend mit dem Titel des Dokuments in + Englisch, durch eine speziell formatierte Zeile für jede + verfügbare Version. Bei einem neuen Dokument könnte ein solcher Abschnitt + wie folgt aussehen: + + Firebird Uninstallation Howto +en:/manual/fb-uninstall.html +en:/pdfmanual/Firebird-Uninstall.pdf + + Jede Versionszeile beginnt mit dem Sprachcode, + gefolgt von einem Doppelpunkt, gefolgt von einer URL. Für Dokumente, die auf unserem + eigenen Server liegen, ist diese URL einfach der absolute + Weg beginnend am Server-Root. Die Abschnitte werden durch Leerzeilen getrennt. + Die Reihenfolge der Abschnitte in der Datei bestimmt die + Reihenfolge der Dokumente innerhalb ihrer Kategorie im + Dokumentationsverzeichnis auf der Webseite. Die Reihenfolge der Versionszeilen + innerhalb eines Abschnitts ist irrelevant. + + + + + Speichern Sie die Datei. Wenn Sie diese auf Ihrem eigenen Computer bearbeiten, + laden Sie sie zurück auf den Server. Aktualisieren Sie jetzt die Firebird + Dokumentationsverzeichnis-Seite in Ihrem Web-Browser und überprüfen Sie, ob das + Dokument dort aufgeführt ist, wo es sein sollte, und ob die Links funktionieren. + Stellen Sie außerdem sicher, dass die Links in der korrekten Spalte sind + (HTML in der mittleren Spalte, PDF etc. in der + Spalte ganz rechts). + + + + Das PHP-Skript macht einen ziemlich guten Job bei der + automatischen Bestimmung des Dokumenttyps, aber es gibt Fälle, in denen + es diesen falsch ermittelt. Wenn dies der Fall ist, fügen Sie den Dateityp - zwischen + geschweiften Klammern - unmittelbar nach der URL in der Versionszeile ein + + en:http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_60_sqlref{html} + + + + Sobald alles funktioniert, committen Sie die aktualisierte + Kategorie-Datei zum CVS. Wenn Sie das Firebird web-Modul vom SourceForge-Server ausgecheckt haben, + finden Sie die Kategorie-Dateien (und mehr) im Ordner + web/website/doc. Verwenden Sie Ihren SF-Benutzernamen und das + zugehörige Kennwort für den Checkout, andernfalls werden Sie nicht in der Lage sein Ihre Änderungen + zu committen. Die Arbeit mit CVS ist beschrieben im Firebird + Docbuilding Howto. + + + + + + + + + Wenn Sie ein existierendes Dokument in eine neue Sprache übersetzt haben oder ein neues Dokument + hierfür erstellt haben + + + + + Schauen Sie sich das Dokumentationsverzeichnis an und entscheiden Sie welche Kategorie + am besten zu Ihrem Dokument passt. (Kategorien werden durch orange Köpfe gekennzeichnet.) + + + + Verbinden Sie sich zum Server, gehen Sie in Verzeichnis/srv/www/htdocs/doc und werfen Sie einen Blick + auf die Dateien, die mit Cat_ beginnen. Öffnen Sie die Datei, die + zu Ihrer gewählten Kategorie gehört. + + + + Lesen Sie die Anweisungen am Anfang der Datei. + + + + + Suchen Sie den Abschnitt für das betreffende Dokument und fügen Sie die Versionszeile(n) für + Ihre Anpassungen hinzu, z.B.: + + Firebird Uninstallation Howto +en:/manual/fb-uninstall.html +en:/pdfmanual/Firebird-Uninstall.pdf +fr:/manual/fr/fb-uninstall-fr.html +fr:/pdfmanual/fr/Deinstaller-Firebird.pdf + + Die Reihenfolge der Versionszeile ist irrelevant, aber der Titel muss ganz oben bleiben. + + + + Schritte 5, 6 und 7 sind die gleichen wie die für neue Dokumente. + + + + + +
+
+ + + Dokumenthistorie + + Die exakte Dateihistorie kann über das manual Modul im CVS Baum abgerufen werden; http://sourceforge.net/cvs/?group_id=9028 + + + + 0.1 + + 17 Jan 2004 + + PV + + + Erster unvollständiger Entwurf, veröffentlicht unter dem Titel + Writing Documentation for Firebird (aka + Firebird Docwriting Howto). + + + + + 0.2 + + 27 Jan 2004 + + PV + + + Erste vollständige Version. (Erhielt Eingang in CVS am 31 Jan + 2004) + + + + + 1.0 + + 8 Mär 2004 + + PV + + + Erstes offizielle Release auf der Firebird-Website. + + + + + 1.1 + + 26 Feb 2005 + + PV + + + Die folgenden Änderungen wurden zwischen + März 2004 and Februar 2005 durchgeführt: + + Änderung des Titels zu Firebird Docwriting + Guide. + + Abschnitt zu PostgreSQL docs hinzugefügt. + + Hinweis für nicht-DocBook-Mitwirkende hinzugefügt. + + Erklärung des Begriffs wohlgeformtes XML. + + DocBook-Vorteile klarer herausgestellt. + + Empfehlung von section-Elemente gegen sectN-Elementen getauscht. + + xref und anderen wenig verwendetes + Zeug aus der Elementreferenz entfernt; procedure hinzugefügt. + + Info über nichtproportionales Literallayout aktualisiert. + + Abschnitt über PDL und wie die Lizenhinweise und Dokumenthistorien zu verwenden sind hinzugefügt. + + Einige kleinere Verbesserungen. + + Dokumenthistorie und Revisionsnummer hinzugefügt.. + + Lizenzierung dieser Arbeit unter der Public Documentation + License. + + + + + 1.1.1 + + 8 April 2005 + + PV + + + Absatz über titleabbrev-Elemente hinzugefügt. + + + + + 1.2 + + 10 Feb 2006 + + PV + + + Alle <sectN>-Elemente in der Quellcodestruktur in <section> abgeändert. + + Änderung der docbuildhowto links in ulinks, da die Artikel absofort in separaten PDFs landen. + + DocBook XML Characteristics: Bemerkung über + plaintext entfernt. Hinweis zu XSLT hinzugefügt. + + DocBook XML authoring tools: in zwei Unterabschnitte aufgeteilt; + Warnung bzgl. ConText UTF-8-Problem; Info zu SciTE hinzugefügt; + Warnung bzgl. Speichern als 8-bit hinzugefügt; ersten Absatz über dedizierte XML-Editoren angepasst; + Oxygen hinzugefügt; Altova Authentic entfernt; Aktualisierung/Anpassung der Informationen über Altova XMLSpy. + + Writing your DocBook doc: umbenannt in + Setting up your DocBook doc; Änderung des zweiten Absatzes; + dritten Absatz verschoben (Please read the subsection...) nach Elements we use frequently; + Anpassung der Links von subsection on hierarchical elements zum neuen Absatz. + + Creating the Document: Set/Book Einleitung geändert; + Master-Dok-Beispiel geändert; UTF-16-Hinweis hinzugefügt; + Informationen über Platzierung von Dateien, die zu anderen Basis-Sets gehören. + + Typing text: Kleinere Änderungen des ersten und letzten Absatzes. + + Elements we use frequently: zum Hauptabschnitt befördert, eingegliedert nach Setting up your DocBook doc; + Tip vor dem ersten Unterabschnitt zu normalem Absatz geändert, Änderung des ersten Satzes; + Trennung von Hierarchical elements in Unterabschnitte, und Bearbeitung / Ergänzung von vielem Zeug; + Unterabschnitt über HTML-Tabellen hinzugefügt; Starke Änderungen des Abschnitts + quote - literal; Unterabschnitte über Bilder und Absätze hinzugefügt. + + Non-DocBook aspects of the writing process: verschwunden, alle Unterabschnitte + wurden zu Hauptabschnitten befördert; ihr erster Absatz ist nun in + Language and style zu finden. Bearbeitungen. + + Copyrights: Umbenannt in + Copyright issues und Einleitungsabsatz eingefügt. + + Respecting others' copyrights: + renamed Using material written by others. + Der erste Absatz wurde in zwei geteilt und bearbeitet. Der Absatz über Borland + docs wurde in einen Unterabschnitt ausgegliedert, die ersten Wörter entfernt. + Using PostgreSQL docs ist nun ein Unterabschnitt in Using material written by + others, und umbeannt in PostgreSQL + docs. + + Your copyright and the PDL: starke Bearbeitung, Reorganisation der Unterabschnitte, und Ergänzungen. + + Committing your work: Ergänzung von + cvs add command line und + Important-Hinweis zum Committen nach dem Hinzufügen. + + + + + 1.2.1 + + 11 Mai 2006 + + PV + + + Start tag in bridgehead-Beispiel korrigiert (/ entfernt). + + + + + 1.2.2 + + 25 Jan 2007 + + PV + + + Elements we use frequently: Erwähnung der + title-Option für Warnungen und Hinweise. + Einleitungen für Übersetzer in einen Hinweis verschoben + . + + + + + 1.3 + + 5 Mai 2007 + + PV + + + Topics discussed in this guide: Neuen + Eintrag zur letzten Liste hinzugefügt. + + Links: Hinweis über das Ausgleichen von "hot zones" + (behoben in FOP 0.93). + + Program listings, screens, literal layout, and examples: Hinweis über nicht-proportionale Schriften entfernt literallayout. Änderung der Ausgabe von example in ein Zitat. + + HTML tables: id zugewiesen. Änderung von + processing instructions in ein firstterm. + + PDF rendering of large tables: Neuer Abschnitt. + + Style: Kleine Neuanordnung der Wörter im 3. Listeneintrag. + + Publishing your document on the Firebird website: Neuer Abschnitt. + + License notice: (C) 2004–2006 -> + 2004–2007. + + + + 1.3-de + + 21. Jul 2013 + + MK + + + + Deutsche Übersetzung basierend auf der englischen Dokumentenversion 1.3. + + + + + + + Lizenzhinweis + + Der Inhalt dieser Dokumentation unterliegt der "Public Documentation + License Version 1.0" (der Lizenz); die Dokumentation darf + nur unter Respektierung dieser Lizenz genutzt werden. Kopien der Lizenz + sind verfügbar unter http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) und http://www.firebirdsql.org/manual/pdl.html + (HTML). + + Die Original-Dokumentation trägt den Titel Firebird Docwriting + Guide. + + Der ursprünglich Autor der Original-Dokumentation ist: Paul + Vinkenoog. + + Copyright (C) 2004-2007. Alle Rechte vorbehalten. Kontakt zum + Original-Autor: paulvink at users dot sourceforge dot net. + + Übersetzung ins Deutsche: Martin Köditz. + + Übersetzung ins Deutsche Copyright (C) 2013: Alle Rechte vorbehalten. Kontakt: martin dot koeditz at it-syn dot de. + + \ No newline at end of file diff --git a/src/docs/firebirddocs-de/fb-docwriters-info-de.xml b/src/docs/firebirddocs-de/fb-docwriters-info-de.xml new file mode 100644 index 00000000..09f7d8b2 --- /dev/null +++ b/src/docs/firebirddocs-de/fb-docwriters-info-de.xml @@ -0,0 +1,16 @@ + + + + + + Dokumentation für Firebird Docwriter + Firebird Docwriters' Docs + + + &docwriting-howto-de; + &font-embedding-de; + &fbvpn-de; + + diff --git a/src/docs/firebirddocs-de/fbdoc_vpn-de.xml b/src/docs/firebirddocs-de/fbdoc_vpn-de.xml new file mode 100644 index 00000000..c77d5c27 --- /dev/null +++ b/src/docs/firebirddocs-de/fbdoc_vpn-de.xml @@ -0,0 +1,509 @@ + + +
+ Anleitung für den Umgang mit dem Firebird-VPN + + Beschaffen und installieren der VPN-Software + + + 30 March 2010 + + + Norman + + Dunbar + + + + Martin + + Köditz + + Übersetzung ins Deutsche + + + 22. August – Dokumentenversion 1.0-de - Deutsche Übersetzung + + +
+ Beschaffen und installieren des VPN + +
+ Einleitung + + Damit Dokumentenersteller fertige Dokumente hochladen können, wird + mittlerweile ein VPN-System benötigt, während bisher ein sicherer FTP-Zugang alles war + was benötigt wurde. Dieses Dokument gibt detailierte Hinweise, wie Sie die Software + erhalten und installieren. Abschließend wird geprüft, ob alles läuft. + + Anweisungen wie die Dokumente hochgeladen werden, werden in den + jeweiligen Docwriting-Handbüchern wiedergegeben. + + Windows-Benutzer können ein vorkonfiguriertes Installationspaket herunterladen, + welches die Software openVPN installiert und fertig konfiguriert. + + Linux-Benutzer müssen die Software openVPN installieren + und dann eine einfache Konfigurationsdatei einspielen, um Verbindungen zum Firebird-Netzwerk zu ermöglichen. + Diese Konfigurationsdatei ist alles, was Linux-Benutzer herunterladen müssen. + + Die Server-IP, Benutzernamen und -kennwörter werden in einer E-Mail an Sie versendet, sobald Sie nach + Upload-Rechten fragen. Bitte beachten Sie das diese Daten spezifisch auf Sie zugeschnitten sind - niemand + sonst kann Ihre Daten verwenden. +
+ +
+ Download durchführen + + Unabhängig davon, ob Sie Windows oder Linux verwenden, Sie müssen erst + eine Verbindung zum Server mittels der Ihnen per E-Mail übermittelten Benutzerdaten herstellen. + + + Sobald Sie sich mit Ihrem übermittelten Benutzerdaten eingeloggt haben, sehen Sie zwei Dateien: + + + + XXXX_Firebird_VPN_config.zip + + + + XXXX_Firebird_VPN_setup.exe + + + + Die Zip-Datei ist nur für Linux-Benutzer, die Exe für Windows-Benutzer. Der + 'XXXX'-Teil des Dateinamens variiert und ist benutzerspezifisch für Ihre Benutzung angepasst. + Der Dateiname beginnt typischerweise mit Ihrem Namen - welcher inkorrekt dargestellt werden kann, so + wie es meiner war - aber machen Sie sich keine Gedanken hierüber. Der Dateiname + macht keinen Unterschied bezüglich des Inhalts. + + + Windows-Benutzer müssen Windows XP, Windows 2000 - oder eine höhere Version verwenden. + + + Die Windows-Datei ist um die 2 MB groß, da sie sowohl den Installer als auch die Konfigurationsdateien enthält. + Die Linux-Datei beinhaltet Ihr persönliches Zertifikat, jedoch keinen Installer. Es ist dementsprechend klein! +
+ +
+ Installation + + Der Installationsvorgang ist für Windows- und Linux-Benutzer unterschiedlich. + Bitte beachten Sie den entprechenden Abschnitt weiter unten. + + Sobald vollständig durchgeführt, wird das System so konfiguriert sein, dass + Sie sich mit dem Firebird-Server verbinden können. Der Server hat die IP-Adresse 192.168.2.2. + Das heißt, wenn Sie ein Netzwerk mit dem gleichen Adressraum verwenden, werden Sie nicht in der + Lage sein, sich zum Server zu verbinden, wenn es ein Gerät mit der IP-Adresse 192.168.2.2 in Ihrem + Netzwerk gibt. + + Die schnelle Lösung hierfür ist, dass Sie Ihren Router so konfigurieren, dass er nur + Adressen oberhalb von 192.168.2.2. vergibt - somit verhindern Sie, dass andere Geräte + mit dem Firebird-Server kollidieren, wenn Sie eine Verbindung aufbauen möchten. + + In meinem eigenen Netzwerk zum Beispiel, habe ich den Router so konfiguriert, dass er nur + Adressen oberhalb von 192.168.2.10 vergibt. Ich habe die Adressen unterhalb für Dinge reserviert, + die eine permanente IP benötigen - mein Drucker, zum Beispiel, steht hart auf + 192.168.2.4. Glücklicherweise verwendete bis dato nichts 192.168.2.2. + +
+ Windows-Installation + + Sobald Sie die Setup-Datei, wie oben beschrieben, heruntergeladen haben, klicken Sie einfach doppelt + auf die Setup-Datei, um den Installationsvorgang zu starten. + + Sie müssen Windows XP, Windows 2000 oder eine höhere Version verwenden - Vista, Windows 7 Windows 2003 etc. + OpenVPN ist nicht unter einer älteren Version (älter als XP oder Windows 2000) lauffähig. + + + Sie benötigen außerdem lokale Administrationsrechte, um einige Installationsteile durchführen zu können. + + Führen Sie einen Rechtsklick auf die Setup-Datei aus und wählen Sie Ausführen als Benutzer... + und dann als Administrator ausführen. + + + Sobald der Installer läuft, werden Sie durch einige verschiedene Installerseiten geführt, wenn Sie auf next + klicken. Halten Sie sich an den folgenden Ablauf: + + + + Auf der Welcome-Seite - klicken Sie auf + next. + + + + Auf der License-Seite - klicken Sie + accept. Wenn Sie mit der Lizenz nicht einverstanden sind, + verlassen Sie den Installer. + + + + Auf der Choose Components-Seite - alle Optionen + sind standardmäßig ausgewählt und Sie sollten hier einfach auf + next klicken. + + + + Auf der Install Location-Seite - wählen Sie einen Dateipfad + für Ihre Installation. Der Standardwert ist c:\program files\openVPN (oder + c:\program files + (x86)\openVPN auf Windows 7). Klicken Sie auf + install. + + Während der Installation kann es passieren, dass Ihre Firewall Sie über den Installer informiert. + Wenn dem so ist, erlauben Sie dem Installer den Internetzugriff. Möglicherweise erhalten Sie weitere Hinweise + zu Komponenten, die der Installer installieren möchte. Für diese muss der Internetzugriff ebenfalls gewährt werden. + + Windows wird Sie darauf hinweisen, dass das laufende Programm keine + Windows Logo zertifizierte Anwendung ist. Klicken Sie zum Fortfahren auf dennoch installieren. + + Unter Windows 7, wird der Prompt + Der Herausgeber dieses Treibers kann nicht verifiziert werden... ausgeben. + Klicken Sie auf Treibersoftware trotzdem installieren. + + + + Auf der Install Complete-Seite - klicken Sie auf + Next. + + + + Klicken Sie abschließend auf finish. + + + + Die openVPN-Anwendung läuft noch nicht. Wenn alles erfolgreich war, können Sie zum Starten + auf + Start -> Alle Programme -> openVPN -> + openVPNGUI klicken. + + Sobald openVPN läuft, werden Sie ein neues Symbol in Ihrem + System-Tray sehen. Wenn das Symbol rot eingefäbt ist, sind Sie nicht verbunden, wenn es grün dargestellt wird, + sind Sie verbunden. Ein Doppelklick auf das Symbol öffnet den Verbindungsdialog, genauso wie es ein Rechtsklick tut. Klicken + Sie zum Herstellen der Verbindung auf Connect im Menü. + + Wenn Sie versuchen eine Verbindung herzustellen, kann es sein, dass Ihre Firewall nach + der Erlaubnis für den Internetzugriff durch openvpn.exe fragt. + Erlauben Sie diese und sagen Sie Ihrer Firewall, dass diese Berechtigung auch zukünftig gilt. + + Um die Verbindung von openVPN zu trennen, klicken Sie doppelt auf das grüne + openVPN-Symbol oder klicken Sie mit der rechten Maustaste hierauf und wählen + Sie den Menüeintrag disconnect. + + Sie sind nun in der Lage die Installation zu testen. Stellen Sie sicher, dass + openVPN läuft. +
+ +
+ Linux-Installation + + Öffnen Sie eine Terminalsitzung und, unter Ihrem eigenen Benutzer, geben Sie den Befehl + whereis openvpn ein. Die Ausgabe sieht ähnlich der folgenden, wenn die Software + openVPN bereits installiert ist: + + $ whereis openvpn +openvpn: /usr/sbin/openvpn /etc/openvpn.conf <other stuff> + + And, if not, the result will be as follows: + + $ whereis openvpn +openvpn: + + Wenn die Software bereits installiert ist, können Sie die folgenden Abschnitte überspringen + und zum Kapitel Linuxkonfiguration übergehen. + +
+ Ubuntu, Linux Mint etc + + Für Ubuntu und Derivate, ist der Vorgang zum Installieren von + openVPN wie folgt: + + + + Klicken Sie auf System -> Administration -> + Synaptic Package Manager, wenn Sie unter Ubuntu arbeiten, oder unter Linux Mint auf + Menu ->Package Manager. Dies startet den Software Paketmanager. + + + + Geben Sie Ihr eigenes Kennwort ein, wenn Sie danach gefragt werden. + + + + Im Schnellsuche-Eingabefeld, geben Sie + openvpn ein und klicken Sie dann auf + suchen. + + + + In der erscheinenden Paketliste, suchen Sie den Eintrag + openvpn und haken Sie die Checkbox am Zeilenbeginn an. + + + + Sie werden gefragt Für Installation vormerken. Tun Sie dies. + + + + Klicken Sie auf Mark für die außerdem benötigten Pakete, wenn der + Dialog erscheint. + + + + Klicken Sie auf Übernehmen. + + + + Bestätigen Sie den abschließenden Dialog. + + + + Warten Sie ... + + + + Klicken Sie zum Abschluss auf + Schließen. + + + + Die Paketliste zeigt nun, dass + openVPN in Version + 2.1~rc19-lubuntu2 (in meinem Fall) installiert wurde. + Dies unterscheided sich offensichtlich von anderen + openVPN-Versionen, die für Ubuntu, etc. entwickelt werden. + + + + Schließen Sie den Paketmanager. + + +
+ +
+ OpenSuse + + Für OpenSuse stellt sich der Installationsvorgang für + openVPN wie folgt dar: + + + + Drücken Sie ALT und F2 gleichzeitig, um auf die Befehlszeile zu wechseln. + + + + Geben Sie yast ein und drücken Sie Enter. + + + + Geben Sie das root-Kennwort ein, wenn Sie danach gefragt werden. + + + + Klicken Sie auf Software im linken Bereich. + + + + Klicken Sie auf Software Management im rechten Bereich. + + + + Geben Sie im Suchenfeld openvpn ein und klicken Sie auf + suchen. + + + + Wenn die Liste der relevanten Pakete erscheint, scrollen Sie zum Paket mit Namen + openvpn. + + + + Klicken Sie mit der rechten Maustaste auf diesen Eintrag und wählen Sie + installieren aus dem Menü. + + + + Klicken Sie auf Übernehmen. + + + + Folgenden Sie den Anweisungen, um von der korrekten CD, DVD, etc. zu installieren, wenn notwendig. + + + + Schließen Sie den Softwaremanager. + + +
+ +
+ Linux-Konfiguration + + Sobald Sie die Softare installiert haben, können Sie die Konfiguration vornehmen. + Dies ist ein simpler Vorgang und beinhaltet nichts schwierigeres als ein Verzeichnis anzulegen + und die heruntergeladene Zip-Datei zu entpacken. + + Dies ist der Prozess: + + + + Wechseln Sie in ein passendes Verzeichnis, wo Sie die Konfigurationsdateien für + openVPN erstellen möchten. + + $ cd ~ + + + + Erstellen Sie ein Verzeichnis. + + $ mkdir -p Firebird/VPN + + + + Kopieren Sie die heruntergeladene Zip-Datei in ein neues Verzeichnis. + + $ cd Firebird/VPN +$ cp <dowload location>/*_Firebird_VPN_config.zip ./ + + + + Extrahieren Sie die benötigten Dateien. + + $ unzip *.zip +... + + + + Sie besitzen nun alle benötigten Dateien, um eine VPN-Verbindung zum Firebird-Netzwerk aufzubauen. +
+ +
+ OpenVPN starten + + OpenVPN läuft nicht automatisch nach dem Linux-Start. + Sie müssen es selbst starten, wenn Sie es benötigen. Starten Sie das Programm als Benutzer + root, da es auf dynamische Art Dateien im Verzeichnis /dev. + Der folgende Befehl wird innerhalb einer Terminalsitzung aufgerufen. Wir gehen davon aus, dass Sie + unter Ihrem eigenen Benutzer arbeiten. Der Vorgang funktioniert ebenfalls anstandslos unter Ubuntu, Linux Mint, oder + anderen Linux-Installationen, bei denen es keinen dedizierten root-Benutzer gibt. + + $ cd ~Firebird/VPN +$ su -c "/usr/sbin/openvpn --config `pwd`/firebirdsql-project.ovpn" + + Alternativ können Sie openVPN + jederzeit folgendermaßen starten: + + $ su -c "/usr/sbin/openvpn --config \ +~/Firebird/VPN/untangle-vpn/firebirdsql-project.ovpn" + + Egal welchen Befehl Sie auch immer verwenden mögen, Sie werden nach einem Kennwort gefragt. + Auf Ubuntu-ähnlichen Systemen ist das Kennwort Ihr eigenes. Wenn Sie OpenSuse verwenden, ist es das root-Kennwort. + + An diesem Punkt wird die Bash-Sitzung nach vielen Textmeldungen stehen bleiben und mit folgender Zeile abschließen: + + ...Initialisation Sequence Completed + + openVPN läuft nun und hat einen Tunnel zum Firebird-Netzwerk aufgebaut. + Sie sind nun in der Lage das System zu testen. +
+
+
+ +
+ Test + + Zum Testen Ihrer Installation, verwenden Sie eine Befehlszeilenversion von FTP. Dies ist schnell und einheitlich unter Linux und Windows. + Dies ist der Vorgang: + + + + FTP-Verbindung zum Firebird-Server aufbauen: + + $ ftp 192.168.2.2 +Username: <as supplied> +Password: <as supplied> +230 logon successful +Remote system type is UNIX +Using binary mode to transfer files + + + Der Verbindungsaufbau kann einen Moment dauern. Er ist etwas langsamer als beim alten Server. + Dies scheint eine kleine Störung im System zu sein, die aber sicher in naher Zukunft behoben wird. + + + + Wechseln Sie zum PDF-Verzeichnis: + + ftp> cd htdocs/devel/doc/manual/pdf + + + + Listen Sie die Verzeichnisinhalte auf: + + ftp> ls +... + + + + Sie haben nun ein funktionierendes VPN-System und können es nutzen, um komplette Dokumente in + das Firebird-Netzwerk zu laden. +
+
+ + + Dokumenthistorie + + Die exakte Dateihistorie kann über das manual Modul im CVS Baum abgerufen werden; http://sourceforge.net/cvs/?group_id=9028 + + + + 1.0 + + 30 March 2010 + + ND + + + Neues Handbuch erstellt. + + + + 1.0-de + + 22. Aug 2013 + + MK + + + Übersetzung ins Deutsche. + + + + + + + Lizenzhinweise + + Der Inhalt dieser Dokumentation unterliegt der "Public Documentation + License Version 1.0" (der Lizenz); die Dokumentation darf + nur unter Respektierung dieser Lizenz genutzt werden. Kopien der Lizenz + sind verfügbar unter http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) und http://www.firebirdsql.org/manual/pdl.html + (HTML). + + Die Original-Dokumentation trägt den Titel Firebird Backup File + Splitting Filter. + + The Initial Writer of the Original Documentation is: Norman Dunbar. + + Copyright (C) 2010. All Rights Reserved. Initial Writer contact: + NormanDunbar at users dot sourceforge dot net. + + Übersetzung ins Deutsche: Martin Köditz. + + Übersetzung ins Deutsche Copyright (C) 2013: Alle Rechte vorbehalten. Kontakt: martin dot koeditz at it-syn dot de. + +
diff --git a/src/docs/firebirddocs-de/font-embedding-de.xml b/src/docs/firebirddocs-de/font-embedding-de.xml new file mode 100644 index 00000000..1059805d --- /dev/null +++ b/src/docs/firebirddocs-de/font-embedding-de.xml @@ -0,0 +1,695 @@ + +
+ + Verwendung von nicht-westlichen Zeichensätzen in den Firebird-Dokumentationen + + Verwendung von nicht-westlichen Zeichensätzen + + Eine Anleitung zum Einbetten von Schriftarten für Firebird Dokumentenersteller und Übersetzer + + + Paul + + Vinkenoog + + + + Martin + + Köditz + + Übersetzung ins Deutsche + + + 20. Juli 2013 – Version 1.3.1-de - deutsche Version + + +
+ Einleitung + + Wenn Sie nicht-westliche Zeichensätze in Ihrer Firebird-Dokumentation verwenden, + wird die HTML-Version wahrscheinlich gut aussehen. Moderne Browser werden kaum Probleme mit diversen Sprachen und Schriften haben, + solange die notwendigen Schriftarten auf dem System vorhanden sind. Möchten Sie nun aber die PDF-Version erstellen, müssen einige Punkte beachtet werden: + + + + Finden Sie die Schriften, die für body-Texte, Titel und Monospaced-Schriften benötigt werden. + + + + Überschreiben Sie die Standard-Fonts, die in den Stylesheets angegeben sind. + + + + Erstellen Sie Metric-Dateien für die Schriften, die Sie verwenden wollen. + + + + Erstellen Sie eine FOP-Benutzerdatei mit den Anleitungen zum Einbetten der Schriften. + + + + Erstellen Sie die PDF. Wenn alles so läuft wie es soll, führen Sie einen Commit der Schritte 2 bis 4 in das CVS durch. + + + + Wenn Sie die erste Person sind, die eine Dokumentation in einer Sprache erstellt, müssen Sie alle o.a. Schritte durchführen. Ist dies nicht der Fall, können Sie ein existierendes Setup verwenden. + Möglicherweise müssen Sie die FOP-Benutzerkonfigurationsdatei bearbeiten, da die Orte der Schriftdateien von System zu System unterschiedlich sein können. Siehe auch Wichtig-Kasten Schritt 4. + + Es wird vorausgesetzt, dass Sie bereits mit der Arbeit mit DocBook XML-Dateien in Ihrer eigenen Sprache vertraut sind. + Speichern Sie die Dateien in einer Unicode-Codierung, beispielsweise UTF-8. XMLMind, SciTE, Windows Notepad und andere Editoren haben keine Probleme hiermit + (XMLMind speichert standardmäßig in UTF-8). ConText hingegen kann Unicode nur als UTF-16 speichern, aber soweit bekannt, stellt auch das kein Problem für die Build-Tools dar. +
+ +
+ Wie werden PDF-Dateien erstellt? + + Um die auszuführenden Schritte besser zu verstehen, folgt nun ein kurzer Überblick, wie Ihr DocBook-Quelltext zu PDF konvertiert wird. + + + + Schritt 1: DocBook -> XSL-FO + + + Ein sogenannter XSL transformer mit dem Namen + Saxon liest den DocBook XML-Quelltext, wandelt ihn ins + XSL-FO-Format und speichert ihn im Verzeichnisbaum unter manual/inter/fo. Das FO in XSL-FO + steht für Formatting Objects. Wie DocBook selbst, + ist dies ein XML-Format, jedoch anzeigeorientiert. Nachstehend ein typischer Auszug von XSL-FO: + + <fo:block keep-together="always" margin-left="0pc" + font-family="sans-serif,Symbol,ZapfDingbats"> + <fo:block font-family="sans-serif" font-weight="bold" + keep-with-next.within-column="always" + space-before.minimum="0.8em" space-before.optimum="1.0em" + space-before.maximum="1.2em" + color="darkblue" text-align="start"> + <fo:block font-size="19.8pt">SQL Syntax</fo:block> + </fo:block> +</fo:block> + + Das Saxon-Tool finden Sie unter + manual/lib/saxon.jar. Um verstehen zu können + wie wir die DocBook-Teile zu XSL-FO konvertieren möchten, lädt Saxon ebenfalls die Transformations-Stylesheets. Die Standard-DocBook-Stylesheets befinden sich in manual/src/docs/docbook, die eigenen Anpassungen in + manual/src/docs/xsl. + + In diesem ersten Schritt wird die DocBook -> XSL-FO + Transformation vom fo build-Target ausgeführt. Wenn Sie den Befehl build pdf... + eingeben, wird das fo-Ziel bereits intern aufgerufen, Sie können es jedoch auch explizit starten, um nur die XSL-FO-Dateien zu bauen, ohne die Erstellung des PDFs. + + + + + Schritt 2: XSL-FO -> PDF + + + Die XSL-FO-Datei wird zum PDF konvertiert. Dies geschieht durch das Werkzeug Apache + FOP (Formatting Objects Processor). Das Ergebnis wird im Verzeichnisbaum unter manual/dist/pdf gespeichert. Weder Stylesheets noch die originale DocBook-Quelle sind hiervon betroffen. Apache FOP + ist zu finden in manual/lib/fop.jar. + + Dieser Schritt wird ausgeführt mittels des fo2pdf + build target. Auch dieses wird intern vom + pdf target aufgerufen. Aber auch hier können Sie die .fo-Dateien selbst bearbeiten (was manchmal notwendig ist). + + + + + Die folgenden Abschnitte, werden durch die in der Einleitung beschriebenen Schritte führen. + Die Tabelle zeigt, welcher der jeweiligen Schritte den DocBook-to-PDF Erstellungsprozess beeinflusst: + +
+ + + + + + + + + + + Schritt + + Beschreibung + + Beeinflussungen + + + + + + 1 + + Finden der benötigten Schriftarten + + (vorbereitender Schritt) + + + + 2 + + Überschreiben Stylesheet-Fonts + + Schritt 1: XSL-FO-Erstellung + + + + 3 + + Erstellung der Metric-Dateien + + Schritt 2: PDF-Erstellung + + + + 4 + + Erstellung der FOP-Benutzerkonfigurationsdatei + + Schritt 2: PDF-Erstellung + + + + 5 + + PDF "bauen" und commiten + + (Letzter Schritt – der eigentliche Erstellvorgang) + + + + +
+
+ +
+ Schritt 1: Finden der benötigten Schriftarten + + 1: Finden der benötigten Schriftarten + + Die DocBook-Stylesheets unterscheiden zwischen sechs Schriftfamilien: für body, title, monospaced, symbol, dingbat und + sans (= sans-serif) text. Sie sind wie folgt definiert: + +
+ body.font.family = serif +title.font.family = sans-serif +monospace.font.family = monospace +symbol.font.family = Symbol,ZapfDingbats +dingbat.font.family = serif +sans.font.family = sans-serif +
+ + Die sans.font.family wird in der Praxis nicht verwendet. Sie wird nur der Vollständigkeit halber aufgelistet. Die symbol- und dingbat-Familien werden vermutlich nicht + verändert. Das bringt uns dazu, passende Fonts für body, title und monospace zu finden. + + Für englische und andere westliche Sprachen wird serif + zu Times New Roman im PDF, sans-serif zu + Helvetica/Arial und monospace zu Courier. Diese Schriftarten, ebenso der Symbol-Fonts, werden von allen Adobe PDF-Readern unterstützt. + Deshalb müssen westliche Docwriter keine speziellen Anstrengungen unternehmen, damit ihre Sprache korrekt dargestellt wird. Die meisten nicht-westlich orientierten Zeichen sind hingegen + nicht Teil der Adobe Standardfonts. Wenn Sie die Schriftarten nicht selbst einbetten, werden die Tools das PDF ohne Meckern erstellen, die unbekannten Zeichen werden jedoch durch ein + # ersetzt. Ihr Text sieht dann möglicherweise so aus: #### + ## #### #### ##### ## ## #####. + + Sie sind gut beraten, Schriftarten zu verwenden, die allgemein auf Computersystem vorhanden sind, zumindest innerhalb Ihrer Lokalisierung. + Metrics und Konfigurationsdaten werden ins CVS committet und sind durch andere Docwriter nutzbar, jedoch nicht die Schriftarten selbst. Diese müssen auf dem System des Benutzers vorhanden + sein, wenn ein PDF erstellt werden soll. (Hinweis: Nur beim + Erstellen, nicht beim + Lesen!) + + Wenn Ihre Sprache oder Schriften keinen Unterschied zwischen serifen- + und nicht-serifen-Fonts macht, wählen Sie die gleiche Schriftart für den body und die title-Familien – oder verwenden Sie eine Auswahl, die Ihrer Sprache angemessen ist. + Versuchen Sie jedoch nicht einen anderen Font für die monospace-Familie zu verwenden, auch wenn der Unterschied zwischen proportionalen und nicht-proportionalen + Schriftarten in Ihrem Fall bedeutungslos scheint. Monospaced wird häufig verwendet, um Wörter in Sätzen hervorzuheben. + + Jeder gewählte Font sollte diese Schrifteffekte unterstützen: normal, + italic (kursiv), bold (fett), und bold italic (fett-kursiv). (Nur wenn dies für Ihre Sprache relevant ist.) + Manchmal werden diese Unterschiede innerhalb einer Font-Datei vorgehalten, manchmal sind sie über bis zu vier Dateien verstreut. + Nutzen Sie nur Type 1- und TrueType-Fonts. + + Aufgrund der erheblichen Unterschiede zwischen den weltweit vorhandenen Sprachen und Schriften, ist es unmöglich eine spezifische Anweisung diesbezüglich zu geben. + Fühlen Sie sich frei, jederzeit Probleme oder Fragen diesbezüglich in der firebird-docs-Liste zu diskutieren. + + Sobald Sie sich für die zu verwendenden Fonts entschieden haben, notieren Sie sich die Ablageorte der Dateien. + TrueType-Dateien besitzen die Erweiterung .ttf, TrueType-Sammlungen .ttc. Type 1-Dateien besitzen die Erweiterung + .pfb (der Font selbst) und + .pfm (die Metric-Info). Zum Einbetten von + Type 1-Fonts, benötigen Sie beide Dateien, die .pfb + und die .pfm. +
+ +
+ Schritt 2: Überschreiben der Stylesheet-Schriftarten + + 2: Überschreiben der Stylesheet-Schriftarten + + Jede Font-Konfiguration wird im Verzeichnis manual/config/xx platziert, wo xx + Ihrem Sprachcode entspricht. Wenn das Verzeichnis bisher nicht existiert, erstellen Sie es. Bearbeiten Sie die Datei + fo-params.txt in diesem Verzeichnis (wenn sie noch nicht existiert, kopieren Sie sie aus manual/config). Angenommen Sie arbeiten an einem japanischen Setup und Sie haben folgende Schriftarten gewählt: + MSGothic für titles, + MSMincho für normal body text und WPJapanese um monospace zu ersetzen. + Sie würden dann die relevanten Teile der + manual/config/ja/fo-params.txt wie folgt bearbeiten: + +
+ body.font.family=MSMincho +title.font.family=MSGothic +monospace.font.family=WPJapanese +
+ + Stellen Sie sicher, dass Sie jede veränderte Zeile unkommentieren, wenn notwendig. + + Sobald die Zwischenausgabe der XSL-FO für japanisch erstellt wurde, wird das Dokument Referenzen für diese Schriftarten + enthalten, statt der Standardfonts der Stylesheets. Ein Teil der .fo-Datei könnte folgendermaßen aussehen: + +
+ <fo:block keep-together="always" margin-left="0pc" + font-family="MSMincho,Symbol,ZapfDingbats"> + <fo:block font-family="MSMincho" font-weight="bold" + keep-with-next.within-column="always" + space-before.minimum="0.8em" space-before.optimum="1.0em" + space-before.maximum="1.2em" + color="darkblue" text-align="start"> + <fo:block font-size="19.8pt">...Japanese text here...</fo:block> + </fo:block> +</fo:block> +
+ + Die nächsten zwei Schritte behandeln den folgenden Aspekt: Die eigentliche Erstellung des PDFs. +
+ +
+ Schritt 3: Erstellung der Metric-Dateien + + 3: Erstellung der Metric-Dateien + + Für jeden verwendeten nicht-Standardfonts, muss eine Datei mit Font-Metric-Informationen erstellt werden. + Apache FOP benötigt diese Infos während der XSL-FO -> PDF-Konvertierung. + Sie können die Metric-Dateien mit den t1metrics und + ttfmetrics targets Ihres Buildsystems generieren. Rufen Sie die Befehlszeile auf und wechseln Sie in das Verzeichnis + manual/src/build. Geben Sie folgendes Kommando ein + (alles in einer Zeile!): + +
+ build ttfmetrics + -Dff=D:\Path\To\fontfile.ttf -Dmf=filename.xml -Dsfx=xx +
+ + Um die TTF-Metric-Datei zu erstellen, oder + +
+ build t1metrics + -Dff=D:\Path\To\fontfile.pfm -Dmf=filename.xml -Dsfx=xx +
+ + für eine Type 1-Metric-Datei. + + Bitte beachten Sie: + + + + Sie müssen den kompletten Pfad zu Ihrem Font angeben, jedoch nur einen Dateinamen für die Metric-Datei. Letztere wird ersetzt in + manual/config/xx, + mit xx, Ihrem Sprachcode. + + + + Wählen Sie einen Dateinamen für Ihre Metric-Datei. Sinnvollerweise sollte der Name jedoch so gewählt werden, dass er Ihrem Font zugeordnet werden kann. + + + + Für das t1metrics target, müssen Sie die + .pfm-Datei verwenden, nicht die + .pfb. + + + + Das zweite Zeichen von t1metrics ist die Zahl 1 (eins), nicht der Buchstabe + el. + + + + Alternativ zum Parameter sfx können Sie auch folgendes eingeben: + -Dmf=xx/filename.xml. + + + + + Bitte berücksichtigen Sie, dass Sie diesen Schritt für jede Schriftart wiederholen müssen, die Sie hinzufügen. Wenn die fett- und/oder kursiv-Variationen + in verschiedenen Dateien stecken, müssen Sie auch je eine eigene Metric-Datei erstellen. + + + Metric-Dateien, die mit FOP 0.20.5 erstellt wurden (was Teil des Build-Tools bis April 2007 war), sind nicht mit der aktuellen FOP-Version (0.93 or higher) + nutzbar. Wenn Sie solch alte Dateien in Ihrem Verzeichnisbaum besitzen, regenieren Sie diese mit der jüngsten Tool-Version. + Bitte beachten Sie, dass Durchführung eines CVS-Updates, die aktuellen Metric-Dateien beinhalten kann. + + +
+ Schriftarten-Sammlungen + + Einige TrueType-Fonts werden in .ttc-Dateien gepackt (TrueType collections). Das + ttcmetrics target ermöglicht Ihnen die Metric-Dateien für diese Fonts folgendermaßen zu erstellen: + +
+ build ttcmetrics -Dcf=D:\Path\To\collection.ttc + -Dfn=fontname -Dmf=filename.xml -Dsfx=xx +
+ + Der ff (font file) Parameter wurde durch cf (collection file) ersetzt. + Zusätzlich gibt es den fn (font name) Parameter. Um herauszufinden, welche Fonts in einer Sammlung existieren, rufen Sie das + ttcmetrics target mit nur dem ersten Parameter auf, wie folgt: + +
+ build ttcmetrics -Dcf=D:\Path\To\collection.ttc +
+ + Die Ausgabe wird in einer Ausnahmebehandlung (exception) und einem 20 Zeilen langen Java Stack Trace resultieren. Vorher jedoch, finden Sie + eine Liste aller fonts, die die Sammlung beinhaltet. +
+
+ +
+ Schritt 4: Erstellung einer FOP-Benutzerkonfigurationsdatei + + 4: Erstellung einer FOP-Benutzerkonfigurationsdatei + + Dies ist der komplizierteste Schritt. Sie müssen die + fop-userconfig.xml-Datei bearbeiten, um FOP zu sagen: + + + + welche Schriftarten (und Variationen) eingebunden werden; + + + + wo die Schriftarten gefunden werden können; + + + + wo die Metric-Dateien gefunden werden können. + + + + Dann fangen wir mal an: + + + + Wenn notwendig, kopieren Sie die fop-userconfig.xml aus dem allgemeinen + manual/config-Verzeichnis + in Ihr Sprachverzeichnis (e.g. manual/config/ja). + + + + Öffnen Sie die Datei in einem Text- oder XML-Editor und suchen Sie nach dem Eintrag + font-base. Ersetzen + xx durch Ihren Sprachcode, so dass die URL auf das korrekte Konfigurationsunterverzeichnis zeigt. + Entfernen Sie das Kommentarzeichen! + + + + Wechseln Sie nun zum <fonts>-Element. Sie werden einige auskommentierte Beispiele finden. + + + + Fügen Sie ein <font>-Element für den ersten Font hinzu: + + <font metrics-url="msmincho.xml" kerning="yes" + embed-url="file:///D:/WINNT/Fonts/MSMincho.ttf"> + <font-triplet name="MSMincho" style="normal" weight="normal"/> +</font> + + Hinweise: + + + metrics-url + zeigt auf die Font-Metric-Datei, die Sie zuvor erstellt haben und die im gleichen Verzeichnis wie + fop-userconfig.xml liegt. + + + + embed-url muss eine URL sein, die auf die Font-Datei selbst zeigt. Aber vorsicht! Für Type 1-Fonts, + müssen Sie die .pfb-Datei angeben, nicht die + .pfm wie Sie dies beim Erstellen der Metric-Datei taten. + + + Selbst wenn das gesamte Setup bereits existiert, kann es notwendig sein, embed-url zu bearbeiten, + da es möglich ist, dass die Schriftart bei Ihnen in einem anderen Verzeichnis liegt, als bei der Peson, die den ursprünglichen CSV-Commit des Setups durchgeführt hat. + Mehr Konfigurationsänderungen sollten nicht nötig sein. + + + + + Das font-triplet name muss der gleiche sein, wie der Name, den Sie in + fo-params.txt verwendet haben, um den Standardfont zu überschreiben. + + + + + + + + Nun müssen Sie die Informationen für fett, kursiv und fett-kursiv hinzufügen. + Häufig sind diese in verschiedenen Font-Dateien zu finden und Sie werden separate Metric-Dateien erstellt haben. + Wenn dies tatsächlich der Fall ist, erhält jede Variation (fett, kursiv, fett-kursiv) ihren eigenen <font> Eintrag, zum Beispiel für fett-kursiv: + + <font metrics-url="msmincho-bi.xml" kerning="yes" + embed-url="file:///D:/WINNT/Fonts/MSMinchoBI.ttf"> + <font-triplet name="MSMincho" style="italic" weight="bold"/> +</font> + + Beachten Sie, dass font-triplet name identisch für jede Variation sein muss: + der Name, den Sie in + fo-params.txt verwendet haben. + + Manchmal existieren keine fett- oder kursiv-Varianten einer Schriftart. + In diesem Fall müssen Sie dieses faken, da die Zwischen-.fo-Datei + diese spezifizieren. Wenn die Zwischendateien nicht existieren, werden die gefürchteten ### #### ## in der PDF erscheinen. Für jede nichtexistierende + Variation, muss ein <font-triplet>-Element hinzugefügt werden, für jede Varaiante, die stattdessen werden soll: + + <font metrics-url="msmincho.xml" kerning="yes" + embed-url="file:///D:/WINNT/Fonts/MSMincho.ttf"> + <font-triplet name="MSMincho" style="normal" weight="normal"/> + <font-triplet name="MSMincho" style="italic" weight="normal"/> +</font> + + Wenn weder fett noch kursiv existieren, erhalten Sie am Ende vier + <font-triplet> Untereinträge im <font>-Element. + + + + Wiederholen Sie die Schritte 4 und 5 für jede Font-Familie, die Sie zu + fo-params.txt hinzugefügt haben. + + + + Wenn alles erfolgreich war, sollten Sie nun in der Lage sein, PDFs in Ihrer Sprache zu erstellen.. + + + Die FOP 0.20.5-Benutzerkonfigurationsdateien (die bis April 2007 verwendet wurden) + haben das falsche Format für unsere aktuelle FOP version (0.93 oder höher). + Wenn FOP sich diesbezüglich meldet, führen Sie ein CVS-Update durch. Sollte das Dateiformat dann immer noch falsch sein, prüfen Sie die Datei + manual/config/fop-userconfig.xml und geben Sie Ihrer sprachabhängigen Benutzerkonfigurationsdatei die gleiche Struktur. + +
+ +
+ Schritt 5: Erstellung des PDF und Ausführung des Commits + + 5: Erstellung des PDF und Ausführung des Commits + + Um Ihre Konfiguration zu testen, wird nun das PDF in Ihrer Sprache erstellt, z.B.: + +
+ build pdf -Drootid=qsg15-ru -Dsfx=ru +
+ + Untersuchen Sie das Ergebnis gründlich. Wenn Sie irgendwo im Dokument ### #### + ##-Zeichen finden, wird Ihnen der Anzeigeort Hinweise darauf geben, was schiefgelaufen ist: + + + + Erscheinen die Zeichen in den titles, haben Sie möglicherweise vergessen die + title.font.family in + fo-params.txt zu überschreiben und/oder die fett- oder fett-kursiv-Variationen in der Datei + fop-userconfig.xml hinzuzufügen. + + + + Wenn Sie im body erscheinen, habe Sie vermutlich die + monospace.font.family vergessen. + + + + Besteht das Dokument hauptsächlich aus + #s, die titles sind hingegen OK, haben Sie wahrscheinlich die Angabe von body.font.family vergessen. + (Dies sollte Ihnen die Schamesröte ins Gesicht treiben.) + + + + Wenn die Rauten an isolierten Stellen angezeigt werden, müssen Sie möglicherweise die Symbol- und/oder Dingbat-Familien überschreiben. + + + + Vergleichen Sie Ihr PDF mit dem englischen Original, um hilfreiche Anhaltspunkte für die Probleme zu finden. + Und natürlich gibt es da noch die firebird-docs list. + + Sobald alles läuft, führen Sie einen Commit zum CVS aus: + + + + Das manual/config/xx + Sprachverzeichnis (sofern dies noch nicht im CVS existiert). + + + + Die fo-params.txt-Datei in diesem Sprachverzeichnis. + + + + Alle .xml-Metric-Dateien im Sprachverzeichnis. + + + + Die fop-userconfig.xml-Datei im Sprachverzeichnis. + + + + Wenn Sie keine Schreibrechte für das CVS besitzen, kontaktieren Sie ein Mitglied des Unterprojektes. Dieses wird Ihnen beim Commit helfen.. +
+ +
+ Nachwort + + Wir sind noch relativ "unbeleckt" bezüglich der Übersetzung der Firebird-Dokumente zu nicht-westlichen Schriften + und ich glaube, wir haben noch viel aus der Erfahrung zu lernen. Bitte übermitteln Sie jegliche Fehlerbericht, Kommentare und Vorschläge an die + firebird-docs-List. Viel Glück bei Ihrer docwriting-Tätigkeit und Übersetzungen – Es ist großartig, Teil diese Unterprojekts zu sein! +
+ + + Dokumenthistorie + + Die exakte Dateihistorie ist im manual-Module unseres CVS-Baumes aufgenommen; Siehe http://sourceforge.net/cvs/?group_id=9028 + + + + 0.1 + + 22 Dez 2005 + + PV + + + Erste Edition. + + + + + 0.1.1 + + 23 Dez 2005 + + PV + + + Kleine Korrektur in Schritt 3-Abschnitt. + + + + + 0.1.2 + + 24 Dez 2005 + + PV + + + Inkorrekter Fontname-Anforderungen entfernt; Bemerkung über Bearbeitung der embed-file URL hinzugefügt.. + + + + + 0.1.3 + + 25 Jan 2007 + + PV + + + Wie wird das PDF erstellt: Entfernung einiger Wörte aus dem letzten Satz, direkt oberhalb der Schritte-Tabelle. + + + + + 1.0 + + 18 Apr 2007 + + PV + + + Erstelle Metric-Dateien und + Erstelle eine FOP-Benutzerkonfigurationsdatei: Auf aktuellen Stand mit FOP 0.93 gebracht. + + Nachwort: Wortführung geändert. Wir sind keine kompletten Newbies mehr :-) + + + + 1.0-de + + 21. Jul 2013 + + MK + + + + Deutsche Übersetzung basierend auf der englischen Dokumentenversion 1.0. + + + + + + + Lizenzhinweis + + Der Inhalt dieser Dokumentation unterliegt der "Public Documentation + License Version 1.0" (der Lizenz); die Dokumentation darf + nur unter Respektierung dieser Lizenz genutzt werden. Kopien der Lizenz + sind verfügbar unter http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) und http://www.firebirdsql.org/manual/pdl.html + (HTML). + + Die Original-Dokumentation trägt den Titel Using non-Western + fonts in your Firebird docs. + + Der ursprünglich Autor der Original-Dokumentation ist: Paul Vinkenoog. + + Copyright (C) 2005-2007. Alle Rechte vorbehalten. Kontakt zum + Original-Autor: paulvink at users dot sourceforge dot net. + + Übersetzung ins Deutsche: Martin Köditz. + + Übersetzung ins Deutsche Copyright (C) 2013: Alle Rechte vorbehalten. Kontakt: martin dot koeditz at it-syn dot de. + + +
\ No newline at end of file From 03d3466c55c864400132c2665e91752b486fdf08 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Fri, 13 Dec 2013 02:20:50 +0000 Subject: [PATCH 22/33] German Firebird Cache doc added and committed to release branch --- src/docs/firebirddocs-de.xml | 12 ++ src/docs/firebirddocs-de/fbcache-de.xml | 248 ++++++++++++++++++++++++ 2 files changed, 260 insertions(+) create mode 100644 src/docs/firebirddocs-de/fbcache-de.xml diff --git a/src/docs/firebirddocs-de.xml b/src/docs/firebirddocs-de.xml index 3a3d0b91..6ee9cdad 100644 --- a/src/docs/firebirddocs-de.xml +++ b/src/docs/firebirddocs-de.xml @@ -7,6 +7,7 @@ + ]> Firebird Dokumentation @@ -89,6 +90,17 @@ + + + + Firebird Interna + Firebird Interna + + + &fbcache-de; + + + diff --git a/src/docs/firebirddocs-de/fbcache-de.xml b/src/docs/firebirddocs-de/fbcache-de.xml new file mode 100644 index 00000000..4c15cf3b --- /dev/null +++ b/src/docs/firebirddocs-de/fbcache-de.xml @@ -0,0 +1,248 @@ + +
+ Firebird Database Cache Buffer + Firebird Database Cache Buffer - Funktionsweise + + 02. Januar 2010 + + Norman + Dunbar + + + Martin + Köditz + Übersetzung ins Deutsche + + 20. Juli 2013 – Version 1.3.1-de - deutsche Version + +
+ Einleitung + Firebird nutzt einen Seiten-Cache (engl. page cache), um die Seiten im Speicher vorzuhalten. + Diese sind deutlich schneller aus dem RAM zu laden als jedesmal von der Festplatte zu lesen. + Die folgende Beschreibung wie Firebird den eigenen Cache verwendet, stammt aus einem Posting von + Ann Harrison aus der Firebird-Support-Mailing-List. + Das Posting war eine Antwort auf die Frage ob es einen Weg gibt, den Speicher-Cache zu reduzieren, ohne zuviel Performance aufzugeben (engl. + if there is a way to reduce the memory cache without giving up too much performance?) + Dieses Posting bezog sich auf ein System, dass sehr lange benötigte, um aus dem Schlafmodus zu erwachen. Dies wurde als Grund vermutet, dass einige Zeit benötigt wurde, um alle + Cache-Seiten vor dem Ausführen der ersten Abfrage von der Festplatte zu lesen. Dieser Grund wurde bestätigt und der verantwortliche DBA fragte über die Liste, wie er den + Puffer soweit wie möglich reduzieren könne, zeitgleich aber noch ein vernünftig laufendes System erhielte. + Ann gab ihr Einverständnis das Posting formal als Teil des Firebird-Dokumentations-Projektes aufzunehmen. +
+
+ Der Firebird-Cache + Alles in der Datenbank ist in Seiten mit fester Größe vorgegebener Struktur abgelegt - es gibt neun verschiedene Seitentypen. Der Seiten-Cache ist ein Zwischenzustand zwischen dem "Arbeits"-Bereich und der Festplattenspeicher. + Beim Start liest Firebird die Datenbank-Header-Seite (engl. database header page), dann die erste Zeiger-Seite (pointer page) der Systemtabelle RDB$PAGES. Hiermit erfährt Firebird, + wo die Zeiger-Seiten, neben anderen Dingen, für die System- und Benutzertabellen zu finden sind. + Sobald die Anwendung auf die Datenbank zugreift, beginnt eine Transaktion. Firebird liest die Zeiger-Seiten, die erzählen wo die Daten-Seiten für die innerhalb der Transaktion betroffenen Tabellen zu finden sind. Alle Seiten wandern in den Cache und bleiben dort bis der Cache voll ist. Wenn kein Platz für eine neue Seite vorhanden ist, wird Firebird die am wenigsten genutzte Seite entfernt - nicht die erste gelesene, sondern die wenigst genutzte, die nicht geändert wurde. + Wenn ein Commit für eine Transaktion durchgeführt wird - und bei einigen anderen Dingen - schreibt Firebird die durch diese Transaktion geänderten Seiten auf die Festplatte, entfernt sie aber nicht aus dem Cache - dies verhindert, dass die Seiten nochmals eingelesen werden müssen, wenn sie baldmöglichst benötigt werden. + Mit der Zeit und etwas Glück, werden zum Schluss die am häufigsten geänderten und genutzten Seiten im Cache verbleiben - das wären Transaktions-Inventar-Seiten, Zeiger-Seiten für aktive Tabellen, die Header-Seite, die Top-Level-Indexes, etc.. Daten und Lower-Level-Index-Seiten werden rein- und rausgeladen, je nach Gebrauch - aber der Cache wird immer gefüllt sein. + Sie können die MON$-Tabellen (seit Firebird 2.1, insbesondere + MON$IO_STATS) nutzen, um herauszufinden, wie gut Ihr Cache ausgelastet ist. Sie zeigen die Anzahl der Fetches gegenüber den Reads, wie oft auf Seiten zugegriffen wurde und wie oft diese von der Festplatte gelesen wurden. Wenn die Anzahl der Reads dramatisch in die Höhe geht, haben Sie den Cache zu sehr reduziert. + Die MON$-Tabellen zeigen Ihnen außerdem die Anzahl der Marks gegen die Anzahl der Writes, welche angeben, wie oft Seiten geändert wurden gegenüber der Anzahl von Seiten, die auf die Festplatte geschrieben wurden. Wenn Sie sehen, dass die Writes in die Höhe schnellen, haben Sie vermutlich den Cache zu sehr reduziert. +
+
+ MON$IO_STATS verwenden + Wie oben bereits angegeben, kann die Tabelle MON$IO_STATS genutzt werden, um zu bestimmen, wie gut Ihr Buffer-Cache arbeitet. Die Tabelle hat folgende Struktur: + + MONS$STAT_ID + Die Statistik-ID. + + + MONS$STAT_GROUP + Die statistische Gruppe. Statistiken werden in folgende Gruppen unterteilt: + + + + 0: Die Datenbank als Ganzes. + + + 1: Attachments. + + + 2: Transaktionen. + + + 3: Statements. + + + 4: Aufrufe (Calls). + + + + MON$PAGE_READS + Die Anzahl der gelesenen Seiten. Dies sind die Seiten, die von der Festplatte und nicht aus dem Arbeitsspeicher gelesen wurden. + + + MON$PAGE_WRITES + Die Anzahl der auf die Festplatte zurückgeschriebenen Seiten. + + + MON$PAGE_FETCHES + Die Anzahl der Seiten, die aus dem Cache geleseln wurden, Gegensatz zu denen von der Festplatte. + + + MON$PAGE_MARKS + Die Anzahl der im Cache geänderten Seiten. Es ist möglich, dass nicht alle zurück auf die Festplatte geschrieben wurden. + + Um die derzeitigen Statistiken für die gesamte Datenbank zu untersuchen, verwenden wir folgende Abfrage in isql: + tux> isql employee +Database: employee + +SQL> SELECT MON$PAGE_READS, MON$PAGE_WRITES, MON$PAGE_FETCHES, MON$PAGE_MARKS +CON> FROM MON$IO_STATS +CON> WHERE MON$STAT_GROUP = 0; + + MON$PAGE_READS MON$PAGE_WRITES MON$PAGE_FETCHES MON$PAGE_MARKS +=================== =================== =================== =================== + 134 526 13851 529 + + Das erzeugte Resultat zeigt, dass: + + + 134 Seiten von der Festplatte in den Cache gelesen werden mussten. + + + 13.851 Seiten, auf der anderen Seite, wurden direkt aus dem Cache gelesen. + + + 529 Seiten im Cache, wurden auf irgendeinem Wege geändert. + + + 526 geänderte Seiten wurden vom Cache auf die Festplatte kopiert. + + + Hieraus können wir erkennen, dass obwohl eine kleine Anzahl Seiten in den Cache gelesen wurde, wir nichts tun können, um dies zu vermeiden. Sobald die Datenbank gestartet wird, ist der Cache leer, wenn aber eine Anwendung eine Verbindung herstellt, werden verschiedene Seiten gelesen und in der Cache gefüllt, wodurch physikalische Leseoperationen durchgeführt werden. In diesem Beispiel scheint es so zu sein, dass sobald Seiten im Cache vorhanden sind, diese auch relativ häufig verwendet werden. Für jeden physikalischen Read wurden ungeführ 103 Reads aus dem Cache durchgeführt. + Von den 529 aktualisierten Seiten - und dies sind sowohl System- wie auch Benutzerseiten - wurden 526 +zurück auf die Festplatte geschrieben, während 3 Seiten immer noch im Cache verbleiben, noch nicht geschrieben. + Das obige Beispiel zeigt die Performance des Caches während der Datenbanklaufzeit. Wir können dies auf unsere aktuelles Attachment herunterbrechen, indem wir die Abfrage etwas verändern. Wir holen nur die Datensätze, wo + MON$STAT_GROUP gleich 1 ist. + SQL> SELECT MON$PAGE_READS, MON$PAGE_WRITES, MON$PAGE_FETCHES, MON$PAGE_MARKS +CON> FROM MON$IO_STATS +CON> WHERE MON$STAT_GROUP = 1; + + MON$PAGE_READS MON$PAGE_WRITES MON$PAGE_FETCHES MON$PAGE_MARKS +=================== =================== =================== =================== + 0 4 87 5 + 134 520 13619 522 + + Die Interpretation der neuen Statistiken ist die gleiche wie für die gesamte Datenbank. + Wir können außerdem eine Statistikdiagnose für Transaktionen durchfühen: + SQL> SELECT MON$PAGE_READS, MON$PAGE_WRITES, MON$PAGE_FETCHES, MON$PAGE_MARKS +CON> FROM MON$IO_STATS +CON> WHERE MON$STAT_GROUP = 2; + + MON$PAGE_READS MON$PAGE_WRITES MON$PAGE_FETCHES MON$PAGE_MARKS +=================== =================== =================== =================== + 0 0 60 0 + 0 0 1 0 + 0 0 1 0 + 0 0 69 0 + 0 0 93 0 + 0 0 85 0 + 0 0 1 0 + 0 0 1 0 + + Und auch für Statements: + SQL> SELECT MON$PAGE_READS, MON$PAGE_WRITES, MON$PAGE_FETCHES, MON$PAGE_MARKS +CON> FROM MON$IO_STATS +CON> WHERE MON$STAT_GROUP = 3; + + MON$PAGE_READS MON$PAGE_WRITES MON$PAGE_FETCHES MON$PAGE_MARKS +=================== =================== =================== =================== + 0 0 1 0 + 0 0 38 0 + 0 0 4 0 + 0 0 18 0 + 0 0 158 0 + 0 0 1 0 + 0 0 1 0 + 0 0 1 0 + 0 0 1 0 + 0 0 1 0 + 0 0 0 0 + 0 0 1 0 + 1 0 12 0 + 0 0 2 0 + 3 0 1436 0 + 0 0 101 0 + 7 0 613 0 + + Schlussendlich ist es möglich - und vermutlich äußerst nützlich - die Statistiken für Ihre eigene Sitzung zu bestimmen. Sie finden Ihre Attachment-ID mittels CURRENT_CONNECTION unter der Verwendung eines Joins mit + MON$IO_STATS und der Spalte MON$STAT_ID. + SQL> SET LIST; + +SQL> SELECT T.MON$ATTACHMENT_ID, T.MON$TRANSACTION_ID, +CON> IO.MON$PAGE_READS, IO.MON$PAGE_WRITES, +CON> IO.MON$PAGE_FETCHES, IO.MON$PAGE_MARKS +CON> FROM MON$TRANSACTIONS AS T +CON> JOIN MON$IO_STATS as IO +CON> ON (IO.MON$STAT_ID = T.MON$STAT_ID) +CON> WHERE T.MON$ATTACHMENT_ID = CURRENT_CONNECTION; + +MON$ATTACHMENT_ID 12 +MON$TRANSACTION_ID 218 +MON$PAGE_READS 5 +MON$PAGE_WRITES 0 +MON$PAGE_FETCHES 66 +MON$PAGE_MARKS 0 + +MON$ATTACHMENT_ID 12 +MON$TRANSACTION_ID 217 +MON$PAGE_READS 0 +MON$PAGE_WRITES 0 +MON$PAGE_FETCHES 1 +MON$PAGE_MARKS 0 + +
+ + Dokumenthistorie + Die exakte Dateihistorie ist im manual-Module unseres CVS-Baumes aufgenommen; Siehe http://sourceforge.net/cvs/?group_id=9028 + Die vollständige URL des CVS-Logs dieser Datei kann unter dem Link http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/fbcache.xml?view=log gefunden werden. + + + 1.0 + 05. Januar 2010 + ND + + Neues Dokument auf Basis eines Postings von Ann Harrison an den Firebird-support. + + + + 1.1 + 21. Juni 2010 + ND + + Ergänzt, dass es möglich ist, + die Statistiken für die aktuelle Verbindung zu erhalten. Im Gegensatz zur vorigen Behauptung. + + + + 1.1-de + 02. September 2013 + MK + + Deutsche Übersetzung. + + + + + + Lizenzhinweis + + Der Inhalt dieser Dokumentation unterliegt der "Public Documentation + License Version 1.0" (der Lizenz); die Dokumentation darf + nur unter Respektierung dieser Lizenz genutzt werden. Kopien der Lizenz + sind verfügbar unter http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) und http://www.firebirdsql.org/manual/pdl.html + (HTML). + Die Original-Dokumentation trägt den Titel Firebird Database Cache Buffer. + Der ursprünglich Autor der Original-Dokumentation ist: Norman Dunbar unter Verwendung der durch Ann Harrison zur Verfügung gestellten Daten. + Copyright (C) 2010. Alle Rechte vorbehalten. Kontakt zum + Original-Autor: NormanDunbar at users dot sourceforge dot net. + + +
From 22dda2a28cb3b160829b894b3f2c048af5e93938 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Sat, 3 Oct 2015 20:53:10 +0000 Subject: [PATCH 23/33] Committed Japanese translation of Firebird 2.5.4 Release Notes (provided by Tsutomu Hayashi) to Release branch --- src/docs/rlsnotes-ja/rlsnotes-ja.xml | 76 +- .../rlsnotes25/APIandODS25.docbook | 1134 +++++ .../rlsnotes25/AdminFeatures25.docbook | 547 +++ .../rlsnotes-ja/rlsnotes25/BugFixes25.docbook | 3821 +++++++++++++++++ .../rlsnotes25/Compatibility25.docbook | 154 + .../rlsnotes25/ConfigParams25.docbook | 186 + src/docs/rlsnotes-ja/rlsnotes25/DDL25.docbook | 576 +++ src/docs/rlsnotes-ja/rlsnotes25/DML25.docbook | 652 +++ .../rlsnotes-ja/rlsnotes25/Engine25.docbook | 355 ++ .../rlsnotes25/GeneralNotes25.docbook | 247 ++ .../rlsnotes25/Installation25.docbook | 198 + .../rlsnotes-ja/rlsnotes25/Intl25.docbook | 131 + .../rlsnotes-ja/rlsnotes25/Licence25.docbook | 11 + .../rlsnotes25/NewFeatures25.docbook | 203 + .../rlsnotes-ja/rlsnotes25/PSQL25.docbook | 615 +++ .../rlsnotes25/PlatformPorts25.docbook | 124 + .../rlsnotes25/ReservedWords25.docbook | 51 + .../rlsnotes-ja/rlsnotes25/SQLStates.docbook | 1099 +++++ .../rlsnotes-ja/rlsnotes25/Security25.docbook | 23 + .../rlsnotes25/Utilities25.docbook | 410 ++ .../rlsnotes-ja/rlsnotes25/fbteamsr25.docbook | 148 + .../rlsnotes-ja/rlsnotes25/rlsnotes25.xml | 81 + 22 files changed, 10816 insertions(+), 26 deletions(-) create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/APIandODS25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/AdminFeatures25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/BugFixes25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/Compatibility25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/ConfigParams25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/DDL25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/DML25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/Engine25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/GeneralNotes25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/Installation25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/Intl25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/Licence25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/NewFeatures25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/PSQL25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/PlatformPorts25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/ReservedWords25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/SQLStates.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/Security25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/Utilities25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/fbteamsr25.docbook create mode 100644 src/docs/rlsnotes-ja/rlsnotes25/rlsnotes25.xml diff --git a/src/docs/rlsnotes-ja/rlsnotes-ja.xml b/src/docs/rlsnotes-ja/rlsnotes-ja.xml index 237dc99b..7e532e80 100644 --- a/src/docs/rlsnotes-ja/rlsnotes-ja.xml +++ b/src/docs/rlsnotes-ja/rlsnotes-ja.xml @@ -1,34 +1,55 @@ - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]> - Firebird Release Notes + Firebird Release Notes - Japanese @@ -45,6 +66,9 @@ &rlsnotes210; + + &rlsnotes25; + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/APIandODS25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/APIandODS25.docbook new file mode 100644 index 00000000..41cdb7cd --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/APIandODS25.docbook @@ -0,0 +1,1134 @@ + + + Firebird APIとODSの変更 + リリース2.5版 + + +
+ ODS（On-Disk Structure）の変更 + オンディスク構造体（ODS）の変更には以下のものが含まれます： + +
+ 新たなODSバージョン数 + Firebird 2.5はODS（オンディスク構造体）バージョン11.2のデータベースを作成します。 +
+ +
+ 最大ページサイズ + 最大ページサイズは従来通り16KB（16384バイト）です。 +
+ +
+ キャッシュ内の最大ページバッファ数 + データベース・キャッシュとして設定できる最大のページ数は、データベースが64bit版Firebirdで運用されているか、32bit版で運用されているかによって異なります： + + + 64bit版 :: 2^31 -1（2,147,483,647）ページ + + + 32bit版 :: 128,000ページ、つまり、バージョン2.1と同じです + + +
+
+ + +
+ API（アプリケーションプログラミングインタフェース）の拡張 + 追加されたFirebird APIは、以下の通り― + + +
+ + APIの機能でBLOBの変換が可能に + A.dos Santos Fernandes + + トラッカー・リファレンス CORE-3446 + BLOBと他のデータタイプとの双方向の変換がAPIの機能で可能になりました（XSQLVARまたはblr messages）。 + + + BLOBから異なるタイプのデータへ、また、異なるタイプからBLOBへのデータの移動が、executeおよびfetchの呼び出しで可能になりました。 + + + 入力パラメータに関しては、パラメータに文字列を置くことができるので、クライアント側からBLOBの作成・記入を行う必要がありません。 + + + 出力（executeまたはfetch）に関しては、アプリケーションがそのデータを理解し、BLOBを最長の文字列として評価するのに役立ちます。 + + +
+ +
+ + 接続文字列とキャラクタ・セット + A.dos Santos Fernandes + + 以前のバージョンは、OSやファイルシステムで使用されるキャラクタ・セットと連携する手段を持っていませんでした。Firebird 2.5は、データベースその他のファイルの名称や文字列パラメータがAPI接続要求を通じてアクセスされたとき、および／または、API接続要求に渡されたとき、その全体を見て、環境に応じた認識を行うようになりました。この変更により、FirebirdがASCIIサブセット以外のキャラクタを含むファイル名や他のパラメータを受け付け、それらを使用する性能は大幅に改善されました。 + + この機能をサポートするのはDPB接続のみ + 現在の実装では、この機能をサポートしているのはDPB（データベースパラメータブロック）を通じた接続だけです。サービスAPI（isc_spb*）の機能はサポートされていません。 + + +
+ isc_dpb_utf8_filename + 新しい接続オプションisc_dpb_utf8_filenameが導入され、これにより、Firebirdは、渡されているファイル名や他のキャラクタ・アイテムがUTF8（UTF-8）キャラクタ・セットであることを具体的に知ることができるようになりました。このオプションが使われない場合、デフォルトのキャラクタ・セットとしてOSのコードページが選択されます。 + +
+ クライアントとサーバー間の互換性 + + + 新しいクライアント、古いサーバー + + バージョン2.5以降のクライアントで2.5より前のバージョンのリモート・サーバーに接続する場合、isc_dpb_utf8_filenameオプションを使用すると、クライアントは、ファイル名をサーバーへ渡す前に、これをUTF-8からクライアントのコードページへと変換します。isc_dpb_utf8_filenameオプションはDPBから削除されます。 + クライアントとサーバーのステーション間で同じコードページが使われている時、互換性は保証されます。 + + + + + 新しいクライアント、新しいサーバー、isc_dpb_utf8_filenameオプションなし + + バージョン2.5以降のクライアントで、isc_dpb_utf8_filenameオプションを使用せずに、バージョン2.5以降のリモートサーバーに接続する場合、クライアントはファイル名をOSのコードページからUTF-8へと変換し、isc_dpb_utf8_filenameオプションをDPBに挿入します。 + + サーバーが受け取ったファイル名には特別な処理は施されません。しかし、古いクライアントの場合と違い、バージョン2.5のクライアントは、ファイル名を自動で変換し、DPBにisc_dpb_utf8_filenameオプションを自動で挿入します。いずれにせよ、ホストとクライアントが同じコードページを用いている場合には、互換性は保証されます。 + + + + + 新しいクライアント、新しいサーバー、isc_dpb_utf8_filenameオプション使用 + + isc_dpb_utf8_filenameが使用されている場合は、クライアントはファイル名を変更せずにサーバーに渡します。クライアントは常にUTF-8のファイル名をisc_dpb_utf8_filenameオプションとともにサーバーに渡します。 + + + +
+
+ +
+ コードページの変換 + Windowsでは、変換に使われるコードページはWindows ANSIです。他の全てのプラットフォームではUTF-8が用いられています。 + + ファイル名にOSのコードページやUTF-8を用いるのは、必ずしもベストな選択とは言えません。例えば、スクリプトや他のテキストファイルを別の接続キャラクタ・セットを用いたisqlなどのスクリプト実行ツールで処理する場合、複数のキャラクタ・セット（コードページ）を使用していると、ファイルを正しく編集できないことがあります。 + + 解決策：Unicodeコードポイントを使用します。これにより、クライアントのバージョンが2.5より前の場合でも、キャラクタの正しい解釈が可能になります。 + +
+ Unicodeコードポイントの使用 + 接続文字列のファイル名にある任意のUnicodeキャラクタはエンコードによりASCIIキャラクタとして擬装できるようになりました。これは、Unicodeコードポイント番号（U+XXXXの表記法に似たhexadecimal形式で記述）にプレフィックスとしてシンボル#を付すことで実現されます。 + + #XXXXのように標記します。Xは0-9、a-f、A-Fです。 + + キャラクタの一つがリテラルな#だった場合、二重のハッシュ・キャラクタ（##）か、またはコードポイント番号#0023を使用します。 + + クライアントがバージョン2.5より古い場合でも、サーバーでのハッシュ・キャラクタの解釈にはこれら新しいセマンティクスが使われます。 + +
+
+
+ +
+ + SQLSTATEコードのサポート + + W.Oliver + D.Yemanov + + + + トラッカー・リファレンス CORE-1761 + 新しいクライアントサイドAPI関数fb_sqlstate()は、エラーのステータスベクター・アイテムをSQL-2003標準の英数5文字のSQLSTATEコードへと変換するために利用できます。 + + + SQLSTATEコードはSQL CLASSの2文字とSQL SUBCLASSの3文字を連結したものを表現しています。 + + + SQL文がSQLSTATEコードを返すようになりました。 + + + isqlユーティリティがエラーについてSQLCODEではなくSQLSTATEの診断を表示するようになりました。 + + + SQLCODEでの診断は非推奨となっています—将来のリリースで廃止されます。 + + + （バージョン2.5.1）PSQLにWHEN SQLSTATE型の例外処理構文が追加されました。 + + + + SQLCODEの非推奨化 + SQLCODEは非推奨となっており、代わりにSQLSTATEを使用すべき所ですが、FirebirdではSQLCODEもこの先しばらく使うことができます。WHEN SQLCODEの例外処理のようなAPI関数isc_sqlcode()はまだサポートされています。 + + 付録A：SQLSTATEには、このリリースで使用できるSQLSTATEコードのリストと対応するメッセージ・テキストが挙げられています。 +
+ +
+ + <quote>効率的なアンプリペア</quote> + + W.Oliver + D.Yemanov + + + トラッカー・リファレンス CORE-1741 + + APIルーチンisc_dsql_free_statement()の新たなオプションDSQL_unprepare（数値4）を使うと、DSQL文ハンドルはプリペアドステートメントをアンプリペアのままにしておくことができます。 + 従来のisc_dsql_free_statement()関数は、DSQL_close（名前付きカーソルを閉じる）とDSQL_drop（文ハンドルを解放する）のみサポートしていました。 + 追加されたAPIは次の通り： + +#define DSQL_close 1 +#define DSQL_drop 2 +#define DSQL_unprepare 4 + +
+ +
+ + オペレーション関数のキャンセル + AlexPeshkov + + 新しいAPI呼び出しfb_cancel_operation()を使うことで、所与の接続中に、ある種のブロッキングAPI呼び出しが実行している現在のアクションをキャンセルすることができます。 + + 構文 + + ISC_STATUS fb_cancel_operation(ISC_STATUS* status_vector, + isc_db_handle* db_handle, + ISC_USHORT option); + + + パラメータ + + + + status vector (ISC_STATUS* status_vector) + + 通常のステータスベクター・ポインタ構造体です。 + + + + + db_handle (pointer to a isc_db_handle) + + 通常の、有効なデータベースハンドルです。アタッチメントを特定します。 + + + + + option (unsigned short: symbol) + + 実行されるアクションを確定します。オプション・シンボルは以下の通り： + + + fb_cancel_raise：第二のパラメータで指定されたdb_handleに関連する任意のアクションをキャンセルします。この効果として、できるだけ早い時点でエンジンが継続中のリクエストを止め、中断されたAPI呼び出しのステータスベクターを介して呼び出し元に例外を返せるようになります。 + できるだけ早い時点とは、通常は、次の再スケジューリング・ポイントのことです。 + + 例 + + +Thread1: Thread2: +------------------------------ ------------------------------ + +isc_dsql_execute(status, ....) +........ fb_cancel_operation(cancel_status, ...) +status[1] == isc_cancelled; cancel_status[1] = 0; + + + + + fb_cancel_disable：指定されたアタッチメントに関するfb_cancel_raiseリクエストの実行を無効にします。例えばcleanupなど、プログラムが重要なオペレーションを実行している時に役立つ可能性があります。 + + + fb_cancel_enable：前に無効化されたキャンセル実行の通知を再び有効にします。'cancel'状態はデフォルトで有効であり、アタッチメントが作成された時に初期化されます。 + + + fb_cancel_abort；クライアント側で接続を強制的に閉じます。接続をすぐに閉じる必要がある場合は役に立ちます。サーバーは実行中の全てのトランザクションをロールバックします。'Success'の場合は常にアプリケーションに返されます。注意して使用して下さい！ + + + + + +
+ 使い方 + fb_cancel_disableとfb_cancel_enableリクエストのサイクルは、必要な頻度で繰り返すことができます。エンジンがすでにリクエストされた状態にある場合は、例外は発生しません：単に無視されます。 + + 長時間にわたるリクエストを停止する必要がある場合、通常、fb_cancel_raiseが呼び出されます。これは非同期シグナルに対して安全ではないため、シグナルハンドラからではなく、個別のスレッドから呼び出されます。 + + このAPI呼び出しが非同期な特性を持つことに注意して下さい！ + + + 非同期な実行の別の側面として、API呼び出しの終了時にアタッチメントの活動がキャンセルされることもあれば、されないこともあり得ます。後者の可能性は常にあります。また、非同期性により、返されるステータスベクターがほとんどの場合FB_SUCCESSを返すことになります。とはいえ、例外が発生することはあります：ネットワークパケット・エラーなど。 + + 例 + +Thread A: +fb_cancel_operation(isc_status, &DB, fb_cancel_enable); +isc_dsql_execute_immediate(isc_status, &DB, &TR, 0, "long running statement", 3, NULL); +// waits for API call to finish... + + Thread B: + fb_cancel_operation(local_status, &DB, fb_cancel_raise); + +Thread A: +if (isc_status[1]) + isc_print_status(isc_status); // will print "operation was cancelled" + +
+
+ +
+ + シャットダウン関数 + AlexPeshkov + + + このリリースでは、エンベデッドサーバー・アプリケーションで有用となる二つのfb_shutdown*関数が公開されました：：fb_shutdown()とfb_shutdown_callbackです。 + +
+ 関連する二つのfb_shutdown* 関数 + このリリースでは、埋め込みサーバー・アプリケーションで有用となる二つのfb_shutdown*関数が公開されました：：fb_shutdown()とfb_shutdown_callbackです。 + + プロトタイプ + + typedef int (*FB_SHUTDOWN_CALLBACK)(const int reason, const int mask, void* arg); + + int fb_shutdown(unsigned int timeout, + const int reason); + + ISC_STATUS fb_shutdown_callback(ISC_STATUS* status_vector, + FB_SHUTDOWN_CALLBACK callback_function, + const int mask, + void* arg); + + +
+ fb_shutdown() + fb_shutdown()はさまざまなFirebirdサブシステム（yValve、エンジン、リダイレクタ）をスマートにシャットダウンさせます。これは主に内部エンジンが使うために設計されたもので、現在のプロセスにのみ適用できます。これはAPIによってエンベデッドサーバー環境でユーザーアプリケーションに利用していただくことが可能です。 + 今はエンベデッドエンジンでしか使えませんが、この関数は、現在の全ての活動を停止し、実行中のトランザクションをロールバックし、アクティブなアタッチメントを遮断し、エンベデッドエンジン・インスタンスを穏やかにシャットダウンします。 + + アプリケーション開発者向けの注意 + fb_shutdown()は、アプリケーションが同時にアタッチされる可能性があるリモートサーバーのシャットダウンを実行しません。実際に、Firebirdの全てのクライアント・ライブラリ—エンベデッドサーバーを含む—は、最低一つでもデータベースまたはサービスにクライアントがアタッチされていれば、これをexit()で自動的に呼び出します。 + 従って、リモートのアタッチメントの文脈では、これがクライアントによって呼び出されることは決してありません。 + + + パラメータ + fb_shutdown()は二つのパラメータを取ります： + + + ミリ秒でのタイムアウト + + + シャットダウンの理由 + 理由コード（const int reason）は負の値を取りますが、ibase.hにリストが挙げられています： fb_shutrsnで始まる定数を参照して下さい。 + + プログラムからfb_shutdown()を呼び出す際には正の値を渡す必要があります。これは、適切なアクションがコーディングされたコールバック関数ルーチンを通じて、fb_shutdown_callback()に引数として渡されます。 + + + + + 戻り値 + + + 戻り値ゼロはシャットダウンの成功を意味します。 + + + ゼロ以外の戻り値は、シャットダウン中に何らかのエラーが発生したことを意味します。詳細はfirebird.logに書き込まれます。 + + +
+ +
+ fb_shutdown_callback() + fb_shutdown_callback()はシャットダウン中に呼び出されるコールバック関数を設定します。この呼び出しはほとんどの場合正常終了の値を返しますが、メモリ不足の状態などでエラーが返されることもあります。 + + パラメータ + fb_shutdown_callback()は四つのパラメータを取ります： + + + status vector (ISC_STATUS* status_vector) + + 通常のステータスベクター・ポインタ構造体です。 + + + + + pointer to callback function (FB_SHUTDOWN_CALLBACK callback_function) + + これは、コールバックが発生した時に取るべきアクション（あるならば）を実行するため記述しておいたコールバック関数を参照します。 + コールバック関数は三つのパラメータを取ることができます。第一と第二のパラメータはコールバックの際に取るべきアクションを決めるのに役立ちます： + + + シャットダウンの理由 + シャットダウンの理由として二つのものが特に重要です： + + + fb_shutrsn_exit_called：exit()により、またはクライアント／エンベデッドライブラリがアンロードされることにより、Firebirdは終了します。 + + + fb_shutrsn_signal、POSIXのみ適用：SIGINTまたはSIGTERMシグナルを受信した場合です。 + + + + Firebirdは常に負の理由コードを使いますが、ユーザーがfb_shutdown()そのものを呼び出す際には正の値を使用することが求められます。 + + + + 呼び出しに用いられるマスクの実際の値 + このパラメータの用途は、コールバックを呼び出すのをエンジンのシャットダウンの前にするか後にするかを決めるのに役立つということです。 + + + ユーザーアプリケーションによってfb_shutdown_callback()に渡される引数 + これは任意の目的で使用でき、NULLにすることもできます。 + + + + +   + コールバック関数からの戻り値 + + + コールバック関数がゼロを返した場合、これはジョブが正常に終了したことを意味します。ゼロ以外の戻り値は、コールマスク（下記のパラメータに関する項目を参照）に従って解釈されます： + + + fb_shut_postproviders呼び出しの場合、何らかのエラーが発生してfb_shutdown()からゼロ以外の値が返されていることを意味します。エラー状態が返された正確な理由の通知はコールバック関数が担うことになります。 + + + fb_shut_preprovidersコールの場合、シャットダウンが実行されないことを意味します。 + + exit()が呼び出されてシャットダウンが実行される場合、ゼロ以外の値を返すのは良い考えではありません！ ;-) + + + + + + + + コールマスク（const int mask） + + 以下のシンボル記号値を持つことができます： + + + fb_shut_preproviders：コールバック関数はエンジンがシャットダウンされる前に呼び出されます + + + fb_shut_postproviders：コールバック関数はエンジンがシャットダウンされた後に呼び出されます + + + 両者を論理和で結合した場合は、シャットダウンの前後に同じ関数が呼び出されます + + + + コールマスクの値 + + + fb_shut_confirmation + + エンジンが質問：みんなシャットダウンの準備はできているかい？ + + + + fb_shut_preproviders + + プロバイダが終了する前に実行されるアクション + + + + fb_shut_postproviders + + プロバイダが終了した時に実行されるアクション + + + + fb_shut_finish + + 最終的なクリーンアップ + + + + fb_shut_confirmation（fb_shut_preprovidersではないのですが）に対してゼロ以外の値が返されることは、シャットダウンが実行されないことを意味します。 + + + + + + 引数（void* arg） + + これは、コールバック関数に渡される引数です。 + + + +
+ +
+ fb_shutdown関数の使い方 + 以下に挙げたのは、シャットダウンとシャットダウンのコールバック機能の使用サンプルです。これは、データベースのアタッチメントがある時に誰かがCtrl-Cを押すことでプログラムが終了されてしまうことを防ぐためのものです。 + + +#include <ibase.h> + +// callback function for shutdown +static int ignoreCtrlC(const int reason, const int, void*) +{ + return reason == fb_shutrsn_signal ? 1 : 0; +} + +int main(int argc, char *argv[]) +{ + ISC_STATUS_ARRAY status; + if (fb_shutdown_callback(status, ignoreCtrlC, fb_shut_confirmation, 0)) + { + isc_print_status(status); + return 1; + } + // your code continues ... +} + +
+
+
+ シャットダウン用の新しいisc_spb_prp_*定数 + 新しいデータベースシャットダウンモードをサービスAPIへの呼び出しを使って設定できるようになりました。いくつかの新しいisc_spb_prp_*定数を引数として利用できます。 +
+ isc_spb_prp_shutdown_mode と isc_spb_prp_online_mode + これらの引数は、それぞれ、データベースをシャットダウンするためと、オンラインに戻すために使用します。いずれも、gfix -shutの設定と正確に一致する、新しいシャットダウンモードを設定するシングルバイト・パラメータをも持ちます： + + + isc_spb_prp_sm_normal + + + isc_spb_prp_sm_multi + + + isc_spb_prp_sm_single + + + isc_spb_prp_sm_full + + + + シャットダウンのリクエストでは、シャットダウンのタイプも指定する必要があります。以下の中のいずれかとなります。 + + + + isc_spb_prp_force_shutdown + + + isc_spb_prp_attachments_shutdown + + + isc_spb_prp_transactions_shutdown + + + + いずれも4バイトの整数パラメータを取り、リクエストされたシャットダウン操作のタイムアウトを指定します。 + + + 古いスタイルのパラメータもサポートされており、デフォルトのシャットダウン（現在は'multi'）とオンライン（'normal'）モードに入るために使います。 + +
+ + + 使用例 + 以下に、fbsvcmgrユーティリティで新しいパラメータの使う例をいくつか挙げています。便宜上、ログインはすでに確立しているものと仮定しています。いずれの例もページ幅に合わせて改行していますが、実際には一行のコマンドです。 + + + + データベースをシャットダウンしてシングルユーザー・メンテナンスモードに： + + + fbsvcmgr service_mgr action_properties dbname employee + prp_shutdown_mode prp_sm_single prp_force_shutdown 0 + + + + + 次に、マルチユーザー・メンテナンスモードを有効にする： + + + fbsvcmgr service_mgr action_properties dbname employee + prp_online_mode prp_sm_multi + + + + + 今度は完全なシャットダウンモードに入り、60秒間、新しいアタッチメントを無効にする： + + + fbsvcmgr service_mgr action_properties dbname employee + prp_shutdown_mode prp_sm_full prp_attachments_shutdown 60 + + + + + 通常状態に戻す： + + + fbsvcmgr service_mgr action_properties dbname employee + prp_online_mode prp_sm_normal + + + + +
+
+ +
+ + ヘッダレベルの変更に対する制御の厳格化 + AlexPeshkov + + 危険な抜け穴を閉じることにより、いくつかのDPBパラメータに通常のユーザーからアクセスできなくなりました。それらの設定は、管理者の制御下で実行されたのでなければ、場合によっては、データベースヘッダの設定を変更し、破損を起こす可能性があるものです；つまり、それらは、本来ならSYSDBAに限定される操作を開始してしまうのです。すなわち─ + + + isc_dpb_shutdown and isc_dpb_online + + + isc_dpb_gbak_attach, isc_dpb_gfix_attach と isc_dpb_gstat_attach + + + isc_dpb_verify + + + isc_dpb_no_db_triggers + + + isc_dpb_set_db_sql_dialect + + + isc_dpb_sweep_interval + + + isc_dpb_force_write + + + isc_dpb_no_reserve + + + isc_dpb_set_db_readonly + + + isc_dpb_set_page_buffers (スーパーサーバーで) + + + クラシックサーバーでは、パラメータisc_dpb_set_page_buffersは、今でも通常のユーザーが使用できるようになっています。そのユーザーはそのセッションでのみ、一時的にバッファサイズを設定することができます。スーパーサーバーまたはクラシックサーバーでSYSDBAがこれを使用した場合は、データベースヘッダ内のバッファカウントが変更されます。つまり、デフォルトのバッファサイズは恒久的に変更されることになります。 + + データアクセスドライバおよびツールの開発者とユーザー向けの重要な注意事項 + この変更は、リストに挙げられたDPBパラメータで明示的に設定されたもののいずれかに影響します。これは、デフォルトプロパティの値によるDPB実装にそれらを含める、または、通常のユーザーとしてデータベースにアクセスするツールやアプリケーションでそれらを有効にする、いずれの方法で設定した場合も当てはまります。例えば、データベースのParamsプロパティに'RESERVE PAGE SPACE=TRUE'や'FORCED WRITES=TRUE'を含むDelphiアプリケーションで、Firebird 1.x、2.0.1、2.0.3、2.0.4また2.1.0／2.1.1に接続した場合には問題を起こさなかったものが、ISC ERROR CODE 335544788、Unable to perform operation. You must be either SYSDBA or owner of the database.（操作を実行できません。あなたはSYSDBAまたはデータベースの所有者でなければなりません。）のメッセージを出してSYSDBA以外による接続をリジェクトするようになりました。 + +
+ +
+ + アプリケーション用の新しいトレースサービス + VladKhorsun + + 新しいユーザートレース・セッションの管理に関係する五つの新しいサービスがサービスマネージャに追加されました。いずれも対応するサービスAPIアクション関数を伴っています。 + +
+ isc_action_svc_trace_start + ユーザートレース・セッションを開始します。 + Parameter(s) + + isc_spb_trc_name : トーレスセッション名、文字列、オプション + isc_spb_trc_cfg : トレースセッションの設定、文字列、必須 + + 必須パラメータは適切な設定用テキストを含む文字列です。この文字列の内容についてのガイドとして、テンプレートファイルfbtrace.confがFirebirdのルートディレクトリ内に提供されています。 + + + + システム監査セッションとは違い、ユーザーセッションはファイルから設定を読み取ることはしません。クライアント側でローカルに設定を保存し、実行時に使用するためにそれらを取得する仕組みを考える責任はアプリケーション開発者が担うことになります。 + + + 文字列内に余分なホワイトスペースがあっても問題ありません：単に無視されるだけです。 + + + + 出力 + + + 操作の状態を伝えるテキストメッセージは、次のいずれかとなります： + + トレースセッションを開始できません。トレースのプラグインがロードされていません。 + + + または、 + + トレースセッションID NNNが開始されました。 + + + + 第二の場合、トレースセッションの結果がテキスト形式で続けられます。 + + +
+ +
+ isc_action_svc_trace_stop + 指定されたトレースセッションを停止します。 + パラメータ + + isc_spb_trc_id : トレースセッションID、整数、必須 + + 出力 + リクエストの結果（状態）を通知するテキストメッセージ： + + + トレースセッションID NNNが停止されました。 + + + 他のユーザートレース・セッションを停止する権限がありません。 + + + トレースセッションID NNNが見つかりません。 + + +
+ +
+ isc_action_svc_trace_suspend + 指定されたトレースセッションを中断します。 + パラメータ + + isc_spb_trc_id : トレースセッションID、整数、必須 + + 出力 + リクエストの結果（状態）を通知するテキストメッセージ： + + + トレースセッションIDが中断されました。 + + + 他のユーザートレース・セッションを変更する権限がありません。 + + + トレースのセッションID NNNが見つかりません。 + + +
+ +
+ isc_action_svc_trace_resume + 指定されたトレースセッションを中断から再開します。 + パラメータ + + isc_spb_trc_id : トレースセッションID、整数、必須 + + 出力 + リクエストの結果（状態）を通知するテキストメッセージ： + + + トレースセッションID NNNが再開されました。 + + + 他のユーザートレース・セッションを変更する権限がありません。 + + + トレースセッションID NNNが見つかりません。 + + +
+ +
+ isc_action_svc_trace_list + 既存のトレースセッションの一覧 + パラメータなし + 出力 + トレースセッションとその状態を一覧するテキストメッセージです： + + + セッションID：<番号> + + + 名前：<文字列>。空でない場合、トレースセッション名を表示します + + + ユーザー：<文字列>。トレースセッションを作成したユーザーのユーザー名を表示します + + + 日付：YYYY-MM-DD HH:NN:SS、ユーザーセッションの開始日時 + + + フラグ：<文字列>、以下のものの一部または全部を含むコンマ区切りのセット： + + + active | suspend + + セッションの起動状態 + + + + admin + + 管理者ユーザーがセッションを作成した場合はadminを表示。通常のユーザーがセッションを作成した場合は表示せず。 + + + + system + + セッションがFirebirdエンジンによって作成された場合（システム監査セッション）はsystemを表示。通常のユーザーがセッションを作成した場合は表示せず。 + + + + audit | trace + + セッションの種類を示す：エンジンが作成した監査セッションの場合はaudit、ユーザートレース・セッションの場合はtrace。 + + + + log full + + ユーザートレース・セッションでセッションログファイルが満杯の場合に条件付きで表示。 + + + + + + + + いずれのサービスの出力も、通常は、定期的なisc_service_query呼び出しをisc_info_svc_lineまたはisc_info_svc_to_eofのいずれかの情報アイテムと一緒に使うことで得ることができます。 + +
+ +
+ + +
+ + リモート・バックアップファイルによるバックアップとリストア + AlexPeshkov + + バージョン2.5.2では、サーバー側でgbakを起動し、リモートのクライアントに置かれたgbakバックアップファイルから読み取る、またはそれに書き込む機能が導入されました。これはインターネット接続を介したバックアップ／リストアの方法として非常に効果的です。 + + この機能を使う最も簡単な方法は、コマンドラインツールfbsvcmgrを利用することです。これはサービスAPI呼び出し用のインターフェースをとりあえず提供してくれるので、クライアントアプリケーションを自分で書かずに済みます。 + +
+ リモートバックアップ + fbsvcmgrを使ってリモートのデータベースをバックアップするには、次のパターンでコマンドを入力します： + +fbsvcmgr remotehost:service_mgr -user sysdba -password XXX \ + action_backup -dbname some.fdb -bkp_file stdout >some.fbk + +
+
+ バックアップファイルからのリストア + fbsvcmgrを使ってリモートに置かれたバックアップファイルからデータベースをリストアするには、次のパターンでコマンドを入力します。 + +fbsvcmgr remotehost:service_mgr -user sysdba -password XXX \ + action_restore -dbname some.fdb -bkp_file stdin <some.fbk + +
+ + バックアップ実行時に詳細表示（-v[erify]）スイッチは使えません。これは、サーバーからクライアントへのデータチャンネルが、バックアップファイルからデータのブロックを転送するのに使われているためです。 + データベースのリストア時には制限がなく、詳細表示モードが使えます。 + + +
+ 独自のユーティリティ・コードを書く + リモートバックアップ／リストアを独自のプログラムで実行したい場合は、サービスAPIを利用して下さい。 + +
+ バックアップ + バックアップは非常に単純です─isc_info_svc_to_eofのタグを付したisc_service_query()への呼び出しを繰り返すことで返されたデータがバックアップファイルのイメージを表すストリームとなります。isc_service_query()呼び出しでisc_info_svc_to_eofタグを使い、バックアップファイル名としてサーバーにstdoutを渡して下さい。 +
+ +
+ リストア + リストアはやや複雑になります。クライアントはisc_service_query()呼び出しでサーバーに新しいspbパラメータisc_info_svc_stdinを送信します。サービスは、stdinのデータが必要な場合、クエリの結果としてisc_info_svc_stdinを返します。これには4バイト値が続き、クライアントから受け取る用意のあるバイト数を表します。（ゼロ値は現在これ以上のデータが必要ないことを意味します）。 + + クライアントはサーバーからリクエストされた以上のデータを送信してはいけません：エラーSize of data is more than requestedがスローされます。 + + + データは次のisc_service_query()呼び出しで、従来のisc_info_svc_lineタグの形式を使い、send_itemsブロックで送信されます：isc_info_svc_lineは2バイト長のデータです。次の部分が必要になると、サーバーは逆にisc_service_query()からisc_info_svc_stdinにゼロ以外の値を返します。 + + + リモートバックアップ用のサービスAPIの使い方のサンプルについては、fbsvcmgrのソースコードを参照して下さい。 + +
+
+
+ + +
+ + オンラインでの検証サービスの実行 + VladKhorsun + + データベースの検証はオンディスク構造体の整合性に関する低レベルでのチェックを可能にし、小さな破損を修正することもできます。データベースの健康をを保つためにDBAが定期的に検証を行うことは、特に重要なデータベースを扱う上で推奨される手続きです。 + これにはデータベースへの排他的なアクセスが必要です：検証作業中はその他のアクセスは禁止されます。時には、特に巨大で複雑なデータベースの場合、ユーザーのアクセスを遮断することで大規模な停滞が起こることがあります。 + オンライン検証は新しい機能です。これにより、整合性チェックを排他的アクセスなしで実行できるようになります。 +
+ オンライン検証でできること + + + データベースの一部の（または全部の）ユーザーテーブルを検証する。 + システムテーブルは検証されません。 + + + 一部の（または全部の）インデックスを検証する。 + + + + ヘッダ＼PIP＼TIP＼ジェネレータの各ページのような、他のODSのチェックは実行されません。 +
+ +
+ オンライン検証中の保護 + テーブル（および／または、そのインデックス）の検証作業中でも、ユーザーのアタッチメントはそのテーブルの読み取りを行うことができます。データの変更（INSERT\UPDATE\DELETE）については、検証の終了まで待機させられるか、ユーザートランザクションのロックタイムアウトに従ってロックタイムアウト・エラーが返されるか、いずれかとなります。 + 検証作業中のテーブルまたはそのインデックスのガベージコレクションは実行できません： + + + バックグラウンドモード、協調モードでのガベージコレクションは単にこのテーブルをスキップします。 + + + スイープはエラーを発生させて停止します。 + + + テーブルのチェックを開始すると、オンライン検証はデータの変更を防止する二つのロックを取得します： + + + PR（読み取り保護）モードでのリレーション・ロック + + + （新機能）PW（書き込み保護）モードでのガベージコレクション・ロック + + + いずれのロックも、ユーザー指定のロックタイムアウトを使うことで取得されます。ロック・リクエストが失敗した場合はエラーが報告され、そのテーブルはスキップされます。 +
+ 一度ロックが取得されると、テーブルとそのインデックスは、完全な検証を実行した場合と同じ方法で検証されます。これが完了して同じ手続きが次のテーブルへと移行すると、ロックは解除されます。 +
+ 新しいサービスAPIアクション：isc_action_svc_validate + オンライン検証はFirebirdサービスとして実装されており、サービスAPIを通じてアクセスできます。そのため、これをgfixから起動することはできません。 + この呼び出しは以下の要素を含みます： + +アクション： + isc_action_svc_validate + +パラメータ： + isc_spb_dbname : + データベースファイル名、文字列、必須 + + isc_spb_val_tab_incl, isc_spb_val_tab_excl, + isc_spb_val_idx_incl, isc_spb_val_idx_excl : + テーブル＼インデックス名のパターン、文字列、オプション + + isc_spb_val_lock_timeout : + ロックタイムアウト、整数、オプション + +出力： + オンライン検証プロセスの進行状況を示すテキストメッセージ + +
+
+ isc_action_svc_validateの対話的な使用 + fbsvcmgrユーティリティは、この新しいサービスを完全にサポートしています。構文は次の通り： + +fbsvcmgr [host:]service_mgr [user <...>] [password <...>] + action_validate dbname <ファイル名> + [val_tab_incl <パターン>] + [val_tab_excl <パターン>] + [val_idx_incl <パターン>] + [val_idx_excl <パターン>] + [val_lock_timeout <番号>] + + このうち、 + + val_tab_incl検証の実行に含めるテーブル名のパターン + val_tab_excl検証の実行から除外するテーブル名のパターン + val_idx_incl検証の実行に含めるインデックス名のパターン。デフォルトは%、すなわち全インデックス + val_idx_excl検証の実行から除外するインデックス名のパターン + val_lock_timeoutロックタイムアウト、検証するテーブルのロックの取得に使用される、秒単位、デフォルトは10秒、0は待機なし、-1は無期限待機 + + + + 使用上の注意 + + パターンは正規表現、SIMILAR TO式と同じルールで処理されます。 + データベースのダイアレクトに関わりなく、全てのパターンで大文字小文字は区別されます。 + テーブル用のパターンが省略された場合、全てのユーザーテーブルは検証されます。 + インデックス用のパターンが省略された場合、指定されたテーブルの全てのインデックスが検証されます。 + システムテーブルは検証されません。 + + テーブルまたはインデックスのリストを指定するには： + + パイプ・キャラクタ'|'で名前を区切ります。 + スペースを入れないこと：TAB1 | TAB2は誤りです。 + コマンド・インタープリタを混乱させないように、ダブルクォートでリスト全体を囲います。 + + + + + 例 + + + + データベース'c:\db.fdb'の、名前が'A'で始まる全てのテーブルを検証。インデックスは検証しない。ロックの待機は実行しない。 + +fbsvcmgr.exe service_mgr user SYSDBA password masterkey + action_validate dbname c:\db.fdb + val_tab_incl A% + val_idx_excl % + val_lock_timeout 0 + + + + テーブルTAB1とTAB2と、その全てのインデックスを検証。ロック待機のタイムアウトは10秒（デフォルト）： + +fbsvcmgr.exe service_mgr user SYSDBA password masterkey + action_validate dbname c:\db.fdb + val_tab_incl "TAB1|TAB2" + + + + val_XXXオプションのデフォルトの挙動：データベース'c:\db.fdb'の全てのユーザーテーブルとそのインデックスを検証。ロック待機はデフォルトの10秒： + +fbsvcmgr.exe service_mgr user SYSDBA password masterkey + action_validate dbname c:\db.fdb + + + +
+
+ +
+ + 他のサービスAPIの追加 + AlexPeshkov + + + 他に追加されたサービスAPIには以下のものが含まれます： + +
+ サービスAPIでのロールRDB$ADMINのマッピング + セキュリティ・データベースへのアクセスをリクエストする際に権限のあるOSユーザーのロールRDB$ADMINを有効または無効にするため、サービスパラメータブロック（SPB）に二つのタグアイテムが追加されました。 + + + この機能は、新しい-mappingスイッチによってgsecユーティリティに実装されました。コマンドライン・ユーティリティの章の関連する節の注意事項を参照して下さい。 + +
+ タグアイテムisc_action_svc_set_mapping + security2.fdbにアクセスするためのサービス・リクエスト用に、指定されたOSユーザーに対しロールRDB$ADMINを有効にします。 +
+ +
+ タグアイテムisc_action_svc_drop_mapping + security2.fdbにアクセスするためのサービス・リクエスト用に、指定されたOSユーザーのロールRDB$ADMINを無効にします。 +
+
+ +
+ パラメータisc_spb_sec_admin + 新しいパラメータisc_spb_sec_adminは、SYSDBAまたは他の十分な権限を持つユーザーがセキュリティ・データベース（security2.fdb）のロールRDB$ADMINを通常のユーザーに対して付与したり削除したりできるようにするために導入された新しいDDL構文のSPB実装です。通常のユーザーがセキュリティ・データベースでユーザーを作成、変更、削除するには、このロールでSYSDBAと同じ権限を手にする必要があります。 + + isc_spb_sec_adminはspb_long型で、値として0（REVOKE ADMIN ROLEを意味する）またはゼロ以外の数字（GRANT ADMIN ROLEを意味する）を取ります。 + 詳細は、データ定義言語の章のCREATE/ALTER/DROP USERの項を参照して下さい。 +
+ +
+ タグアイテムisc_spb_bkp_no_triggers + この新しいSPBタグは、データベースレベルやトランザクションレベルでのトリガがバックアップ・リストアの最中に起動するのを防ぐため、バージョン2.1でgbakユーティリティに導入された-nodbtriggersスイッチのサービスAPIとしての側面を表すものです。これは、isc_spb_bkp_ignore_limboなどのアイテムを含むオプション命令のセットisc_spb_optionsの中での使用が意図されています。 +
+ +
+ タグアイテムisc_spb_res_metadata_only + トラッカー・リファレンス CORE-3462 + SPB中のリストアサービス・オプションにisc_spb_bkp_metadata_onlyタグを渡すと、metadata-onlyリストアが実行されます。Firebirdのfbsvcmgrを含む多くのツールでは、リストアのリクエストにバックアップ・オプションを指定することはできません。 + （バージョン2.5.1）混乱を避けるため、単にisc_spb_bkp_metadata_onlyを再実装しただけのタグisc_spb_res_metadata_onlyがパブリックヘッダとfbsvcmgrに定数として追加されました。 +
+ + +
+ nBackupのサポート + サービスAPIでnBackupアクションをサポートするために三つのものが追加されました。 +
+ バックアップとリストア + トラッカー・リファレンス CORE-1758 + nBackupユーティリティは二つの論理グループの操作を実行します：データベースのロックとロック解除、そして、バックアップとリストアです。そのうち、ロック／ロック解除の操作にサービスアクションを提供する正当な理由はありません—SQL言語でALTER DATABASEのリクエストを使うことでリモートからのそれらのリクエストは可能です—一方で、バックアップ／リストア操作用のサービスAPIのインターフェースを正当化するのは簡単です。 + バックアップとリストアはホストのステーションで実行する必要があります。それらにアクセスする唯一の方法は、nBackupを起動することでした。 + 以下の二つの新しいサービスアクションによって、サービスAPIを通じてnBackupによるバックアップとリストアをリクエストできるようになりました： + + + isc_action_svc_nbak - 増分バックアップ + + + isc_action_svc_nrest - 増分データベースリストア + + + パラメータ・アイテムは、以下の通り： + + + isc_spb_nbk_level - バックアップレベル（整数） + + + isc_spb_nbk_file - バックアップファイル名（文字列） + + + isc_spb_nbk_no_triggers - データベーストリガを抑制するためのオプション + + + + 使用例 + 以下に、fbsvcmgrユーティリティで新しいパラメータの使う例をいくつか挙げています。便宜上、ロングインはすでに確立しているものと仮定しています。いずれの例もページ幅に合わせて改行していますが、実際には一行のコマンドです。 + + + + レベル0バッックアップを作成： + + + fbsvcmgr service_mgr action_nbak dbname employee + nbk_file e.nb0 nbk_level 0 + + + + + + レベル1バッックアップを作成： + + + fbsvcmgr service_mgr action_nbak dbname employee + nbk_file e.nb1 nbk_level 1 + + + + + + ファイルからのデータベースのリストア： + + + + fbsvcmgr service_mgr action_nrest dbname e.fdb + nbk_file e.nb0 nbk_file e.nb1 + + + + +
+ +
+ ダイレクトI/O機能のサポート + isc_spb_nbk_direct on|off + 新しいタグにより、コマンドラインからnbackup -D on|offを呼び出すのと同じアクションが可能となり、ダイレクトI/Oの強制的なオン・オフが行えます。これは他のnbackup関連のタグと同様に、action_nbakでのみ有効です。 + + この機能の使用法については、ユーティリティの章の新しいnbackupのスイッチについての注意事項を参照して下さい。 + +
+
+ +
+ + サービスAPIでのFIX_FSS_DATAおよびFIX_FSS_METADATAオプションが可能に + A.Peshkov + + + トラッカー・リファレンス CORE-2439 + Firebird 2.1でgbak -restoreスイッチに実装されたFIX_FSS_DATAとFIX_FSS_METADATA関数はコアエンジンに実装され、サービスAPIのisc_action_svc_restore構造体に対応するタグ定数として公開されています。従って、開発者には、古いFirebirdデータベースから新しいオンディスク構造体への移行を自動化するアプリケーションを書く道が開かれています。 + 新しいSPBタグはisc_spb_res_fix_fss_dataとisc_spb_res_fix_fss_metadataです。 +
+
+ +
+ 新しいトレースAPI + 作成中の新しいトレースAPIは、トレースされる任意のイベント発生時にエンジンから呼び出される外部プラグインモジュールとして実装可能なフックのセットを提供します。これはまだドキュメント化されておらず、今後のサブリリースで変更されることもあります。 + + これについてのより詳しい情報は、管理機能の章のトレースのプラグイン機能の項を参照して下さい。 +
+ +
+ + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/AdminFeatures25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/AdminFeatures25.docbook new file mode 100644 index 00000000..61101988 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/AdminFeatures25.docbook @@ -0,0 +1,547 @@ + + + 管理機能 + + Firebirdの管理機能にいくつか改善が施されました。多くの皆さんがこれを歓迎するでしょう。 + +
+ + 新しいシステムロールRDB$ADMIN + + Alex + Peshkov + + + 新たな定義済みシステムロールRDB$ADMINが追加され、SYSDBA権限を他のユーザーに譲渡できるようになりました。どのユーザーでも、特定のデータベースでこのロールが付与された場合、その指定されたロールRDB$ADMINを持つデータベースにアタッチする際にSYSDBAと同様の権限を手にします。 + + これを割り当てるには、SYSDBAはそのデータベースにログインしている必要がありますが、ロールRDB$ADMINをユーザーに付与する方法は、他のロールをユーザーに付与する仕方と同様です。このロールを付与されたユーザーが、そのデータベースでのスーパーユーザー権限にアクセスするためには、ログイン時にこれを明記する必要があります。 + + + ユーザーがアタッチする際に、ユーザー・データベース・ロールがDPB（接続パラメータ）に渡されている場合、これをRDB$ADMINと置き換えることはできません。つまりこの場合、SYSDBA権限を得ることはできません。 + + + 次に挙げる例では、SYSDBA権限がユーザー（User1とAdmins\ADMINS）に譲渡されています。このうち二番目のユーザーは、信頼された認証を介してアクセスが有効とされたWindowsシステムユーザーとして典型的なものです： + + +GRANT RDB$ADMIN TO User1; +GRANT RDB$ADMIN TO "Admins\ADMINS"; + + +
+ 複数のデータベースとスーパーユーザー + RDB$ADMINロールが割り当てられている場合でも通常のユーザーがSYSDBAになるわけではないということは理解しておくべきです。正確には、あるデータベースでユーザーにこのロールが付与されている時、そのユーザーはデータベース内のオブジェクトに対してSYSDBAと同等の権限を与えられている、ということです。 + + + + 同じユーザーに複数のデータベースでのスーパーユーザー権限が必要な場合、そのユーザーに対するロールRDB$ADMINは、それぞれのデータベースについて明示的に付与されなければなりません。 + + + 一つのデータベースに対して複数のユーザーにスーパーユーザー権限を持たせたい場合、それぞれのユーザーにロールRDB$ADMINを付与する必要があります。 + + + ユーザーがあるデータベースのロールRDB$ADMINに属している場合、これを他のユーザーに付与することができます。 + + + WITH ADMIN OPTION（このロールを他のユーザーに付与する権限のために）や、WITH GRANT OPTION（オブジェクトの所有者であることなしに他のユーザーにそれらのオブジェクトに対するパーミッションを付与する権限のために）を指定する必要はありません。ADMINやGRANTオプションは暗に含まれています。 + + +
+ +
+ システム <quote>スーパーユーザー</quote> + POSIXホストではrootユーザーが常にSYSDBA権限を持っていますが、このことは、Firebird 2.1まで、Windowsのドメイン管理者には当てはまりませんでした。バージョン2.1で設定パラメータAuthenticationが導入されたことにより、Windowsドメイン管理者としてログインしているユーザーは、信頼されたユーザー認証を通して、自動的にSYSDBA権限でサーバーにアクセスできるようになりました。POSIX版ではこの仕組みに変更はありませんが、Windows版では、ロールRDB$ADMINの導入により、WindowsのAdministratorsがSYSDBA権限を得る方法が変更されました。 + + + Windowsの<quote>信頼されたユーザー認証</quote>が、デフォルトでは利用できなくなりました！ + デフォルトでは、firebird.confのAuthenticationパラメータはnativeに設定されています。信頼されたユーザー認証を有効にするには、trustedかmixedへと明示的に設定しなければなりません。 + + + +
+ WindowsのAdministrators向けのグローバル管理者権限 + + 信頼されたユーザー認証が設定されているFirebirdサーバーで、信頼されたドメイン管理者がSYSDBAアクセス権限を得るには、ドメイン管理者はロールRDB$ADMINに属している必要があります。通常のユーザー向けとして上で解説した手動による方法を使い、データベースごとにそれぞれ特定の管理者にロールRDB$ADMINを付与します。 + しかし、SYSDBAがサーバーを設定することで、Windows管理者が任意のデータベースにログインする時にロールRDB$ADMINが自動的にマッピングされるようにする方法があり、これによって、POSIXシステムでroot権限を持つユーザーがSYSDBA権限と関連付けられているのと同様の状況にすることができます。新しいALTER ROLE文はこの目的のため（だけ）に用いられます。 + +
+ ALTER ROLE文 + 信頼されたユーザー認証が有効になっているWindowsサーバーで、ロールRDB$ADMINを管理者に自動的にマッピングするようにデータベースを設定するには、SYSDBAは、任意のデータベースにログインし、以下のSQL文を発行します： + + +ALTER ROLE RDB$ADMIN + SET AUTO ADMIN MAPPING; + + + デフォルト設定に戻して管理者が自動的にはSYSDBA権限を得ないようにするには、次のSQL文を発行します： + +ALTER ROLE RDB$ADMIN + DROP AUTO ADMIN MAPPING; + +
+ +
+ サービスAPIタグアイテム + 同様の効果はサービスAPIに用意された二つのタグアイテムでサポートされます：自動マッピングを有効にするisc_action_svc_set_mappingとそれを無効にするisc_action_svc_drop_mappingです。 + これらのタグはfbsvcmgrユーティリティでサポートされています。 +
+
+
+ +
+ ユーザー管理用に拡大するRDB$ADMINの範囲 + 新しいDDLコマンドALTER USERにより、通常のユーザー（普通のFirebirdユーザーやPOSIX上での非rootユーザー、または信頼されたユーザー認証が有効になっているWindowsシステム上で信頼されたユーザー）が、任意のデータベースにログインしている間、パスワードおよび／または個人名要素を変更できるようになります。スーパーユーザーは、同じコマンドを使ってユーザーの作成と削除を行うこともできます。この新しいコマンドの詳細については、データ定義言語の章のCREATE/ALTER/DROP USERの項を参照して下さい。 + + security2.fdbはODS 11.2データベースとして（アップグレードが必要な場合もあります）作成されるので、ここにも定義済みロールRDB$ADMINがあります。どのユーザーも—SYSDBAでさえも—セキュリティ・データベースにログインすることができないため、SYSDBAまたはスーパーユーザーが、ユーザーの作成・削除する権限が必要な通常のユーザーに対してsecurity2.fdbのロールRDB$ADMINを適用できるという代替手段が提供されています。これには三つの方法があり、それぞれ同等の効果を持ちます。 + + + + CREATE USERまたはALTER USER文でオプションパラメータGRANT ADMIN ROLEを使う。 + + + 注意 + この場合のGRANT ADMIN ROLEやREVOKE ADMIN ROLEがGRANT／REVOKE文ではなく、CREATE USERやALTER USER文に対する3キーワードパラメータであることに注意して下さい。'ADMIN'という名のシステムロールは存在しません。 + データベースのロールRDB$ADMINを手にしている任意のユーザーは暗黙のうちに拡張権限WITH ADMIN OPTIONとWITH GRANT OPTIONを手にしています。 + + + 例 + + セキュリティ・データベースでユーザーalexにロールRDB$ADMINを付与する場合： + + ALTER USER alex GRANT ADMIN ROLE; + + + セキュリティ・データベースでユーザーalexからロールRDB$ADMINを取り消す場合： + + ALTER USER alex REVOKE ADMIN ROLE; + + + すべてのデータベースでユーザーalexを削除しその権限も削除する場合： + + DROP USER alex; + + + + + gsecユーティリティに-adminスイッチを付けて使用します。このスイッチは引数を一つ取ります：YESの場合、ロールRDB$ADMINがユーザーに適用されます。NOの場合、このロールは取り消されます。詳細は、ユーティリティの章のgsecの節のロールRDB$ADMINを通常のユーザーに付与するの項を参照して下さい。 + + + + SPBパラメータisc_spb_sec_adminを使います。これはsecurity2.fdbで通常のユーザーにロールRDB$ADMINをSPB接続を介して割り当てる実装です。詳細については、Firebird APIとODSの変更の章のParameter isc_spb_sec_adminの項に記載されています。 + fbsvmgrユーティリティもこのパラメータの使用をサポートしています。 + + + + Firebird 2.5では、サーバーに複数のセキュリティ・データベースを作成することはできません。バージョン3.0以降は、データベースごとに個別のセキュリティ・データベースを持てるようになる予定です。現状では、サーバー上の任意のデータベース（employee.fdbも含め）に接続するごとに唯一のsecurity2.fdbが更新されることになります。 + 将来的に、これらのリクエストは影響を受ける各セキュリティ・データベースに対応するデータベースから送信することが必須となります。 + +
+
+ +
+ + トレースと監査サービス + + Vlad + Khorsun + + + バージョン2.5での新しいトレースと監査の機能は、当初、Nickolay Samofatov氏によってコントリビュートされたTraceAPIから開発されました。これはFirebirdコードをベースとする商業製品Red Soft Database用に彼が開発したものです。 + +
+ 機能の概要 + 新しいトレースと監査の機能は、SQL文の実行、接続、切断など、エンジン内で実行されるさまざまなイベントのログを取り、照合して、対応するパフォーマンス特性のリアルタイムな分析に使うことができます。 + トレースは、トレース・セッションの文脈で起こります。それぞれのトレース・セッションが固有の設定、ステート、出力を持ちます。 + + Firebirdエンジンはトレース可能なイベントの固定リストを持ちます。システム監査トレースとユーザートレースという、二つの異なる種類のトレースを実行できます。エンジンがどのようにセッション用のイベントのリストを作成するかは、どのトレースが要求されているかによります。 + + 全てのトレースセッションに一意なセッションIDが割り当てられます。任意のトレースセッションが始まると、サービスマネージャはこのIDをメッセージとして出力します。 + + Trace session ID nnnn started + + もちろん、ここでの nnnn はIDです。 + +
+ +
+ システム監査のセッション + システム監査のセッションはエンジン自ら開始します。セッションがどのイベントに関心を持っているか決定するため、エンジンはセッションを作成しに行く際にトレース設定ファイルの内容を読みます。 + + firebird.confの新しいパラメータAuditTraceConfigFileは、ファイルの名前と配置を指示します。進行中のシステム監査トレースは最大で一つとなります。デフォルトでは、このパラメータの値は空で、どのシステム監査トレースも設定されていないことを示しています。 + +
+ 設定ファイルにはトレースされるイベントのリストが含まれ、各イベント用のトレースログの配置を指示しています。異なるイベントのセットがそれぞれ異なるデータベースのログを取り、ログファイルを切り離すことができるというような柔軟さは十分にあります。Firebirdのルートディレクトリ内にあるテンプレートファイルfbtrace.confには、監査トレース設定ファイルを記述するためのフォーマット、ルール、構文とともに、利用可能なイベントの完全なリストが含まれています。 + + + fbtrace.confファイルに関するTip + このファイルには各エントリの目的と構文を説明する大量のコメント付きテキストが含まれます。サブリリースを重ねるごとに、トレース性能の改善のため時々新たなイベントと機能が加えられますので、注意して下さい。 + 例えば、最近のプレリリースでの拡張では、サービスイベントを、名前を使ってトレースしたり、include、excludeフィルタをを使ってターゲットを絞ることができるようになっています。 + + 他の例として、パス名マッチングアルゴリズムの改善により、設定ファイル内の文字列をプラットフォームのキャラクタ・セットに従って翻訳したり、UTF-8の文字列に基づいて、Windowsでは大文字小文字を区別しない、POSIXでは大文字小文字を区別する、というようなファイル名の取り扱い等に関するプラットフォーム固有のルールが適用できるようなっています。（トラッカー・リファレンス CORE-2404、A. dos Santos Fernandes）。 + + バージョン2.5.2で施された改善では、トレースセッションの設定により、手動・自動スイープ両方の詳細情報についてログを取ることができるようになりました。テンプレートファイルからSWEEP_オプションを見つけて下さい。 + +
+
+ +
+ ユーザートレース・セッション + ユーザートレース・セッションはサービスAPIに対する新しい呼び出しを使ってユーザーが管理します。このための新しいサービス関数は五つあります： + + + 開始：isc_action_svc_trace_start + + + 停止：isc_action_svc_trace_stop + + + 中断：isc_action_svc_trace_suspend + + + 再開：isc_action_svc_trace_resume + + + 既知の全トレースセッションの一覧: isc_action_svc_trace_list + + + サービスAPI呼び出しの構文については、Firebird APIとODSの変更の章のアプリケーション用の新トレース機能の項で議論されています。 + +
+ ユーザートレース・セッションの働き + ユーザーアプリケーションがトレースセッションを開始すると、セッション名（オプション）とセッション設定（必須）が付けられます。セッション設定は、出力の配置に関する行は別として、fbtrace.confをテンプレートとするルールと構文に準拠したテキストファイルです。このファイルはFirebirdのルートディレクトリにあります。 + + これらのファイルはサーバーには残りません。ユーザートレースの要求に応えるためテキストの格納と取得にふさわしい仕組みを設計するのは、アプリケーション開発者の仕事になります。 + 例えば、コマンドラインユーティリティfbsvcmgrは、セーブファイル・パラメータtrc_cfgをサポートします。 + + + ユーザーセッションの出力は、それぞれ1MBのテンポラリ・ファイルの一群に格納されます。アプリケーションによって一度完全に読み込まれたファイルは、自動的に削除されます。デフォルトでは、ファイルサイズの総計は最大で10MBに制限されています。この値はfirebird.conf内のMaxUserTraceLogSizeを使って小さくも大きくもできます。 + + アプリケーションによって一度ユーザートレース・セッションのサービスが開始されると、アプリケーションは、isc_service_query()への呼び出しを使ってその出力を読み込む必要があります。このサービスは、アプリケーションが読み込めるより速く出力を生成することがあります。出力のサイズの総計がMaxUserTraceLogSizeの上限に達すると、エンジンは自動的にトレースセッションを中断します。アプリケーションがファイル（出力の1MB分）を読み込み終えるとそのファイルは削除され、容量に余裕が生まれてエンジンはトレースセッションを自動的に再開します。 + + アプリケーションは、そのトレースセッションの停止を決めると、単にサービスからのデタッチをリクエストします。別の方法として、isc_action_svc_trace_*関数を使うことで、アプリケーションが自由にトレースセッションを中断、再開、停止することもできます。 + + アタッチメントのキャラクタ・セット名は対応するいずれのトレースログのレコードにも含まれ、user:roleとprotocol:portの間に置かれています。例えば、 + +A.FDB (ATT_36, SYSDBA:NONE, WIN1251, TCPv4:127.0.0.1) + + DPBにキャラクタ・セットが指定されていない場合、アタッチメントのキャラクタ・セットのスロットでトレースログのレコードにNONEが書き込まれます。 + （CORE-3008） + +
+ +
+ トレースのセッションを管理できるのは誰か？ + どのユーザーでもトレースセッションを始動し、管理することができます。通常のユーザーは、自身の接続についてのトレースだけをリクエストすることができ、他のユーザーが開始したトレースセッションを管理することはできません。管理者はどのトレースセッションでも管理できます。 +
+ +
+ 異常な終了 + 全てのFirebirdプロセスが停止されると、どのユーザートレース・セッションも保存されません。つまり、スーパーサーバーまたはスパークラシックサーバーのプロセスがシャットダウンされると、resumeを待機していたものを含め、進行中だったユーザートレース・セッションは完全に停止され、resumeもそれらを再開することができません。 + + + もちろん、クラシックサーバーでは、それぞれの接続がそれぞれ専用のサーバー・インスタンスを含むことから、この状況は当てはまりません。そもそも、クラシックサーバー・インスタンスをシャットダウンするという事態はありません。どのサービス・インスタンスもそれを引き起こした接続より長生きすることはできません。 + +
+ +
+ ユーザートレースのサンプル設定テキスト + 以下のサンプルは、ユーザートレース・セッションの設定テキストを記述するための基準を提供します。 + + + + 接続12345に含まれる全てのSQL文のプリペア、解放、実行をトレースします。 + +<database mydatabase.fdb> + enabled true + connection_id 12345 + log_statement_prepare true + log_statement_free true + log_statement_start true + log_statement_finish true + time_threshold 0 +</database> + + + + + 実行されたINSERT、UPDATE、DELETE文と、プロシージャとトリガへのネストされた呼び出しのログを取りつつ、データベースmydatabase.fdbへの所定のユーザーの全ての接続をトレースし、対応するPLANとパフォーマンスの統計を示します。 + +<database mydatabase.fdb> + enabled true + include_filter %(INSERT|UPDATE|DELETE)% + log_statement_finish true + log_procedure_finish true + log_trigger_finish true + print_plan true + print_perf true + time_threshold 0 +</database> + + + +
+ +
+ コマンドラインからユーザートレースサービスへのリクエスト + トレースサービスと対話的に動作する新しいコマンドラインユーティリティfbtracemgrが追加されました。これはスイッチとパラメータに独自の構文を持ちます。実例も含めた詳細はユーティリティの章で議論されています。 + + さらに、サービスユーティリティfbsvcmgrは、コマンドラインからのサービスリクエストの送信に使うことができます。以下に例を示します。 + + + + fbtrace.confという名の設定ファイルを使ってMy traceと名づけたユーザートレースを開始し、画面上でその出力を読む。 + + + fbsvcmgr service_mgr action_trace_start trc_name "My trace" trc_cfg fbtrace.conf + + このトレースセッションを停止するには、fbsvcmgrコンソールプロンプトでCtrl+Cを押します。（下記(e)も参照）。 + + + + トレースセッションを一覧する： + + fbsvcmgr service_mgr action_trace_list + + + + + ID 1のトレースセッションを中断する + + fbsvcmgr service_mgr action_trace_suspend trc_id 1 + + + + + ID 1のトレースセッションを再開する + + fbsvcmgr service_mgr action_trace_resume trc_id 1 + + + + + ID 1のトレースセッションを停止する + + fbsvcmgr service_mgr action_trace_stop trc_id 1 + + + 他のコンソールでセッションの一覧を得て（b参照）、関心あるセッションのIDを探し、現在のコンソールでそれを使ってそのセッションを停止します。 + + + +
+
+ +
+ RDB$ADMINのユーザー管理スコープの昇格 + トラッカー・リファレンス CORE-2588 + Windowsでは、異なるWindowsセッションの複数のエンジン・インスタンスがグローバル名前空間でのtraceの起動を許可してしまうと、トレースツールは共有メモリの競合を引き起こします。そのため、トレーススコープは、現在のWindowsセッションからアクセス可能なプロセスだけに限定されています。 +
+ +
+ 使用例 + 一般に三つの場合が考えられます： + + + エンジン活動の常時監査 + システム監査トレースを使います。管理者はトレース設定ファイルを作成・編集し、firebird.conf内にあるAuditTraceConfigFileの設定を介してその名前を決め、Firebirdを再起動します。その後、管理者がこのセッションを中断、再開、停止するのにFirebirdを再起動する必要はありません。 + + 監査設定の変更をエンジンに通知するには、Firebirdを再起動する必要があります。 + + + + + 一部（または全部）のデータベースの一部（または全部）の活動に対するオンデマンドな対話的インタラクティブ・トレース + アプリケーション（fbtracemgrユーティリティでも可）がユーザートレース・セッションを開始し、その出力を読み込み、トレースしたイベントをリアルタイムで画面に表示します。ユーザーはそのトレースを中断・再開することができ、最終的にそれを停止することもできます。 + + + + 重要な期間（数時間または終日ということも）のエンジン活動を収集し後で分析する + + アプリケーションがユーザートレース・セッションを開始し、トレースの出力を定期的に読み込み、一つまたは複数のファイルに保存します。そのセッションの停止はその同じアプリケーションか別のアプリケーションによって手動で行う必要があります。複数のトレースセッションが起動している場合、関心あるセッションを特定するため一覧の取得が求められることがあります。 + + +
+ +
+ トレースのプラグイン機能 + 新しいトレースAPIは外部プラグインモジュールとして実装可能なフックのセットを提供します。これらは、トレースされる任意のイベントの発生時にエンジンから呼び出されます。こうしたイベントで適宜ログを取る役割はプラグインが担うことになります。 + このトレースAPIはFirebird 2.5に含まれおり、使用することもできますが、今後のサブリリースでの変更が予定されておりますので、正式なものではなく、unstableと見て下さい。 + 実装された標準のトレースプラグインfbtrace.dll (.so)は、Firebird 2.5がインストールされたディレクトリ内の\pluginsフォルダの中にあります。 +
+
+ +
+ + モニタリングの改善 + + Dmitry + Yemanov + + + Firebird 2.5では、バージョン2.1で導入されたMON$データベースモニタリング機能が拡張され、コンテキスト変数とODS 11.2以降のデータベースでのメモリ使用に関するデータを通知する新たなテーブルが備わりました。また、これらのデータベースでは、クライアントの接続をMON$ストラクチャーを通じて他の接続から終了できるようになりました。 + +
+ 通常のユーザー向けの拡張されたアクセス + もともとの設計では、特別な権限を持たないデータベースのユーザーは自身のCURRENT_CONNECTIONに関するモニタリング情報しか見ることができませんでした。現在は、同じユーザー名で認証された任意のアタッチメントの情報をリクエストできるようになっています。 + トラッカー・リファレンス CORE-2233 + + 注意 + + + 異なるエンドユーザーのためにミドルウェア層で同じユーザー名による同時・複数回のログインを必要とするアプリケーションのアーキテクチャでは、エンドユーザーにモニタリング機能を公開する点について、パフォーマンスやプライバシーへの影響が考慮されるべきです。 + + + 同様の拡張はバージョン2.1.2で実装されました。 + + + +
+ +
+ ODS 11.2データベースの新しいMON$メタデータ + + ODS 11.1のメタデータについては、バージョン2.1用のドキュメントを参照して下さい。 + + + + MON$メタデータ用キャラクタ・セットの変更 + ファイル仕様に関するMON$テーブル内のカラム定義に使われるシステムドメインRDB$FILE_NAME2が、CHARACTER SET NONEからCHARACTER SET UNICODE_FSSへと変更されました。現在影響を受けるカラムはMON$DATABASE_NAMEとMON$ATTACHMENT_NAMEとMON$REMOTE_PROCESSです。この変更で影響を受けるデータは、バージョン2.5で更新されたfilespecの取り扱い、および他のDPBのキャラクタパラメータ・アイテムと一致することになります。 + + （トラッカー・エントリー：CORE-2551、A. dos Santos Fernandes） + + + + + MON$MEMORY_USAGE（現在のメモリ使用） + + + - MON$STAT_ID（統計 ID） + - MON$STAT_GROUP（統計グループ） + 0: データベース + 1: アタッチメント + 2: トランザクション + 3: SQL文 + 4: 呼び出し + - MON$MEMORY_USED（現在使用中のバイト数） + エンジンによって実行されるプールからの高レベルでのメモリ割り当て。 + Can be useful for tracing memory leaks and for investigating unusual + memory consumption and the attachments, procedures, etc. that might + be responsible for it. + メモリリークのトレース、また、それが原因となりうる異常なメモリ消費やアタッチメント、プロシージャなどの調査に役立つ可能性があります。 + - MON$MEMORY_ALLOCATED（OSレベルで現在割り当てられているバイト数） + Firebirdメモリマネージャによって実行された低レベルでのメモリ割り当て。 + これらはOSによって実際に割り当てられているバイトであり、そのため、 + 物理メモリの消費を監視することができます。 + + + すべてのレコードがゼロ以外の値を持つわけではありません。一般に、MON$DATABASEとメモリバインド・オブジェクトだけはゼロ以外の割り当てられた値を示します。小さな割り当てはこのレベルでは行われません。その代わり、データベースのメモリプールにリダイレクトされます。 + + + + - MON$MAX_MEMORY_USED（このオブジェクトで使用される最大のバイト数） + - MON$MAX_MEMORY_ALLOCATED（このオブジェクトによってOSから割り当てられた最大のバイト数） + + + + + + MON$CONTEXT_VARIABLES（既知のコンテキスト変数） + + + - MON$ATTACHMENT_ID（アタッチメント ID） + セッションレベルのコンテキスト変数用の有効なIDのみを含みます。 + トランザクションレベルの変数はこのフィールドにNULLをセットします。 + - MON$TRANSACTION_ID（トランザクション ID） + トランザクションレベルのコンテキスト変数用の有効なIDのみを含みます。 + セッションレベルの変数はこのフィールドにNULLをセットします。 + - MON$VARIABLE_NAME（コンテキスト変数名） + - MON$VARIABLE_VALUE（コンテキスト変数値） + + + + + + MON$STATEMENTSとMON$STATEでのメモリ使用 + MON$STATEMENTSとMON$STATEでのメモリ使用の統計は、実際のCPU消費を表現しています。 + トラッカー・リファレンス CORE-1583 + +
+ +
+ 使用上の注意 + + 例 + + SQL文のメモリ使用ランキングトップ10： + +SELECT FIRST 10 + STMT.MON$ATTACHMENT_ID, + STMT.MON$SQL_TEXT, + MEM.MON$MEMORY_USED +FROM MON$MEMORY_USAGE MEM + NATURAL JOIN MON$STATEMENTS STMT + ORDER BY MEM.MON$MEMORY_USED DESC + + + 現在の接続用の全てのセッションレベルのコンテキスト変数を列挙： + +SELECT + VAR.MON$VARIABLE_NAME, + VAR.MON$VARIABLE_VALUE +FROM MON$CONTEXT_VARIABLES VAR + WHERE VAR.MON$ATTACHMENT_ID = CURRENT_CONNECTION + + +
+ クライアントの終了 + MON$ストラクチャーは、設計上、読み取り専用となっています。そのため、それらに対するユーザーDMLオペレーションは禁止されています。しかし、MON$STATEMENTSとMON$ATTACHMENTSテーブルのレコードの削除（だけ）を許可する仕組みが組み込まれています。このメカニズムの効果として、それぞれ、SQL文実行のキャンセルや、ODS 11.2データベース向けには、クライアントセッションの終了が可能になります。 + + 指定された接続の現在の全活動をキャンセルする： + +DELETE FROM MON$STATEMENTS + WHERE MON$ATTACHMENT_ID = 32 + + + 自分以外の全てのクライアントの接続を切断する： + +DELETE FROM MON$ATTACHMENTS + WHERE MON$ATTACHMENT_ID <> CURRENT_CONNECTION + + + + + + + + + SQL文をキャンセルしようとしても、クライアントに現在実行中のSQL文がない場合は、無効なオペレーション（no-op）となります。 + + + キャンセルと同時に、execute／fetchのAPI呼び出しはエラーコードisc_cancelledを返します。 + + + その後のオペレーションは許可されます。 + + + + + + + + + 終了中の接続でアクティブなトランザクションはすぐにキャンセルされ、ロールバックされます。 + + + 終了されると、クライアントセッションはエラーコードisc_att_shutdownを受け取ります。 + + + その後にこの接続ハンドルを使おうとすると、ネットワークのread／writeエラーを引き起こします。 + + + + + +
+
+
+ + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/BugFixes25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/BugFixes25.docbook new file mode 100644 index 00000000..66d2443c --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/BugFixes25.docbook @@ -0,0 +1,3821 @@ + + + Bugs Fixed + + + + +
+ Firebird 2.5.4リリース + バージョン2.5.4リリース前に以下の改善とバグフィックスが報告されました： + +
+ コアエンジン + （CORE-4713） +     テーブルに式インデックスを挿入した後のロールバックでBLOB not foundのエラーが発生していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4700） +     GDS_DROP_DATABASEの実行時にシャドウのテストに誤りがありました。Firebird 3.0からのバックポートにより修正されました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4690） +     DISTINCTと非DISTINCTの競合が、検索条件IN()を含むサブクエリの結果に影響することがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4678） +     クラシックサーバーまたはスーパークラシックサーバー上のまだコミットされていないトランザクションで、BLOB not foundのエラーが（誤って）スローされることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4673） +     計算項目に基づいた計算インデックスが全てのキーにNULLを格納していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4670） +     制約違反のエラーが取り消される場合がありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4644） +     同時接続による高負荷状況下でデータベースのオープンエラーが発生することがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-4631） +     ロックテーブルをバックアップする共有メモリ領域がリマップされなかった時、ステータスベクターがエラーメッセージLock manager out of roomを返していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4627） +     ON CONNECTトリガがモニタリングテーブルにアクセスする時に、TIPページロックとモニタリングロックの間でデッドロックが発生することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4618） +     MERGE文が同じターゲット行を複数回更新し、また、PLAN MERGEが使われた場合、ロールバックが変更を取り消せませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4615） +     クラシック・サーバーで、ある条件下でASTプロセスがループ化し、CPU負荷が100％となってハングアップすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4599） +     REPLACE()関数がマルチバイトのキャラクタ・セットで正しく機能していませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4530） +     DB_KEYによる二つのテーブルの結合が、SQL文の式の順序によっては実行に失敗することがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4475） +     fb_shutdown()の後では、end-of-processクリーンアップは何もすべきではありませんが、クリーンアップ中にファイルを作成できるらしい状況があることが報告されました。これは修正されました。 + A. Personが修正しました。 +     ~ ~ ~      + + （CORE-4384） +     テーブルのサイズが65535ポインタページを超えた場合に問題が発生していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4383） +     update_in_place()で、インデックスとBLOBのガベージコレクションが動作していませんでした。 + D. Yemanov、D. Sibiryakovが修正しました。 +     ~ ~ ~      + + （CORE-4382） +     ユーザーによるセーブポイントがコミットの際に解放されていませんでした。 + D. Sibiryakovが修正しました。 +     ~ ~ ~      + +
+ +
+ サーバークラッシュ + （CORE-4616） +     同じコンテキスト変数が別のスレッドから同時にアクセスされている場合にサーバーがクラッシュすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4588） +     クライアントがインデックスのナビゲーションスキャン中に異常切断された場合、スーパーサーバーがダウンしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4500） +     ロックテーブルの共有メモリのリマッピングが失敗した後でFirebirdがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4075） +     計算済みのインデックスで例外が引き起こされた場合にサーバーのバグチェックまたはクラッシュが起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ ストアドプロシージャ／トリガ言語（PSQL） + （CORE-4604） +     EXECUTE STATEMENTの間にUTF8 varcharのchar_length()サイズが予期せず増加していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4566） +     実行可能な文、プロシージャ、または関数がメタデータのキャラクタ・セットでシステムフィールドを使用する場合、出力パラメータまたは引数が不正なサイズとなっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ コマンドライン・ユーティリティ + +
+ isql + （CORE-4578） +     isqlのINPUTファイルが適切に閉じられていませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-4452） +     AUTODDL=OFFの場合、isqlで二つのコレーションを異なる名前で作成することができませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +
+ +
+ nBackup + （CORE-4461） +     nBackupがstderrではなくstdoutにエラーメッセージを表示していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+
+ +
+ POSIX固有のバグ + （CORE-4624） +     FirebirdはPOSIXのマウントテーブルエントリーでコロン文字の処理に誤りがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+
+ + + +
+ Firebird 2.5.3アップデート1リリース + 以下のバグフィックスは、以前のリリースのスーパーサーバーとスーパークラシックサーバー・モデルで発見された脆弱性に対処したものです： + （CORE-4630） +     サーバーが不正な形式のネットワークパケットによりセグメンテーション違反を起こし、クラッシュすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+ + +
+ Firebird 2.5.3リリース + バージョン2.5.3リリース以前に修正されたものとして、以下の改善とバグフィックスが報告されました： + +
+ コアエンジン + + （CORE-4460） +     いくつかの組み込み関数を含む式がうまく最適化されないことがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4444） +     物理バックアップ中のout-of-disk-space状態で、エンジンがハングアップし、全てのアタッチメントをブロックすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2648） +     nBackupの増分ファイルへの書き込みがデータベースのForced Writesの設定を無視していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4433） +     誰かが読み取りを行っている場合、グローバルな読み取り／書き込みロック（GlobalRWLock）がEXロックをSHへとダウングレードできませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4372） +     二つのデータページが相互参照するレコードフラグメントを含んでいる場合、デッドロックが起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4353） +     ソーティングレコードが必要以上に大きくなっていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4302） +     降順インデックスでの検索（またはスキャン）が、いくつかの検索キーで非常に非効率となることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4299） +     EXTRACT()関数でWITH THE EXTRACTを使用した場合、エラーInappropriate self-reference of columnが発生することがありました。 +     ~ ~ ~      + + （CORE-4283） +     複数イベントの一斉登録中にエラーResource temporarily unavailableが発生ことがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-4251） +     Guardianサービスがイベントログのメッセージの末尾の後に不要なデータを書き込むことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4250） +     Guardianでプロセスのシャットダウンの時にアクセス違反が発生することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4216） +     TRIGGER ON TRANSACTION COMMITでメモリリークが起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4214） +     グローバル一時表（GTT）が、できないはずの永続的リレーションへの参照ができていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4211） +     シャットダウンプロセスのタイムアウトとfirebird.logに書き込まれる無効なmutexに関するエラーで、エンベデッドエンジンが終了中に5秒間ハングアップすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-4198） +     SQL文が16進数リテラルで終わっている場合に不正なtoken unknownのエラーが発生していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4145） +     ドメインを使用するEXECUTE BLOCKのプリペア中にメモリリークが起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4144） +     UNIONを用いたクエリのプリペア中にエラーcontext already in use (BLR error)が発生していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4143） +     fbembed.dllでメモリリークが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4139） +     計算インデックスのマッチング中にエラーinvalid streamが発生する場合がありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4135） +     スーパーサーバーで、スイープが複数のアタッチメントが同時に確立するのをブロックしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4134） +     自動スイープが開始された時に競合状態が発生することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4118） +     派生フィールドまたはビュー・フィールドに式インデックスが使われないことがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4117） +     COMPUTED BYフィールドが、例外パラメータとして直接使用された場合、NULLとして評価されていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4113） +     EXECUTE BLOCKのプリペアに失敗していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4102） +     OR句がunionに適用されている場合の最適化が不十分でした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4101） +     無効なI/O error during write operationエントリーが、そのようなデータベースエラーがない場合にもfirebird.logに現れていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4100） +     自動スイープが必要のない時に起動することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4083） +     COALESCE（またはIIF）を使った派生テーブルでの完全な外部結合が正しくNULLを返していませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4058） +     サーバーにリモートスタックバッファオーバーフローがありました。 + A. Peshkovにより修正され、特別リリースFirebird 2.5.2アップデート1としてリリースされました（詳細は下記details below）。 +     ~ ~ ~      + + （CORE-4050） +     SQLダイアレクトがセキュリティ・データベースへの内部接続に設定されていませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-4051） +     32KB以上のレコードのソートを行った場合にメモリリークが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4038） +     格納されたDBKEYの最適化に失敗していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4036） +     長く圧縮不能なデータをテーブルに格納しようとした場合にバグチェックまたはデータベースの破損が起こることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4005） +     再帰CTEの失敗が誤ったエラーメッセージを返していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4004） +     時間のかかる操作が時々、非同期シャットダウン／キャンセル・リクエストで中断されないことがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4002） +     データベース・トリガON COMMIT TRANSACTIONにエラーメッセージindex unexpectedly deletedが現れることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3989） +     多数の同時ソートが実行されている時にパフォーマンスの悪化またはレスポンスの遅延が起きていました。 + D. YemanovとV. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3981） +     ビューからのselect実行中に演算子のチェックが最適なものとなっていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3978） +     スイープ中に無効なトランザクション・カウンターがfirebird.logにレポートされることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3940） +     ファイルXXXXへのGetFileSize操作中にI/Oエラーが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3924） +     グローバル一時表（GTT）が最低一つのリード・コミッティッドな読み取り専用トランザクションが含まれている場合に並行した変更が行われると、バグチェック291（cannot find record back version）が起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3921） +     エラーrecord disappeared (186), file: vio.cpp line: 408が発生し、CPU負荷100％となることがありました（bugcheckabort=1で、スイープがgap ~21000で開始した場合）。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3916） +     大きなテーブルで誤った検証のエラーが発生することがありました。すなわち、Index x is corrupt (missing entries) in table ... + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3902） +     派生フィールドがインデックスの使用で最適化されないことがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3874） +     左結合の結果セットで存在しない行にも関わらず計算項目が現れていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3817） +     ゼロ以外の遅延の値が指定された場合、データベースの強制シャットダウンが動作しませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3360） +     UPDATE ... RETURNING ... がRETURNING句だけに存在するカラムに対してエラー -551（更新許可がありません）を引き起こしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3305） +     無効なトリガを作成・変更すると、その後にBLOB not foundのエラーが起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2848） +     競合が比較的高い場合、lock conversion deniedまたはlock deniedのエラーが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2648） +     nBackupの増分ファイルへの書き込みがデータベースのForced Writesの設定を無視していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2165） +     厳密な不等価条件が使われている場合、不必要なインデックスの読み込みが起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1604） +     ユーザーの名前に非asciiキャラクタが含まれている場合、データベースの作成時にエラーが起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1475） +     アクティブなアタッチメントを持つデータベースが、データベースがシャットダウンした後でもgbakのバックアップファイルで置き換えられないことがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1295） +     DB_KEYを持つクエリの最適化が不十分でした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + 改善点 + + （CORE-4445） +     物理バックアップ（ALTER DATABASE BEGIN/END BACKUPまたはnBackupユーティリティを用いるもの）で、バックアップ状態がストールドからマージに切り替わる時、メインのデータベース・ファイルの伸張が高速化されるよう改善されました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-4443） +     fallocate()をサポートするLinuxシステムでファイルの高速な伸張が可能になりました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-4432） +     アロケーションテーブルが初めて読み込まれる時にアタッチメントが他をブロックすることがなくなりました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-4431） +     物理バックアップ状態がストールした時のアロケーションテーブル・ロックの競合が低減されました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-4386） +     object in useのエラーに関するレポートが詳細になりました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-4252） +     エラーを起こした文脈を特定しやすくするため、整合性制約検証エラーメッセージのテキスト中にリレーション名が追加されました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-4215） +     SET STATISTICS INDEX文を実行しても並行するアタッチメントがブロックされたり遅延したりしなくなりました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-3994） +     スイープ終了時のlimboトランザクションのスキャンが改善されました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-3881） +     インデックスと制約の違反に関するエラーレポートが拡張され、問題のあるキーの値を含むようになりました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-3704） +     現在の接続と現在のトランザクションについての詳細情報を取得するため、SYSTEM名前空間に、新しいコンテキスト変数が追加されました。 + 追加された変数：現在の接続についてはSYSTEM::CLIENT_PIDおよびSYSTEM::CLIENT_PROCESS、現在のトランザクションについてはSYSTEM::LOCK_TIMEOUTおよびSYSTEM::READ_ONLY。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-4438） +     エンベデッドSQL（ESQL）にUPDATE OR INSERT文のサポートが実装されました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-4437） +     エンベデッドSQL（ESQL）にRETURNING句のサポートが実装されました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-4047） +     外部関数（UDF）への入力パラメータ数の上限が15まで拡大されました。 + A. dos Santos Fernandesが実装しました。 +     ~ ~ ~      + +
+ +
+ サーバークラッシュ + + （CORE-4319） +     トレース設定にconnection_id=NNの行が含まれている時に存在しないデータベース／エイリアスへの接続が試みられた場合、エンジンがクラッシュすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4300） +     バッファサイズ = 0でiscDatabaseInfo()が呼び出された場合、サーバーが異常終了していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4267） +     データベースのスイープ中にサーバーがクラッシュすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4212） +     グローバル一時表（GTT）で外部キー制約を削除するとサーバーがクラッシュしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4127） +     サイズオーバーのキーに遭遇した時、エラーkey size exceeds implementation restrictionをレポートせずにサーバーがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4123） +     文字列を大文字に変換するトリガから呼び出されたストアドプロシージャを実行する時にサーバーがクラッシュすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4121） +     エンジンがUDFから呼び出されたBLOB GET/PUT関数内でシャットダウンする時にセグメンテーション違反が起こることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-4093） +     巨大な数値を文字列に変換している間にサーバーがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-4045） +     データベースのシャットダウン中にサーバーがクラッシュすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3996） +     制限されたパスでデータベースを作成しようとした時にFirebirdがクラッシュしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3993） +     進行中のアタッチメントを持つデータベースのシャットダウン中にサーバーが終了するかクラッシュすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3988） +     トレースまたは監査がアクティブな時にエンジンがクラッシュすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3979） +     自律型トランザクションで変更をロールバック中にサーバーがクラッシュすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3944） +     アタッチメントを削除してオフラインでデータベースを移動させるスクリプトを実行すると、サーバーがクラッシュしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3908） +     多数の自律型トランザクションが開始・終了している時にエンジンがメモリリークを起こしてクラッシュすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ ストアドプロシージャ／トリガ言語（PSQL） + （CORE-4247） +     DELETE WHERE CURRENT OF {カーソル} が新しく追加されたフィールドを持つテーブルで失敗していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4244） +     DOS864キャラクタ・セットの連結したテキストを含むプロシージャの作成に問題がありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4233） +     宣言済みのカーソルを持つPSQLモジュールで、エンジンが誤った変数に値を割り当てることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4210） +     出力パラメータに付けたコメントがプロシージャの変更後に保存されていませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4204） +     IF (x = (SELECT ...)) 文を含むプロシージャのコンパイル時にエラーが発生していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3054） +     ユーザーのロールが外部のEXECUTE STATEMENT呼び出しを通じて渡されていませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3998） +     パラメータ化されたEXECUTE STATEMENT呼び出しが失敗することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3895） +     PSQLコードが修正されたデータを含むストアドプロシージャからselectを実行する時に高いメモリ使用量を示していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + +
+ +
+ 国際言語のサポート + （CORE-4136） +     Sharp-Sのキャラクタが誤ってUNICODE_CI_AIコレーションで取り扱われていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-4125） +     COLLATE UNICODE_CI_AIをインデックスなしのWHERE句で使用すると極端に遅くなっていました。 + A. dos Santos Fernandes、T. Martirが修正しました。 +     ~ ~ ~      + + （CORE-3949） +     ICU 49でUNICODEコレーションが動作しませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2912） +     小文字のy-トレマ（ISO8859_1コード0xFF）を含む文字列を大文字化する時に例外が発生していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +
+ +
+ コマンドライン・ユーティリティ + +
+ gfix + （CORE-4297） +     RDB$TRANSACTIONSでのlimboトランザクションの説明が1KBを超えた場合にgfixがクラッシュしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + +
+ +
+ fbsvcmgr + （CORE-4298） +     fbsvcmgrがsts_record_versionsなどのstsスイッチの認識に失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3969） +     fbsvcmgrをaction_trace_start、_list、_stop付きで何度も繰り返し実行すると、メモリリークが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + +
+ +
+ fbtracemgr +
+ +
+ gbak + （CORE-4417） +     gbakがドイツ語のウムラウト付きのキャラクタを含むインデックスまたは主キーをコミットすることができませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3995） +     バージョン2.5.2、スイッチ-Vと-Yが一部で失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ gsec + （CORE-3932） +     gsecを使用した場合、ユーザー名にダブルクォートを含むユーザーの作成はできましたが、削除ができませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ qli + + （CORE-4327） +     qliでNULLのBLOBをデータベース間でコピーするとエラーが起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ isql + + （CORE-4137） +     isqlが-extractから誤ったメタデータを返していました。具体的には、データ型とPSQL変数定義のキャラクタ・セット引数の間にスペースを入れておらず、そのため、出力スクリプトで構文エラーを引き起こしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +
+
+ +
+ データベースの監視／管理 + + （CORE-4010） +     取得操作をDELETE FROM MON$STATEMENTSを介して後から中断することができませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3977） +     DELETE FROM MON$STATEMENTSが、そこそこ長い取得を行っているSQL文を中断しませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3935） +     同じマシンの別のデータベースにDELETE FROM MON$ATTACHMENTSを発行した後に、TCP/IPを介したデータベースへの接続ができなくなっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ トレース／監査 + （CORE-4225） +     データベースレベルのトリガを持つデータベースで活動のトレースを行おうとすると、サーバーがクラッシュすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-4094） +     トレースの出力で誤ったパラメータの順序が示されていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3970） +     POSIXで、トレースが不正確なタイマーを使用していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ サービスマネージャ + + （CORE-4303） +     サービスの破棄中に競合状態が起こることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-4224） +     サービスAPIを通じたデータベースの置換に失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3942） +     サービスAPIを用いたgbakバックアップからリストアを行う場合のエラーメッセージでいくつかの問題が明らかになりました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ Windows固有の問題 + （CORE-3243） +     CURRENT_USERとMON$USERが信頼された認証でエラーを起こしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3183） +     fbembed.dllが自身と同じフォルダからicuin30.dllをロードしていませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + Improvements + （CORE-4439） +     Windows上のスーパーサーバーとスーパークラシックサーバーへの最大接続数が1024から2048に拡大されました。 + P. Beachが実装しました。 +     ~ ~ ~      + +
+ +
+ POSIX固有の問題 + （CORE-4031） +     Debian Ubuntu 64のmake installに誤りがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-4011） +     Red Hat、Mageiaで稼働するスーパークラシックサーバーとスーパーサーバーで、開始／停止状態が検出されていませんでした。 + P. Makowskiが修正しました。 +     ~ ~ ~      + +
+ +
+ + + +
+ Firebird 2.5.2セキュリティアップデート1、2013年3月 + （CORE-4058） +     2013年3月にFirebirdサーバーでのリモートスタック・バッファオーバーフローが見つかりました。これにより、認証されていないユーザーがサーバーをクラッシュさせたり、リモートからコードを実行することが可能となっていました。 + ビルド番号23539以下の全てのFirebirdバイナリと、2013年3月8日より前の全てのスナップショットにはこの脆弱性があります。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ + + +
+ Firebird 2.5.2リリース + バージョン2.5.2リリース以前に修正されたものとして、以下の改善とバグフィックスが報告されました： + +
+ 改善点 + + （CORE-3727） +     改善点 :: FirebirdのビルドシステムにCプリプロセッサフラグのサポートが追加されました。 + A. Peshkovが実装しました。 +     ~ ~ ~      + + （CORE-3656） +     改善点 :: トレースAPIでスイープの情報がサポートされました。 + + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-3598） +     改善点 :: TRACEが、トランザクション終了後に起こるアクションの統計情報を生成するようになりました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-3539） +     改善点 :: TRACEに、実行時に発生したエラー（ロックコンフリクトやキー違反など）のログを取る機能が提供されました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-2668） +     改善点 :: 自動スイープの開始時、firebird.logにログが書き込まれるようになりました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-2666） +     改善点 :: リモートのバックアップ／リストアを実行するAPIが利用できるようになりました。 + See also /doc/README.services_extension in your Firebird installation. + A. Peshkovが実装しました。 +     ~ ~ ~      +
+ + +
+ コアエンジン + + （CORE-3877） +     ビッグエンディアンのプラットフォーム上で、関数CHAR_TO_UUIDとUUID_TO_CHARが正しく動作しませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3855） +     GLOBAL TEMPORARY TABLE ON COMMIT DELETE ROWSに書き込まれるBLOBが、既存のデータページに十分な空き領域がある場合でも、新しく割り当てられたページに配置されることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3853） +     Firebird 2.5.1で作成されたデータベースをFirebird 2.5.0で使用する場合、IS NULL句に異なる評価が与えられることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3844） +     検証が、特定の場合にインデックス破損の検出に失敗していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3841） +     行が挿入された際のデータベースの破損が放置されることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3825） +     トランザクションがisc_tpb_autocommitオプション付きで開始された時に、EXECUTE STATEMENTを用いたDDLを起動しようとすると、バグチェック287（too many savepoints）を生成していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3799） +     AUTONOMOUS TRANSACTIONオプションと一緒に使うとWITH CALLER PRIVILEGESオプションが動作していませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3792） +     バッチ挿入のパフォーマンスが低下していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3791） +     エンジンがRAMの容量より大きなデータベースで活発に作業している時にパフォーマンスが低下していました。 + N. Samofatov、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3761） +     BLOBをEXCEPTION文の引数として使用した時に変換エラーが起こることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3730） +     関数isc_dsql_exec_immed2()がRETURNING句に入力パラメータの値を渡す際にそれを失ってしまいました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3722） +     IS NOT DISTINCT FROM NULLがインデックスを利用できる場合にそれを使っていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3697） +     UNION句を含むビューからselectを実行する場合に文字列切り捨てのエラーが発生することがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3692） +     UNIQUE制約に関わっているカラムでNOT NULL制約を削除できませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3690） +     いくつかの曖昧なクエリに対して誤った警告メッセージが返されていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3677） +     外部関数がエンベデッドモードで使われた時に発生することのあるバグによりユーティリティがエントリーポイントをエクスポートするのを防ぐ必要がありました。 + + ISC APIをエクスポートする必要があるスーパーサーバーのバイナリは唯一の例外です。 + + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3675） +     CREATE INDEXが複合インデックスでNULL値と空の文字列を同じもののよう扱っていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3631） +     NULL値を持つ重複レコードが正しくチェックされていませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3610） +     一意なインデックスに重複キーを書き込むことが可能となっていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3601） +     トリガを持つビューでTEXT BLOB charsetの不正な変換が起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3599） +     システムロールRDB$ADMINの削除が可能になっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3579） +     計算項目が後から作成された別のカラムに依存している場合にテーブルを削除できませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3557） +     削除中のテーブルに対するクエリのプリペア中にサーバーがクラッシュしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3490） +     名前付きカーソルの使用中に並列処理上の問題が起こることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3238） +     GEN_UUID()にRFC-4122準拠のバイナリUUIDを返させること。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3092） +     ROW_COUNTが単体でのINSERT文の前にクリアされていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2457） +     UNICODE_CIコレーションが内部gdsソフトウェアの整合性チェックを引き起こしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1997） +     マルチレベルのコレーションを使用するマルチセグメントのインデックスへの外部キー処理が失敗していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1992） +     エラーbad BLR -- invalid stream for union selectが不適切にスローされていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-927） +     ビュー内で使用されるプロシージャで、権限付与が動作しませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ サーバークラッシュ + （CORE-3884） +     トレースが有効な場合、空のクエリのプリペア中にサーバーがクラッシュすることがありました。 + D. Starodubov、V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3873） +     キャッシュへの書き込み中にディスクI/O違反が起こった場合、シャドウへの切り替え中にサーバーがクラッシュすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3834） +     派生テーブルでのNATURAL JOINの使用がサーバーをクラッシュさせることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3814） +     Forced Writes offでのデータベースのシャットダウンの実行中にスーパークラシックサーバーがクラッシュすることがありました。 + V. Khorsun、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3636） +     トレースAPIがバージョン2.5.1のサーバーをクラッシュさせていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3627） +     一意なインデックスを持つテーブルに行を挿入すると、アクセス違反でサーバーがクラッシュすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ データ操作言語 + （CORE-3807） +     マルチバイト接続の際にGROUP BY句内で文字列リテラルが使われている場合、エラーInvalid expression in the select listが予期せず発生することがありました。 + D. Yemanov、a. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3806） +     ORDER BY句内でサブクエリまたは計算フィールドがベーステーブルを参照している場合に誤ったデータが返されていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3777） +     GROUP BYを使っている場合に予期せぬconversion error from stringのエラーが起こることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3683） +     再帰クエリがエンベデッドなGROUP BY句を含んでいる場合、誤った結果が生成されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3736） +     いくつかのテーブルで、読み取り専用権限を持つユーザーがWITH LOCK句を使い、そのテーブルの更新をブロックすることができていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3611） +     同じカラム名が繰り返し現れるCTEまたは派生テーブルからの取得中に誤った結果が起こることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +
+ +
+ コマンドライン・ユーティリティ + +
+ fb_lock_print + （CORE-3686） +     fb_lock_printの出力でのacquire blocksとmutex waitのカウンターで不正な値（ゼロ）がレポートされていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ fbsvcmgr + （CORE-3658） +     fbsvcmgrユーティリティがISC_USER環境変数の値ではなくOSユーザー名でサーバーに接続していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+ +
+ fbtracemgr + （CORE-3770） +     fbtracemgrユーティリティが全く活動していない時に55％ほどまでのCPU負荷を掛けていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3769） +     fbtracemgrがCtrl-Cで中断された場合にメッセージUnknown tag (4) in isc_svc_query() resultsが現れていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ gbak + （CORE-3875） +     gbakがパラメータの正しいチェックに失敗しており、-B :を指定した場合、ランダムなデータベースをバックアップしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3802） +     Firebird 2.5.1で、データベースのバックアップからのリストア中にメモリを使い果たすことがありました。 + A. dos Santos Fernandes、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3733） +     gbakリストア中にシステムジェネレータの修復に失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3649） +     gbakが、すでに正常に閉じられた後でエラーが発生した場合でも、バックアップファイルを削除していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ gsec + （CORE-3762） +     gsecがいくつかのエラーに対してゼロのリターンコード（no error）を返していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+ +
+ isql + （CORE-3810） +     isqlで、-pag 0コマンドスイッチがSET HEADING命令を含むSQLスクリプトで使われた場合、ゼロ除算またはコアダンプが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      +
+
+ +
+ データベースの監視／管理 + （CORE-3625） +     MON$IO_STATSが（ASTレベルで）非同期で実行されたページ書き込みを報告していませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2286） +     PSQLモジュール内でのMON$CALL_STACKからのselectが、時々ゼロの行を返していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ トレース／監査 + （CORE-3860） +     トレースAPIの不完全なデータベースフィルタがサーバーをクラッシュさせることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3845） +     重いクエリが中断された時、その時間がトレース統計にゼロミリ秒として記録されていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + +
+ +
+ サービスマネージャ + （CORE-3612） +     gfix関連のサービスが、isc_service_start()のステータスベクターのエラー値を失うことがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ POSIX固有の問題 + + （CORE-3912） +     スーパークラシックサーバーで、変数INET_selectのGlobalPtr<>が欠けていたため、セグメンテーション違反が起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3750） +     さまざまな上限の拡大がPOSIXではエラーを起こすことがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3721） +     マルチユーザーのサーバーで、ISC_変数が設定されていた場合、スタートアップスクリプト（/etc/init.d）がこれらを拾っていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3646） +     Linux上で、FreePascalのマルチスレッドプログラムがバージョン2.5.xのクライアントライブラリを使っている場合にセグメンテーション違反が起こっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3609） +     オプション-tがfb_inet_server -hによって二度表示されていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3607） +     Solarisで、RLIMIT_NPROC制限が定義されていなかったため、このプラットフォームでのsrc/remote/inet_server.cppのコンパイルに失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3606） +     Solarisでのコンパイルの問題を回避するため、CまたはC++コンパイラを使うリンカコマンドが、それぞれCFLAGS、CXXFLAGSを適用する必要がありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3605） +     GLOB_OPTIONSがCFLAGSとCXXFLAGSを混在させ、これらがプラットフォーム間で互換性を持つかのように見せていました；しかし、コンパイラ実装の違いにより、両者の違いが排他的となることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ Mac OS X Lion + （CORE-3911） +     Mac OSXで、APIエントリーポイントBopenとBLOB_openが見えなくなっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3786） +     Firebird 2.5.1のクラシックサーバー（32bit版）が、再起動直後、isqlでのデータベース作成中にハングアップしていました。そこでisqlをkillして操作をやり直すと今度は成功し、次の再起動まで再び失敗することはありませんでした。この問題は約90％の再現性がありました。 + P. Beach、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3740） +     標準の64bitバイナリ版で、引数に153以上の要素を持つIN()演算子を使用するSELECTがクラッシュを起こしていました。これは、コンパイラで使われる最適化セット（フラグ -03）の問題であることがわかりました。 + P. Beach、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3682） +     Firebird 2.5.1が第二のデータベースへのアタッチ中にハングアップしていました。 + P. Beach、A. Peshkovが修正しました。 +     ~ ~ ~      +
+ +
+ +
+ リモートインターフェース／API + （CORE-3819） +     データベース接続文字列内のポートアドレスに対するサービス名の解決が誤って実行されることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3812） +     セッション中に膨大な数の主キーが削除および／または変更されている時、クライアントがデータベースへの接続を失うことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3801） +     ステータスベクターで警告が二度現れることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3778） +     接続のシャットダウン中にアクセス違反が起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3732） +     データベースへのアタッチメントを閉じるとセグメンテーション違反を起こすことがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3569）    CHAR(32767)が長さ32765でXSQLVARに現れていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ + + +
+ Firebird 2.5.1リリース + バージョン2.5.1リリース以前に修正されたものとして、以下の改善とバグフィックスが報告されました： + +
+ コアエンジン／API + + （CORE-3537） +     改善点 :: ON COMMIT DELETE ROWSオプション付きで作成されたグローバル一時表に加えられたトランザクションの変更のロールバックの取り消しは不必要だったため、削除されました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-3536） +     改善点 :: 他のアタッチメントでアクティブなトランザクションにより、グローバル一時表でのガベージコレクションに不必要な遅延が起きていました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-3457） +     改善点 :: 小さなチャンクの割り当てに関して、テンポラリ・スペース・マネージャに一層の最適化がなされました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-3323） +     改善点 :: ロックマネージャに待機状態をキャンセルする機能が提供されました。 + 以下の例を考えてみます： + + tx1: update table t ... where id = 1 + tx2: update table t ... where id = 1 + + トランザクションtx2がWAITモードにある場合、tx1の終了までえんえんと待機し続けることになり、この待機状態はDELETE FROM MON$xxxまたはfb_cancel_operationのリクエストを用いても解消されませんでした。 + この改善により、ロックマネージャに、このような果てしない待機状態を取り消す機能が提供されました。 + V. Khorsunが実装しました。 +     ~ ~ ~      + + （CORE-3295） +     改善点 :: オプティマイザで実際のレコード圧縮比を推定し、テーブルの濃度（格納されたレコード数）に関するより正確な推測ができるようになりました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + + + （CORE-3560） +     バージョン2.5のクラシックサーバーがメタデータのキャッシングの際にバージョン2.1.5より多くのメモリを使用していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3549） +     セッション終了時にデータベースの破損が起こり、エラーpage xxx is of wrong type expected 4 found 7がスローされることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3547） +     浮動小数点の負のゼロがインデックスでは正のゼロと同じになっていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3535） +     nbackupの状態の変更時にエラーが発生した場合、不正なページの書き込み対象が未定義となることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3533） +     スーパーサーバーで、クライアントのアプリケーションによってプリペアされキャッシュされた全てのSQL文のハンドルを明示的にリリースせずに接続が終了された場合に、メモリリークが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3532） +     トレースの実行中に新たなセッションの開始されるとサーバーがハングアップしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3525） +     自律型トランザクションが"親"トランザクション実行時のフラグを誤って継承していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3515） +     インデックスが更新されて同期が外れ、エントリーを失わせる複合的な条件下で、インデックスの破損が発生することがありました。これは検証によってピックアップされ、"missing entries"のメッセージがfirebird.logへと書き込まれていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3512） +     トレースの実行中にサーバーがハングアップすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3509） +     ALTER PROCEDUREが既存のものと同じ名前を持つパラメータの追加を許可していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3502） +     DROP VIEWがカラム以外の既存の依存関係を無視していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3494） +     シャットダウンがfb_shutdown_callback()にインストールされたハンドラによってリジェクトされた後では、アタッチがどうしてもうまく行きませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3491） +     PSQLモジュールのTYPE OF COLUMNパラメータを変更すると、元のカラムに影響が出ていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3461） +     バックアップ・リストアの後でDDLの操作が失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3443） +     UDFライブラリの検索中に競合状態が発生することがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3418） +     INACTIVEとして作成されたデータベースのトリガがアクティブになっていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3398） +     GRANT ADMIN ROLEが受け付けられませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3397） +     intlとトレース・ライブラリに未解決のシンボルが見つかっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3394） +     一意性制約違反を起こした場合に、ステータスベクターに不要なlock conflictエラーが残されることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3341） +     自律型トランザクション内にポストされたイベントが消失し、リスニング中のクライアントに通知されていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3340） +     空の例外ハンドラを持つ自律型トランザクションで、一意なキーカラムのプライマリに重複した値が挿入され、バックアップをリストアできなくなるることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3327） +     ネットワークサーバーのスレッドプールが必要以上のスレッドを作成することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3326） +     速いmutexが、死んだプロセスによってロックされた状態のままになることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3325） +     高負荷状況下で、新たなプロセスが共有メモリのマッピングに失敗する可能性がありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3315） +     監査プラグインが正規のものの後に第二の *失敗した* EXECUTE_STATEMENT_FINISH を記録していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3314） +     プロシージャとそれが依存しているテーブルが同じトランザクションで削除された後で、依存関係が解消されていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3312） +     従属テーブルがOR句によって親テーブルに依存している場合、結合のplanが最適なものとなっていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3306） +     インバリアントなサブクエリがバリアントなものとして扱われており、そのため、ネストされたストアドプロシージャに対する複数回の呼び出しが起こっていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3283） +     サブクエリでLEFT OUTER JOINを使うクエリで不正なplanが生成されていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3282） +     EXECUTE STATEMENTがSQLのテキスト引数をパーシングする際に誤ったキャラクタ・セットを使用していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3266） +     非同期サービスによるデタッチのリクエストと起動中のユーザートレースサービスとの間で競合状態が起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3256） +     明示的なplanを持つビューに対する選択クエリのパーシング中にエラーrequest depth exceededが現れることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3237） +     ストアドプロシージャのコンパイルに時間がかかりすぎていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3207） +     トランザクションの開始時にFB_965910463_Class.isc_start_multiple内にAccessViolationExceptionがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3205） +     isc_dsql_exec_immed2()がエラーコードisc_stream_eofとisc_sing_select_errを、これらのエラー発生時に返していませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3188） +     エラーPage 0 is of wrong type (expected 6, found 1)が予期しない場合に起こっていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3176） +     サブクエリから派生したカラムを持つビューが、インデッックスを使わずに、サブクエリの出力をテーブルに結合していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3168） +     トレース機能の<サービス>セクションでexclude_filterが動作していませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3157） +     ストアドプロシージャにパラメータの説明を加えると、メモリが大量に消費され、実行時間が長くなることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3151） +     sqlda_supに割り当てられたメモリがいつまでもリリースされない場合がありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3148） +     SQZ_apply_differencesで危険なコードが見つかりました。 + D. Kovalenko、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3140） +     パラメータに付けたコメントがプロシージャの変更後に保存されていませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3137） +     データを修正している選択型プロシージャで、部分的なロールバックが可能となっていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3131） +     WIN1257_LV（ラトヴィア語）コレーションで、A、E、I、Uの四つの文字に誤りがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3125） +     ルーチンWorker::shutdown()でアクセス違反が起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3058） +     前に32,767以上のジェネレータが作成されていた場合、新しく作成されたジェネレータは誤った値を持っていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3029） +     例外ハンドラを含むEXECUTE BLOCKから例外が発生した後のロールバックで、バグチェックToo many savepoints (287)が起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3024） +     ALTER VIEWの後で、エラーno current record for fetch operationが起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2835） +     selectに主キー・インデックスを使う必要がある場合に、ナチュラルキーが使われていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2827） +     多くのトリガと間接的に関わる操作のプリペア中に、相互に関連する複雑なメタデータのプリペアに非常に時間がかかっていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2709） +     NULL値を持つ複合インデックスで、インデックス付きの読み込みが過剰に行なわれていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1752） +     異なるコレーションを持つ結合の結果が、使用するexecution planによって違うものになっていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1274） +     PLAN MERGEが選ばれて、等価演算子の引数のデータ型が異なっている場合、結果が誤っていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ サーバークラッシュ + + （CORE-3554） +     リモートで空のSQLクエリを渡すと、プリペア中にサーバーがクラッシュするか、または不正なパーシング・エラーがスローされることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3557） +     削除プロセスに入っているテーブルに対するクエリのプリペア中にサーバーがクラッシュすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3524） +     使用中のストアドプロシージャの再コンパイル中にサーバーがクラッシュしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3503） +     古いバージョンでは正規の文脈となる位置に、新しいバージョンでは不自然な（aggregateまたはunionの）ストリームがある場合に、ALTER VIEWがサーバーをクラッシュさせていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3477） +     存在しないSQLパラメータが渡された場合にサーバーがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3440） +     isc_que_events()のqueueに入っているイベントが0の場合、サーバーがクラッシュしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3247） +     BLOBにキャラクタ・セットがUTF8のデータがある場合にサーバーがクラッシュしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3419） +     自律型トランザクションがロールバックされるとサーバーがハングアップまたはクラッシュすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3400） +     FreeBSD8.2R上でしばしばサーバークラッシュが起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3374） +     最新のフォーマットではないレコードに対してSELECT WITHが発行された場合にサーバーがクラッシュしたり、データが破損することがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3320） +     特定のMERGE構文でサーバーがクラッシュすることがありました。詳細は公表されていません。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3255） +     GROUP BY句を持つビューを使うとサーバーがクラッシュすることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3219） +     DSQL_unprepareを使うと、トレースマネージャがサーバーをクラッシュさせていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3217） +     複数の接続が同時にアタッチまたはデタッチしている時にロックマネージャ内部でサーバーがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3202） +     execute_immediate API呼び出しファミリーが、リモートサーバーをクラッシュさせることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3180） +     宣言や選択中にマッチングしないカラムを持つALTER VIEWがサーバーをクラッシュさせていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3138） +     MON$テーブルに、その構造を変更した後でアクセスすると、内部エラーまたはクラッシュが起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3064） +     明示的なplanの中でプロシージャの識別子とそのエイリアスの両方を使用すると、サーバーがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ データ操作言語 + （CORE-3523） +     SIMILAR TOが降順の範囲で誤ったマッチングを行っていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3493） +     タイムスタンプに'16.11.1858 00:00:01'以前の値を入力すると、エラー"value exceeds the range for valid timestamp"をスローしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3489） +     union内でのBLOBの変換が時々失敗していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3479） +     ASCII_VAL()関数が空の文字列に対して0を返す所でエラーを起こしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3355） +     インデックスが使われている場合にDATEとTIMESTAMPの比較が誤っていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3353） +     演算子（blob_field LIKE ?）がパラメータをBLOBとしてではなくVARCHAR(30)として記述していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3335） +     マルチバイトBLOBのSUBSTRING関数とその境界引数で内部ラッピングが発生し、誤った結果が出ていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3311） +     パラメータ化したROWS句を用いたUPDATEまたはDELETE文のプリペア中にエラーdata type unknownがスローされていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3302） +     DISTINCTによる集約で、誤った（重複した）データが返されていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3277） +     キャラクタ・セットUTF8のvarcharで、RIGHT()関数が誤った結果を出していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3245） +     長いテキストからなるBLOBに対するSUBSTRING()の操作で、オプションの三番目の引数がなかった場合、返されたBLOBに32767文字しか含まれていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3244） +     三番目の引数があった場合には、空の文字列（''）に対するPOSITION()の結果が誤っていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3233） +     第二のオペランドが32KB以上だった場合、LIKE、STARTING、CONTAININGが失敗していました。 + A. dos Santos Fernandes、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3228） +     マルチバイトのテキストからなる長さ1024バイト以上のBLOBで、RIGHT()関数が失敗していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3227） +     引数がマルチバイトのキャラクタをどこかに含んでいる場合、ASCII_VAL()関数が失敗していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3222） +     WITH CHECK OPTIONを持つビューが、WHERE句で、TRIM()関数の呼び出しに適合しませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3211） +     NOT IN条件を含むビューからselectを行ったときに文字列切り捨てのエラーが起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3210） +     SELECTクエリで、予期しないエラーno current record for fetch operationが発生していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3208） +     再帰クエリが重大なメモリリークを起こしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3203） +     UPDATE OR INSERTでRETURNINGを使うと、Invalid Cursorのエラーを起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3173） +     第二のものにGROUP BY句と内部結合がある、二つの共通テーブル式を含むストアドプロシージャからselctを行うと、誤って何も結果を返しませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3164） +     クライアントがキャラクタ・セットUTF8を使用して接続している場合、BLOBフィールドを含むパラメータ化されたリクエストが失敗していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3141） +     ビューの最後のカラムが値を持っていてもNULLとして返されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3091） +     引数Xが負の数で、Yの値がスケール0でスケーリングされた数値だった場合、組み込み関数POWER(X, Y)が動作しませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +
+ +
+ コマンドライン・ユーティリティ + +
+ gbak + （CORE-3236） +     サービスマネージャスイッチとlocalhost:dbの両方が指定された場合に、gbakがunavailable databaseのエラーをスローしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3249） +     gbak -bの出力ファイルとして使用されていているファイルがすでに存在し、新たなバックアップファイルのサイズが既存のものより小さい場合、バックアップファイルが切り捨てられませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3232） +     -se service_mgrスイッチを付けずにnon-transportableなバックアップを行った場合、元のデータベースより約50％大きいバックアップファイルが生成されていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ nBackup + （CORE-3521） +     nBackupの増分ファイルの内容がディスクに書き込まれていませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3482） +     Linux版のnBackupがCtrl-Cでセグメンテーション違反を起こし、データベースがロック状態になり、増分ファイルが増大し続けていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3297） +     firebird.confがない場合、nBackupが終了の通知を行っていませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3199） +     POSIX版で、リクエストを行なっているユーザーがrootまたは所有者ではない場合、O_NOATIMEフラグが開いていることで、nBackupが失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ fbtracemgr + （CORE-3487） +     fbtracemgrユーティリティが、Ctrl-Cでの終了時に、時々セグメンテーション違反を起こいsていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+
+ fb_lock_prt + （CORE-3454） +     fb_lock_print -cがサーバーをハングアップさせていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+ +
+ gpre + （CORE-3486） +     GPRE言語モジュールがgcc 4.4でコンパイルできませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3022） +     gpreをGCC 4.4.1でコンパイルするとC++コンパイラ警告が出ていました。 + D. Dodsonが修正しました。 +     ~ ~ ~      + +
+ +
+ +
+ データベースの監視／管理 + + （CORE-2305） +     改善点 :: 監視中のスナップショットの間でMON$STATEMENT_ID値を定数としました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-3508） +     MON$DATABASE_NAMEとMON$ATTACHMENT_NAMEフィールドで、どの接続キャラクタ・セットでも、非ASCIIキャラクタがクエスチョン・マークで代替されていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3218） +     SQL文キャンセルのリクエストが、現在実行中のSQLコードによって警告なく無視されることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ サービスマネージャ + （CORE-3261） +     リストア・サービス実行中にアサーションが実行されることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ POSIX固有の問題 + （CORE-3589） +     MacOSXとFreeBSDで、共有ファイルが閉じられると、セマフォがその共有ファイルからデタッチされず、内部リソースリークを起こしていました。このバグは、ISC_event_init()関数が返すエラーに対するチェックが抜けていたため、たまたま見落とされていたものです。これは、MacOSX 10.7でスーパーサーバーとスーパークラシックサーバーの起動に失敗していたことから明らかになりました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3544） +     Linuxでmake installに失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3447） +     4.2より上のバージョンのicuを持つLinuxで、いくつかのコレーションがインストールされていませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3377） +     POSIXでのFirebirdビルド中に、ビルドされたディレクトリではなく既定のディレクトリで、欠けているfbintl.confについての記録をfirebird.logに書き込もうとしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3259） +     POSIXで、ユーザーコードでCtrl-C（終了）を処理する時にデッドロックやセグメンテーション違反が起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3257） +     Linuxで'make install'が失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3229） +     何らかの原因により、エラーOperating system directive open failed, Too many linksがfirebird.logに記録されていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3212） +     FreeBSDでのコンパイルがエラーを起こして失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3194） +     Linuxのスーパークラシックサーバーへの接続数の上限が508になっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3185） +     すでにFirebirdサーバーが稼働しているPOSIXボックスで、root以外のユーザーによるFirebirdのコンパイルを行うと、テンポラリ・ロックスペースでアクセス競合を起こしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3166） +     POSIXでクラシックサーバーからスーパークラシックサーバーへとモードを切り替えるためのスクリプトchangeMultiConnectMode.shがスーパーサーバーのインストールに誤って含まれていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3150） +     Linuxで、gbakがCtrl-Cで中断された時にセグメンテーション違反を起こしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3143） +     Linuxで、ユーザーがgstatを中断した時にセグメンテーション違反を起こすことがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2921） +     FreeBSDで'make install'が動作していませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ Windows固有の問題 + （CORE-3329） +     WindowsのAdministratorsがロールRDB$ADMINを予期せず手にしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3059） +     WindowsサーバーでRemoteFileOpenAbilityにTrueを設定すると失敗していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ リモートインターフェース／API + （CORE-3248） +     改善点 :: メッセージ・バッファ内の未使用のVARCHAR値のバイト数がゼロに設定されるようになりました。 + A. Peshkovが実装しました。 +     ~ ~ ~      + + （CORE-2752） +     改善点 :: SO_KEEPALIVEオプションがクライアントのTCPソケットに設定されるようになりました。 + D. Yemanovが実装しました。 +     ~ ~ ~      + + （CORE-3511） +     非ASCIIキャラクタを持つ、クォートで囲まれていないロール名がデータベースパラメータバッファ（DPB）に渡された時、誤って大文字化されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3389） +     ゼロのトランザクションハンドルを持つisc_dsql_exec_immed2がBUGCHECK(147)を起こすことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3387） +     クライアントライブラリが強制的に切断されたサーバーソケットでの応答パケットを待ち続けていつまでもハングアップしていることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3351） +     Windowsクライアントが接続時にエラーメッセージ10054をfirebird.logに書き込むことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3328） +     クライアントがデータベースのシャットダウン時にエラーメッセージUnsuccessful detach from databaseをfirebird.logに書き込んでいました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3220） +     API関数isc_info_svc_get_usersが結果のクラスタにエラーメッセージを返していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3170） +     EVENTがポストされてもサブスクライバが存在しない場合、エンジンが無限ループに入ることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3119） +     イベント処理に関連したリモートでのプロトコルコードが無限ループを引き起こし、CPU使用率が100％となっていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3095） +     同じトランザクションでイベントが何回ポストされても、クライアントが一回分のイベントしか受け取っていませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + +
+ +
+ + + + + +
+ Firebird 2.5.0リリース + バージョン2.5.0の最終リリース以前に修正されたものとして、以下のバグが報告されました： + +
+ コアエンジン／API + + （CORE-3115） +     内部レコードの圧縮ルーチンにいくつかのバグがありました。 + A. Peshkov、D. Kovalenkoが修正しました。 +     ~ ~ ~      + + （CORE-3103） +     バージョン2.5の第三のリリース候補で、SELECT文がインデックスなしの読み込みを、バージョン2.1.3での同じ文よりも、より多く行っていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3101） +     以前のバージョンから移行したデータベースで、ALTER DOMAINができませんでした。 + A. dos Santos Fernandes、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-3100） +     EXECUTE STATEMENTの外部トランザクションで、WAITモードとロックのタイムアウトのパラメータが、対応するローカルなトランザクションのパラメータとマッチングしていませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3096） +     CORE-2893の修正で入り込んだ不具合のため、SQL文のプリペア中にノードの二重処理が起こり、デバッグ・ビルドでアボートが頻発していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3094） +     選択型ストアドプロシージャからのNOT INでパラメータが動作していませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3090） +     テーブルと派生した定数を返すサブクエリを用いたLEFT JOINの結果が不正なものでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-3089） +     外部のデータソースがInterBase 4.1（ODS 8）のデータベースだった場合、そのデータソースに対してEXECUTE STATEMENTを実行しようとすると失敗していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3079） +     バッチ挿入が全て単一のトランザクション中で実行され、イベントをポストしたトリガを含んでいる場合に極端に遅くなっていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + +
+ +
+ サーバークラッシュ + （CORE-3109） +     NULLのトランザクションでisc_dql_exec_immed3_m()がCREATE DATABASE ...のために呼び出された場合、サーバーがクラッシュしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +
+ +
+ コマンドライン・ユーティリティ +
+ gsec + + （CORE-3116） +     gsecユーティリティがユーザーの出力リストをstdoutではなくstderrに送っていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+
+
+ + + +
+ 旧版でのバグフィックス + バージョン2.5開発中に修正されたものとして、以下のバグが報告されました： + +
+ コアエンジン／API + + （CORE-3034） +     式インデックスへのキーの挿入中に、データベースのシャットダウンやユーザーからのリクエストなど、何らかの理由でリクエストがキャンセルされた場合、バグチェック300（can't find shared latch）を起こすことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3016） +     接続の切断時にFatal lock manager error: invalid lock id (0), errno: 0がfirebird.logに出ることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3015）    さまざまなCannot initialize the shared memory regionのエラーが報告されていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-3003）    SELECT文を介して呼び出されているプロシージャ内にSUSPEND文が存在するかどうかについての新たなチェックは適切に動作していました：プロシージャがSELECT文を介して呼び出された時、SUSPENDが存在しなかった場合、エラーProcedure ... is not selectable (it does not contain a SUSPEND statement)がスローされていました。 + ところが、同じエラー状態がRESTORE中にも発生し、リストアが失敗することがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2995） +     ステータスベクターで、単一のエラーが二回報告されていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2993） +     高負荷なシステムで、モニタリングテーブルの使用中に、ロックマネージャの致命的なエラーInvalid lock id (NNN)が起こることがありました。 + V. Khorsun、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2900） +     DISTINCTによる集約を含むリクエストを使うと定期的に、ただしランダムなメモリアクセス違反が起きることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2977） +     ODSバージョンが10より前のデータベースの、DATE型のインデックス付きフィールドでサーバーが不正な動作をしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2965） +     SINGULAR句を含むサブクエリの後で返されたROW_COUNTの値が規則に反していました。そもそもROW_COUNTは更新または削除の影響を受けた行のカウントを意味するものなので、サブクエリからゼロ以外の値が返されるはずがありませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2956） +     プロシージャのパラメータを処理するリクエストで問題が起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2943） +     二つの再帰部分を持つ再帰クエリのパーシング中にエラーが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2936） +     二つの連続するリーフインデックスページが、二つの異なる接続によって、インデックスから同時に削除（ガベージコレクション）された場合、別のインデックスページで兄弟ポインタが解放されたインデックスページを参照したままになり、リンクしている兄弟ページのリストが壊れることがありました。解放されたページが再び割り当てられると、Wrong page type (expected 7 found N)として、インデックスの破損が報告されていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2916） +     インデックス作成中に変換エラーが発生した場合、エラー処理に失敗していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2893） +     サブクエリ中の式がインバリアントなものとして扱われ、不正な結果を生成することがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2879） +     スイープがエラーpage 0 is of wrong type (expected 6, found 1)を起こすことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2876） +     ALTER DATABASE ADD DIFFERENCE FILE使用時に、おかしなエラー処理が行なわれていたため、エンジンがデータベースのバックアップモードに関して混乱することがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2875） +     4096バイトより長いCHARカラムと文字列定数との比較を行った場合に、文字列右端の切り捨てエラーが起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2871） +     派生テーブルまたはビューが左／右結合とORDER BY句の両方を含み、また、外部クエリもORDER BY句を含む場合、外部のORDER BY句が効果を持ちませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2858） +     セキュリティチェックの失敗を通知する例外が発生した場合にメモリの破損が起こることがありました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2856） +     キーが削除された場合、一意なインデックス中でNULL以外のキーが見つからないことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2833） +     データがnullデータフィールドへの参照を含んでいた場合、式インデックスに影響を及ぼすデータの変更に失敗していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2826） +     UTF-8のデータベースで、結合条件が失敗していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1089） +     ORDER BY句が（メインではない）右側のテーブルのカラムを含んでいない場合、DISTINCTとLEFT JOINを使ったビューからのselectで、誤った順序のレコードが返されていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-195）    BEFORE UPDATEトリガですでにアクションを起こしているいくつかのレコードを更新した際に、すでにバージョン1.5.1で修正されていた古いバグによる不具合により、バグチェック291（cannnot find back record version）が起きていました。この不具合がバージョン2.0で再び入り込みましたが、以前ほど破壊的ではなく、物理的にテーブルの最初にあるレコードのみ影響を受けていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2822）    サブクエリが自明ではない派生テーブルを含んでいた場合、エラーno current row for fetch operationがスローされていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2820） +     初期に施された大きな修正の副作用として、PLAN ORDERを持つクエリが小さなメモリリークを起こしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2815） +     ページインベントリページの変更済み後に変更のマーキングが行なわれていた論理条件の整理。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2785） +     BLOBの変換が不適切に処理される問題が特殊な状況下で現れていました。すなわち、オブジェクト定義付きCOMMENTとして保存される1バイトのキリル文字テキストによる入力引数文字列が、変換時に、先頭以外のBLOBセグメントの最大64KBというサイズ制限を超過していました。この余剰バイトは後続のチャンクへと回されるはずのところ、変換エラーを引き起こしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2783） +     再帰クエリがSELECTリスト内のサブクエリとして使われ、その結果がORDER BY基準として指定された場合、アクセス違反が起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2730） +     RISCマシンで、DB_KEYを使った動作中にバスエラーが起こることがありました：（アライメント要求を持たない）リテラルからdb_keyへとキャストする時、QWORD境界ではアライメントが必要であり、強制的に行なわれるべきでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2722） +     BLOBからNONE/OCTETSキャラクタ・セットでコピーする時に不正な形式のBLOBの保存が許可されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2660） +     外部結合状態でマッチングが見つからなかった場合にCOUNT(*)が誤って0を返していました。現在は正しくNULLが返されます。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2659） +     複雑なビューを含む外部結合クエリのplanが、利用可能なインデックスを利用していなかったことで、最適なものとなっていないことがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2640） +     ある条件下で、ロックマネージャが通常のデッドロックの検出に失敗しサーバーをハングアップさせることがありました。 + V. Khorsun、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2635） +     一意なインデックスが、多くのNULLキーを含んでいた場合にレベル1で破損することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2632） +     モニタリングテーブル使用時に、予期しないInvalid BLOB IDのエラーが起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2616） +     高負荷下でエラーpage <N> is of wrong type (expected 7, found 5)が起こり、何かがデータベースを破損したような印象を与えていましたが、再起動すると、破損した痕跡はありませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2608） +     Windowsの最近のバージョン（64bitのXP以降、32bitのVista以降）で、Firebirdで大規模なデータベースを稼働していると、OSが全RAMをファイルシステムのキャッシュに費やして、応答しなくなりました。Windowsがクラッシュする場合もありました。 + + このイシューはドキュメント化されています。Firebirdでは、ファイルシステムのキャッシュでのRAMの使用量を制御するfirebird.conf中の新たなパラメータFileSystemCacheSizeの実装によって対処しています。 + N. Samofatovが修正しました。 +     ~ ~ ~      + + （CORE-2602） +     キャラクタ・セットNONEを使用するアタッチメントがモニタリングテーブルからの読み込みに失敗することがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2591） +     通常のパフォーマンスがしばらく続いた後で、高いmutex待機率とパフォーマンス低下を示し始めました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2581およびCORE-2582） +     ある状況では、内部・外部関数の呼び出しを含む式の結果としての無限大とNANを、エンジンが例外として捉えていませんでした。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2578） +     結合した一つ以上のテーブルを持つビューからRDB$DBKEYをselectすると、変換エラーを返していました。 + A. dos Santos Fernandes、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2514） +     'temp'ドライブの空きスペースが不十分だった場合に、CreateFileに関するエラーが報告されていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2422およびCORE-2321） +     サーバーがTempDirectoriesで設定された複数の配置間の切り替えを行いませんでした。そのため、最初に設定されたテンポラリ・ディレクトリの空きスペースが不十分だった場合、ソートに失敗していました。たいていの場合、ユーザーは大量のテンポラリ・スペースをリクエストする、ソートまたは他のクエリが'operating system directive write failed. Invalid argument.'のようなエラーを起こして失敗するのを目の当たりにしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2315） +     FirebirdによるFLOATのサポートはオリジナルのInterBaseの仕様に従っていませんでした。IBのドキュメントによれば、FLOATの値は1.175E-38から3.402E38までの範囲になければなりませんでした。クロスプラットフォームで行われたテストでは、オーバーフローを起こさない最大値は < 3.4E38だと証明されています。 + W. Oliverが修正しました。 +     ~ ~ ~      + + （CORE-1991） +     UDFがBLOBパラメータ付きで宣言された場合、エンジンはRDB$FUNCTION_PARAMETERS.RDB$FIELD_LENGTHにnullを格納していました。これにより、実行時に'message length error'が起きていました。 + D. Sibiryakovが修正しました。 +     ~ ~ ~      + + （CORE-1781） +     サブクエリが集約関数によって別の文脈に指示された場合、エンジンが整合性チェックのエラーをスローしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2564） +     RISCマシンで、モニタリングテーブル使用時に、バスエラーがスローされていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2550） +     ビッグエンディアンのマシンで、DB_KEYの使用時にバスエラーがスローされていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2538） +     ストアドプロシージャがEXECUTE PROCEDUREを使って呼び出された場合、PSQLが単体のクエリ結果をそのプロシージャへの入力パラメータとして使用するのを許可しませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2532） +     マルチボリューム・データベースのボリュームサイズが不正に割り当てられていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2526） +     サービスへの接続に関わらず、サーバーがシャットダウンすることがありました。 + A. Peshkov、D. Kovalenkoが修正しました。 +     ~ ~ ~      + + （CORE-2505） +     組み込み三角関数が、NaNや無限大を生成することがありました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2501） +     バイナリのshift関数が負のshift値を取るという、誤った結果を出していました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2499） +     DISTINCTアイテムの実装制限が行われておらず、不正なBLRが生成されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2482） +     データベースがアタッチメントまたはデタッチメントを受け付けた時にモニタリングテーブルによるデータ収集が不安定になっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2475） +     外部テーブルのデータが、そのテーブルにアクセスする最初のもの以外のクラシックサーバーのセッションから見えなくなっていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + +（CORE-2449） +     予期された例外の代わりに予期しないlock conflictエラーがスローされることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2444） +     複数のアタッチメントが同時に関心をイベントに登録し、イベントテーブルの空きスペースが使い果たされた場合、エンジンがハングアップすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2426） +     ALTER TABLEがコレーションを尊重していませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2416） +     派生テーブルに関する集約を持つクエリの準備がアクセス違反を起こしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2411） +     オプティマイザが特定のタイプのクエリで、バージョン2.0.4と2.1.1でよりも遅い方のPLANを選んでいました（このバグはバージョン2.0.5と2.1.2にも同様に影響していました）。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2397） +     同じトランザクション内で一つのテーブルの一つ以上のインデックスの削除すると、破損が起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2359） +     番号を割り当てる際に、マルチバイト文字列の論理的な最大長が尊重されていませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2331） +     ALTER DOMAINの結果として、無効なRDB$FIELD_SUB_TYPEの値が格納されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2272） +     イベント接続の試行をkillした際に、サーバーがガベージを返し始めていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1971） +     WHERE句や他の演算子に、修正済みでドキュメント化もされている通りの評価順序（常に左から右）を設定すること。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1346） +     LPAD()とRPAD()関数が一つのSQL文で一つ以上のカラムに適用された場合、実装制限に掛かることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2356） +     Windowsで、任意の作業プロセスが存在している場合、クラシックサーバーのリスナープロセスが再起動後に必要なリソースを作成できませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2355） +     結果の文字列のバイト長が縮小した場合、LOWER/UPPERの不正な処理が行なわれていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2351） +     データベースの<ファイル指定>がエイリアスだった場合、そのエイリアスが存在したとしても、そのデータベースを作成できませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2349） +     Invalid SQLDAのエラーが誤ってスローされていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2348） +     トランザクション番号が32bitの符号付整数を超過することから、さらなるデータベース破損の問題が起こりました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2340） +     同時に高い負荷が掛かる状況下で、バグチェック258（page slot not empty）が起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2320） +     複雑な再帰クエリが常に全ての行を返すわけではありませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2313） +     境界条件により、INF_*関数が最初にisc_info_truncatedを持つ出力バッファの全体を無効化することがありました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2311） +     WITH RECURSIVEクエリがメモリリークを起こすことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2300） +     SUBSTRING()の二番目の評価が、予期せぬ算術例外、数値オーバーフロー、または文字列切り捨てのエラーをスローしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2289） +     外部キー作成中に外部キー違反が起こった時、参照された主キーについて、誤った名前が報告されていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2242 + ）    エンジンが整数コンテナを、マシンのローカルなフォーマットの整数で、BLOBパラメータバッファ（BPB）に不正に配置していました。このため、ビッグエンディアンのプラットフォームでエラーが起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2241 + ）    テーブルに対するALTER TABLE ALTER COLUMN.. の操作が大量の挿入操作の過程で行われた場合、インデックスのわずかな破損が起こり、それ以降のクエリが誤ったレコード数を返す原因となっていました。このバグは、BTR\compress_root()のレガシーコードに由来するものでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2230） +     EXECUTE BLOCKの入力パラメータがドメインチェックを受けていませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2186） +     Windowsのエンベデッドサーバーで、CREATE DATABASEの処理中に、isc_dsql_execute_immediate()の後でfbintl.dllがアンロードされていませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2182 + ）    新しい組み込み関数と名前が重複してしまった既存のUDFを削除できませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2154） +     最後のレコードがEXECUTE PROCEDUREで取得された後で、isc_dsql_sql_info()をisc_info_sql_recordsパラメータ付きで呼び出すと、request synchronization errorが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2132） +     比較演算子でストアドプロシージャの呼び出しが使われている場合、インデックス付き検索を選択できませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2117） +     インデックス付き検索とサブクエリで不正なROW_COUNTの値が返されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2115） +     クエリが長い場合、クエリのplanが失われることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2101） +     オープンなPSQLカーソルのend-of-streamマークを越えて取得を行おうとした場合に、バグチェック249（pointer page vanished）のエラーがスローされていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2098） +     グローバル一時表からselectしたビューを作成できませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2078） +     インデックスなしの選択演算子が結合に含まれていない場合、その結合のplanに可能なだけの最適化がなされませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2075） +     外部結合を使った場合、ビューのRDB$DB_KEYの各部が逆にされることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2073） +     式インデックスのバグ：逆にされたブール式の結果が不正なものとなっていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2069） +     RDB$DB_KEYがビュー本体の中で使われた際に、不正なビューの伸張が行なわれていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2068） +     <サブクエリ式>の引数がRDB$DB_KEYを含む場合、IN <サブクエリ式>オペランドで、比較が誤った結果を返していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2067） +     GROUP BYとRDB$DB_KEYの問題。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2066） +     SQL_TEXT／SQL_VARCHARからSQL_TIMESTAMP／SQL_TIME／SQL_DATEへの変換。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2053） +     計算式がINSERT文のRETURNING句の中で使われた場合、最適化が不十分となることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2045） +     バージョン2.1での不具合が元に戻っていました。これにより、blr_fieldで存在しないシステムフィールドへの参照がNULLとして解決されていませんでした。一方で、並行して施されていたblr_fldに関わる変更は、適切で正しい挙動を示していました。 + dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2044） +     UPDATE OR INSERT ... RETURNING OLDとnullableでないカラムの結果が不正なものとなっていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2041） +     UPDATE OR INSERTでGEN_ID()を使うと、ジェネレータが3ずつステップしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2039） +     ドメインレベルでのCHECK制約が誤ってNULL値を処理していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2031） +     RDB$DB_KEYにある条件を加えると、最初のレコードにNULLが現れていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2027） +     システムフィールドを含むORDER BY式のバッファサイズが誤って計算されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2026） +     読み取り専用としてマーキングされたデータベースで問題がありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2008） +     システムスキーマで、プロシージャのパラメータにNOT NULLのフラグがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2002） +     UDFの結果にFREE_ITがマーキングされていた場合、その結果からの変換エラーでメモリリークが起きていました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2001） +     時々、変換エラーが表示されずに、算術例外または文字列切り捨てのメッセージが現れていました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2000） +     ロックマネージャが高負荷下で誤ってデッドロックをレポートすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1986） +     ドメイン名を変更するとドメインへの依存関係が削除されてしまいました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1984） +     パーティシパントの一つがタイムアウトを許可されて待機している場合に、ロックマネージャが誤ってデッドロックをレポートすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1980） +     スイーパによるCPU使用率がいつまでも100％となっていることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1970） +     Lock conversion denied (215) のエラーが起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1962） +     関数EXTRACT (MILLISECONDS FROM aTimeStampOrTime)が不正な結果を返していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1958） +     トランザクションが同じレコードを複数回更新しようとした場合、バグチェック179（decompression overran buffer）による整合性チェックがスローされていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1957） +     長いアクセス制御リスト（ACL）が切り捨てられ、権限が消される原因となっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1943） +     RAND()式で集約を行うSQL文が無限に行を返していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1938） +     別の接続で削除または再作成されているテーブルを参照するSQL文のプリペア中または実行中に、バグチェック243（missing pointer page）スローされていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1936） +     組み込み関数LOG(base, number)がパラメータをチェックしておらず、例外処理を行わずにNANの値をout-of-rangeの入力に通知していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1914） +     テーブル作成中に問題が起こった場合、データベースが矛盾した状態に置かれることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1812） +     ダイアレクト1によるいくつかのdate/time式で、使われるはずのインデックスが使われていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1650） +     GROUP BY操作を使ったSELECT GEN_ID(..) FROM RDB$DATABASEで行が無限に生成されるという、ありそうもないことが起こっていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1607） +     UNIONのストリームに依存する相関サブクエリが充分に最適化されていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1606） +     親レコードがロックされていても、外部キーのターゲットが変更されていない場合、子レコードを挿入することができていました。 + A. Potapchenko、V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1575） +     単一のトランザクションで、テーブルに複数回の更新が行なわれると、深刻なメモリバグが起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1544） +     ユーザーアプリケーションが、実行時の何らかの用途で、実行時に一時ストアドプロシージャを作成すると、RDB$PROCEDURES.RDB$PROCEDURE_IDカラムの内部ジェネレータが、その内部ジェネレータの32Kの制限（符号付SMALL INT）をすぐに超えてしまい、新たなストアドプロシージャ作成の試みに対して数値オーバーフローの例外を起こしていました。 + この修正により、32Kの境界で生成された値は包み込まれ、ID番号の既存のギャップを再利用することが許可されます。同様の修正はRDB$GENERATORSとRDB$EXCEPTIONSにも適用されています。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1343） +     単純な場合とサブクエリでのバグ。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1246） +     派生テーブルとの外部結合が不正な結果を返していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1245） +     ビューとの外部結合が不正な結果を返していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-903） +     UPDATE文のSET句で、同じカラムを参照する複数の割り当てに関するFirebirdの挙動が標準に準拠していませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-501） +     COALESCEが最適化の問題を起こしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-216） +     データベースでの権限付与が多すぎる場合、それらの権限が失われることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1421） +     スーパーサーバーで、ログインの試みが失敗した後でシャットダウンがリクエストされた場合、すぐにシャットダウンできませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1907） +     同じトランザクションでドメイン制約の削除・追加を行うと、不正な依存関係が残っていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1905） +     aliases.confで、ファイル名に含まれるハッシュ記号（#）が不正に処理されていました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-1887） +     新たに作成されたデータベースが誤ったアクセス権を持っていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1869） +     ロールの付与／削除のロジックがバージョン2.0とバージョン2.1で違っていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1841） +     いくつかのビューが派生テーブルと長いテーブル名／エイリアスを使っていた場合、RDB$VIEW_RELATIONS.RDB$CONTEXT_NAMEをオーバーフローすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1840） +     個々のDDLの実行で小さなメモリリークが起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1838） +     GTTのインデックスに対するSET STATISTICS INDEXが、インデックスidをデータベースのページサイズで利用できる最大の番号で誤って変更することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1830） +     セーブポイントを使った同じトランザクションで同じレコードを複数回更新すると、インデックスが破損することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1817） +     RelaxedAliasCheckingパラメータがRDB$DB_KEYに関して効果を持っていませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1811） +     キーワードVALUEをクォートで囲まずに使用しても、パーサが反応していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1798） +     RDB$DB_KEYがINSERT ... RETURNINGの中でNULLとして評価されていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1797） +     トリガで、OLD/NEW.RDB$DB_KEYが不正な結果を返していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1784） +     EXECUTE STATEMENT内のEXECUTE PROCEDUREでエラーが起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1777） +     TPBで、テーブル予約に競合する指定が許可されていました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-1775） +     プリペア中のセキュリティチェックが十分に行われていませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1770） +     DDLでバグチェック291が起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1735） +     参照整合性のトリガでSET DEFAULTアクションの引数の挙動に問題がありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1731） +     時々、エンジンが何もI/O活動を行わないままCPU使用率100％で数分間ハングアップしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1730） +     TempDirectoriesの設定で指定されたディレクトリの一つが利用できない場合、問題が起こっていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1724） +     計算項目または限定子（IN／ANY／ALL）で、共通テーブル式が使えないことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1694） +     CREATE／ALTERデータベーストリガにバグがありました（ここのコメントはロシア語です）。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1693） +     CONNECT／TRANSACTION STARTトリガ内のEXECUTE STATEMENTでエラーが起きていました。 + A. dos Santos Fernandes、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1689） +     There are <n> dependenciesのエラーメッセージが依存するオブジェクトの数を誤って示していました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-1357） +     DummyPacketIntervalの仕組みが壊れていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1307） +     fb_inet_serverのスイッチ-sが正しく処理されていませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-479） +     RDB$SECURITY_CLASSESで、権限付与により、もとのエントリが上書きされていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ サーバー／クライアントのクラッシュ + （CORE-3011） +     アタッチとデタッチが繰り返し行なわれている接続の監視中にサーバーがハングアップまたはクラッシュすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2908） +     ODS 8.xのデータベースでの稼働中に、エンジンがクラッシュまたは予期しないエラーを起こすことがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2888） +     メモリ破損が原因となり、クエリが不正に評価されたり、サーバーがクラッシュすることもありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2576） +     誤った、または切り捨てられたBLRのパース時にサーバーがクラッシュすることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2455） +     統計関数でのエラー発生直後にDROP DATABASEを実行すると、サーバーが故障していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2441） +     UPDATE OR INSERT文の実行時にサーバーがクラッシュすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2306） +     いくつかのワーカースレッドが開始に失敗すると、スーパーサーバーが異常終了することがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2368） +     イベントが見つからない場合、isc_cancel_events()への呼び出しの後でアクセス違反が起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2222 + ）    BLOB変換フィルタを使ってテキストBLOBを保存すると、エンジンでアクセス違反が起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2137 + ）    設定パラメータDummyPacketIntervalが明示的に設定されていると、データベースのリストアで、サーバーがクラッシュすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2121） +     クライアントのライブラリが、BLOBに関わる操作を行なっている間にクラッシュすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1983） +     OSでのout-of-memory状態によりアクセス違反が起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1965） +     DDLに同時に負荷がかかる状況下で、無効なロックIDにより、ロックマネージャがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1894） +     計算フィールド間で循環した依存関係により、サーバーがクラッシュしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1963） +     複数の接続から同時に権限の付与／削除を行うと、サーバーがクラッシュすることがありました + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1506） +     isc_dsql_execute_immediate()とゼロ長の文字列によりサーバーがクラッシュしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-210） +     同じストアドプロシージャが二つの別々のプロセスで変更されている場合、クラシックサーバーがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1930） +     プロシージャが出力を持たないよう変更され、依存するプロシージャが再コンパイルされなかった場合、サーバーがクラッシュすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1919） +     EXECUTE STATEMENTでのメモリ破損によりサーバーがクラッシュすることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1884） +     入力パラメータのデフォルト値として式を持つストアドプロシージャを使用すると、ランダムにクラッシュが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1839） +     再帰CTEを使って計算されたフィールドによってソートを行うと、サーバーがクラッシュすることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1793） +     パラメータ化された未使用のCTEを持つクエリの準備中にサーバーがクラッシュすることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1512） +     DEFAULT句に誤ったパース行っていたため、サーバーがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ データベースの監視／管理 + （CORE-2209 + ）    高負荷状況下では、監視のリクエストが非常に遅くなったり、その間の他の活動をブロックすることもありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2171 + ）    テーブルMON$CALL_STACKのカラムMON$CALLER_IDが無効なIDを報告していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2017） +     ストアドプロシージャのI/O統計がモニタリングテーブルに記録されていませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1944） +     ビッグエンディアンのプラットフォームで、モニタリングテーブルが誤ったデータを含んでいました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1890） +     高負荷下で、データベース監視プロセスがハングアップすることがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1881） +     データベースの監視により、サーバーがクラッシュしたり、ページロックのロジックに悪影響を及ぼすことがありました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1728） +     Linuxの新規インストール後にデータベース監視が動作しませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+ +
+ データ操作言語 + + （CORE-1910） +     MERGE文のINSERT句で、無効なフィールドが受け付けられていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1859） +     MAX()関数で、算術オーバーフローまたはゼロ除算が起こることがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1828） +     ダイアレクト1で、ABS()関数にエラーが起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      +
+ +
+ コマンドライン・ユーティリティ + +
+ isql + + （CORE-2831） +     スクリプトが抽出される場合、出力にデータベース名とユーザー名が含まれるべきではありません。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2741） +     CHECKキーワードが全ての大文字・小文字以外の任意のキャラクタが混在したものだった場合、メタデータの抽出で、CHECK制約のDDLが誤って解釈されていました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-915） +     PSQL本体がWindowsのサードパーティ製テキストエディタで書かれていた場合、isqlのメタデータ抽出ツールがPSQL本体のコードで改行を二重にしていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2408） +     isqlによるメタデータ抽出プロセスで、NOT NULLとCOLLATEフラグの前に、プロシージャのパラメータのデフォルト値を置いていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2407） +     isqlによるメタデータ抽出プロセスで、CREATE DATABASE文からPAGE_SIZE句が抜けていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2370） +     2048以上のキャラクタを含むSQLのplanが、isqlで全く表示されませんでした。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2270） +     isqlをzloginコンソールで実行すると、全メモリを消費してクラッシュしていました。 + J. Swierczynski、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1891） +     SHOW VIEWが、式を持つビューのフィールドについて無意味な情報を示していました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1875） +     CURRENT_DATEを含むスクリプトでエラーが起きていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1862） +     Firebird 2.1で、抽出されたスクリプトが相互に依存する選択型プロシージャで使用できませんでした。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-1782） +     30以上のキャラクタからなるエイリアスを持つカラムのデータ取得時に、isqlがクラッシュしていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1749） +     AUTODDL ONを含むDDL文が統計を表示していませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1507） +     ISQLによるスクリプトでの行数カウント機能が、INPUTコマンドの後で同期しなくなっていました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-1363） +     double型から変換された文字列が23バイトを超えた場合、ISQLがクラッシュしていました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + +
+ +
+ gsec + （CORE-2928） +     gsecでバッファオーバーフローが起きていました。 + A. Peshkovが修正しました。 + 理由は不明ですが、gsecのコードが、表示操作中に、パスワードハッシュの値を内部ユーザーデータ構造体へとコピーしていました。バージョン2.0以降、新しいハッシュアルゴリズムによって以前よりハッシュが長くなっていますが、その保存操作に使えるバッファが短すぎた可能性があります。 + ハッシュの値はどこにも移動しないため、これが脆弱性となることはありません。ともかく、無害ではあります：ファーストネーム、ミドルネーム、ラストネームはパスワードの直後に記入されるので、このバッファオーバーフローが悪用されることはあり得ません。 + 現在、これは修正されているので、このオーバーフローを検出するためにglibcの新しいバージョンを採用する必要はありません。 +     ~ ~ ~      + + （CORE-2528） +     gsecユーティリティがOSにエラーコードを返していませんでした。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-1680） +     セキュリティ・データベースのユーザー数が50以上だった場合、gsecのDISPLAYで、最初の少数のユーザーしか表示されませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+ +
+ gbak + + （CORE-2914） +     存在しないUDFを参照している式インデックスを持つデータベースのリストアを行うと、サーバーにクラッシュが起きていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2793） +     同じデータの複数回のバックアップ／リストアのサイクルでテストした結果、一つのバックアップから別のバックアップへ、バックアップファイルのバイナリ表現に一貫性がないことが明らかになりました。このことは、gbakのバージョン1.5.4以降全てのバージョンに当てはまることが報告されました。これは、バージョン2.1.4で、またバージョン3.0のアルファ版で、現在までに修正されています。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2634） +     大量のメタデータを持つデータベースのリストア時に、パフォーマンスが低下する不具合が起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2291） +     エンジンがエラーを検出して適切な例外をスローすべき場合に、[FOR] SELECTを含む間違ったトリガのコードに対してエラーバグチェック284（cannot restore singleton select data）がスローされていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2285） +     多数の権限付与を行っているデータベースがバックアップ／リストア後に破損することがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2245） +     長い例外メッセージが定義されたデータベースで、バックアップからのリストア時にエラーが起きていました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2223 + ）    gbakが、SQLの権限を保存しているアクセス制御リスト（ACL）での作業中にいくつかのバグに遭遇していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2214） +     セキュリティクラスのリストアが不正に行われていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1911） +     サービスAPI使用時に、バックアップとリストアがスレッドセーフとなっていませんでした。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-1843） +     サービスマネージャを使用した場合、gbakがスペースを含むパスを許可しませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1703） +     gbakの出力が別のプロセスにリダイレクトされた場合、遅延／ロックアップが起こっていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ nBackup + + （CORE-2750） +     明示的な差分ファイルが削除された後で、物理バックアップが操作を再開できませんでした。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2648） +     nBackupの増分ファイルがデータベースのForced Writes設定を尊重していませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2266 + ）    nBackupによるデータベースのロックが正しく動作しておらず、データベースへの書き込みが中断状態にあるべき時でもデータベースファイルの伸張が続いていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1696） +     nBackupユーティリティ使用時に、ロックマネージャでデッドロックが発生していました。 + R. Simakovが修正しました。 +     ~ ~ ~      + + （CORE-1876） +     バージョン2.1で、nBackupを用いた増分バックアップに失敗していました。 + N. Samofatovが修正しました。 +     ~ ~ ~      + +
+ +
+ gfix + （CORE-2846） +     接続がまだアクティブであるために、gfix -shut <モード> -attach <タイムアウト>が指定されたタイムアウトの後で失敗した場合、データベースへの接続ができませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-97） +     gfix -shut -forceによってデータベースファイルがロックされたままとなり、その後にリストアできなくなっていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2268） +     有効でないトランザクション番号が原因となって、gfixがBUGCHECKのエラーをスローしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2271 + ）    gfixユーティリティにはレガシーなバグがあり、大きなデータベースでのデータベース検証／修正ルーチン中に現れていました。こうしたルーチンを実行するユーザーの権限レベルに関するチェックが操作の遅い段階で行なわれていたため、権限を持たない（つまり、SYSDBAや所有者ではない）ユーザーが検証操作を開始できてしまいました。いったん権限チェックが始まると、データベースの検証は作業中でも停止されるため、未完状態となり、避けられたはずのロジカルな破損が起こっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1961） +     データベースの権焼酎に整合性チェックのエラーバグチェック210（page in use during flush）がスローされていました。 + D. Yemanov、R. Simakovが修正しました。 +     ~ ~ ~      + +
+ +
+ gstat + （CORE-2519） +     20億以上のレコードを持つテーブルで、gstatからの出力が不正なものとなっていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1412） +     長く放置されてきた、gstatのパラメータ処理に関するいくつかのバグを修正する必要がありました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + +
+ +
+ fb_lock_print + （CORE-2598） +     fb_lock_print -c[onsistency]スイッチがWindowsで動作していませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2354） +     fb_lock_print -iaの出力が、繰り返し中にファイルに書き込まれていませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ GDMLのqliクエリユーティリティ + （CORE-2247） +     QLIユーティリティで、メッセージと記述子のバッファが適切に配列されていませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+
+ +
+ サービスマネージャ + （CORE-1982） +     サービスAPIを通じて呼び出された同時のバックアップまたはリストアが互いに干渉しあうことがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +
+ + +
+ リモートインターフェース／API + + （CORE-2563） +     不正な形式のパケットをいくつかの特殊なフォーマットで送信することで、スーパーサーバーのメインポート（デフォルトで3050）をシャットダウンすることが可能でした。これにより、新規の接続に対するサービス妨害（DoS）状態に陥っていました。これは認証されていないクライアントによって悪用される可能性がありました。 + 2009年7月15日、Core Security Technologies社によって報告されました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2437） +     クライアントがイベントを受け取った時にバッファオーバーフローが起こることがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2307） +     API情報のリクエストの結果として不完全な値が返されていました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-2234 + ）    Windowsのクラシックサーバーで、Firebirdサーバー側でのチェックが不適切だったため、時々、終了した作業プロセスが終了後もまだ生きていると見なされていました。同じバグにより、Firebirdサーバーで高負荷時に誤作動や長いデッドロックが起こることがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2151） +     テンポラリディレクトリのパスにスペースが含まれていた場合、右端のスペースで（誤って）切り捨てられていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2033） +     クライアントライブラリ内のシンボル_Unwind_GetIPが、静的ライブラリのリンクが失われていたため、未解決のままになっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2018） +     読み取り専用データベースに単一のクライアントしかアクセスできませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1972） +     非SYSDBAユーザーが、SYSDBAに限定すべき他のいくつかのデータベースの特性とともに、任意のデータベースのForced Writesモードを変更できていました。この、長く放置されてきた、DPBパラメータの処理でのレガシーなループホールにより、データベースの破損が起きたり、通常のユーザーがSYSDBA専用の操作にアクセスできるようになっていました。 + この変更により、いくつかの既存のアプリケーションやデータベースツール、コネクティヴィティ・レイヤー（ドライバ、コンポーネント）が影響を受けます。 + いくつかの修正はバージョン2.1.2とバージョン2.0.5にバックポートされました。. + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1868） +     クライアントライブラリがisc_dsql_free_statement()内でクラッシュしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1763） +     クライアントライブラリが、接続時、ソケットにオプションSO_KEEPALIVEもTCP_NODELAYも設定していませんでした。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1755 and + )CORE-1756 +     isc_start_transaction()で、二種類のクラッシュが起こることがありました。 + D. Kovalenko、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1726） +     isc_service_start()で失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1079） +     fbclient/fbembedライブラリによるホストプロセスへの各アタッチで、64KBのメモリリークが起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ セキュリティ + （CORE-2657） +     きちんとドキュメント化されていないSPBタグにより、任意の信頼されたユーザー名をサービスに渡し、そのユーザーがSYSDBAのものを含む任意のパーミッションを手にすることができるという、望ましくない機能が提供されていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2087） +     設定パラメータRemoteBindAddressがIPアドレスではなく、ホスト名や、存在しないIPアドレスを指定した場合、それは警告なく無視され、サーバーはfirebird.logまたはシステムログには何も通知せずに全てのインターフェースにバインドします。システムがインターネットにポートを開いている場合、これは潜在的なセキュリティ上のリスクと見なされます。現在は、無効な、または利用できないIPアドレスはlocalhost（127.0.0.1）として解決されることになります。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2055） +     Firebirdのクライアントライブラリでバッファオーバーフローが起きていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1845） +     標準の呼び出しの一部が、通常のユーザーに対してサーバーのインストールディレクトリを示していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1810） +     キャラクタ'.'を含むユーザー名に関して、いくつかのイシューが出されました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ 国際言語のサポート +     ~ ~ ~      + （CORE-2642） +     Windowsでの不明瞭なICU初期化の問題により、マルチスレッド環境で誤作動が起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2607） +     introducer構文（_charset）が監視クエリやPSQLモジュールと関連して使われた場合、問題が起きていました。 + この問題と回避方法については、国際言語のサポートの章、その他の改善点中のIntroducer構文の使用法の項を参照して下さい。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +     ~ ~ ~      + （CORE-2361） +     isc_dsql_fetch()をUTF8接続で使用して、キャラクタ・セット8859_1のスペイン語のカラムを読み込む時に、文字列切り捨てのエラーが起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2227 + ）    いくつかの環境で、アクセント付きキャラクタを含むカラム名を参照するトリガの作成時に問題が起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-2123） +     CP943Cの接続charsetでUNICODE_FSSのデータを取得する際に問題がおきていました。 + A. dos Santos Fernandes、D. Kovalenkoが修正しました。 +     ~ ~ ~      + + （CORE-2122） +     UNICODE_FSS／UTF8と他のcharsetの間での大きなテキストBLOBの翻訳。 + A. dos Santos Fernandes、D. Kovalenkoが修正しました。 +     ~ ~ ~      + + （CORE-2095） +     CVJIS_eucj_to_unicode()のバグ。 + A. dos Santos Fernandes、D. Kovalenkoが修正しました。 +     ~ ~ ~      + + （CORE-2019） +     UTF-8の変換エラー（文字列切り捨て）が予期せずにスローされていました。 + dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1989） +     UTF8用のUNICODE_CIコレーションを使ったカラムが外部キー制約で使用できませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1927） +     プロシージャsp_register_character_setがRDB$CHARACTER_SETS.RDB$CHARACTER_SET_IDに負の値を生成することがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1690） +     テーブルがUTF8のテキストを含んでいる場合に、算術例外、数値オーバーフロー、または文字列切り捨てのエラーが起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1596） +     CsConvert::convertのバグ。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1432）    レコードのフォーマット間でカラムのコレーション属性が伝達されていませんでした。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-316） +     名前にマルチバイトのキャラクタを含むデータベースを開けないことがありました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1802） +     PXW_CSYのコレーションを使う最大のキーサイズに関して、いくつかのイシューがレポートされていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1774） +     ES_ES_CI_AIのコレートで問題が起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + + （CORE-1254） +     DISTINCTと、大文字小文字・アクセントを無視したコレーションで問題が起きていました。 + A. dos Santos Fernandesが修正しました。 +     ~ ~ ~      + +
+ +
+ POSIX固有の問題 + + （CORE-3067） +     HP-UXを除く64bitのPOSIXで、共有メモリが閉じられた時にオブジェクトがアンマッピングされていませんでした。 + 64bitのポインタが32bitのマスクでマスキングされていました。これは全くひどいやり方だとわかりました：Object == 0x7FAB12345678、page size == 4K、bit数の上限は無くなり、開始アドレスは意図した0x7FAB12345000ではなく0x12345000となっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3019） +     Gentoo Linuxの最近のバージョンで、関数ライブラリ/etc/init.d/functions.shを利用しようとすると、メッセージ* ERROR: firebird does not have a start functionを出して失敗し、スーパーサーバーもスーパークラシックサーバーも開始しませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-3001） +     インストール時に、firebirdユーザーとグループの作成に失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2919） +     Linuxのインストール・スクリプトが標準以外のポートを無視していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2845） +     Solarisでのビルドのプロセスが、メッセージSFIOを使う必要がありますを出して停止していました。そもそも、Solaris 10はもはやSFIOを必要としていません。64bitビルドでは、ファイル記述子の上限255での問題は起こりませんし、32bitのビルドでは簡単な回避方法があります。詳細はこちらの記事を参照して下さい。 + しかし、Solaris 10 3/05からSolaris 10 11/06まではこのイシューの影響を受けます。問題の修正にはいくつかのパッチが必要となります。 + 当面の最も簡単な解決法は、コードにdefineを残しておくことです。ただし、Solaris 10に関連する情報でコメントを付けておいて下さい。パッチを適用するか、ユーザーがSolaris 10でこの問題の影響を受けないバージョンを使っていれば、defineは削除できます。 + このイシューに関する更新情報はcommon.hに挿入されています。Solarisで32bitのFirebirdをビルドする方は、SFIO defineのコメントを解除する前に、Soloarisのバージョンやビルド／パッチレベルに応じて十分な情報に基づいた決定を行う必要があります。 + P. Beach、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2814） +     SPARCでは、ルーチンmap_sort_dataがバスエラーを起こしてサーバーがクラッシュしていました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2601） +     POSIXプラットフォーム上でインストール・ディレクトリの微調整に使われる標準的なconfigureスイッチの多くは、Firebirdには役立ちません。 + 標準的なGNUのスイッチをデフォルト設定を変更せずに機能させるのは不可能に近く、簡単明瞭とはほど遠い煩雑なものでした。これらに代わり、configure用の新たなスイッチのセットが追加され、Firebirdのファイル群のきめ細かな配置設定が可能になりました。 + これらのスイッチのリストはインストールの章、Firebirdの'configure'専用スイッチの項で挙げられています。 + A. Peshkoffが修正しました。 +     ~ ~ ~      + + （CORE-2572） +     タイプLCK_page_spaceのロックがビッグエンディアンのマシンで不正に処理されていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2221 + ）    POSIXプラットフォームで、security2.fdbへのアクセス権が0660から0666に修正されると、どのデータベースへのどのアタッチメントも失敗するようになっていました。 + P. Beach、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-2093） +     64bit版Solarisで、スーパーサーバーのスタートアップに失敗していました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1909） +     linux/amd64でfirebird.logにガベージがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1885） +     POSIX下で、CREATE COLLATIONによって接続が失われていました。 + A. dos Santos Fernandes、A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1854） +     Unix OSの認証方法を利用する時、CURRENT_USERの値が大文字にならないことがありました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1826） +     changeRunUser.shとrestoreRootRunUser.shスクリプトがinit.dスクリプトで実行ユーザーを変更していませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1818） +     POSIXプラットフォームで、テンポラリ・ページスペースで使われるテンポラリ・ファイルが使用後に削除されませんでした。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1807） +     サーバーが異常終了後に標準的でないポートに割り当てられていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1766） +     Linux版クラシックサーバーの所有者とisc_monitor1ファイルのグループが不正なものとなっていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      + + （CORE-1671） +     ライブラリがdlopen'edモジュールで使われた場合、クライアントライブラリのatexit()呼び出しがセグメンテーション違反を起こしていました。 + A. Peshkovが修正しました。 +     ~ ~ ~      +
+ +
+ Windows固有の問題 + + （CORE-2769） +     高負荷のWindowsシステム上で、サーバによるxnet_response_eventの設定を待機している間に、ローカル接続（XNET）がクライアントのタイムアウトによって失敗することがありました。この問題の解決のため、firebird.conf中のConnectionTimeoutパラメータがXNET接続用にアクティベートされています。 + D. Yemanovが改善しました。 +     ~ ~ ~      + + （CORE-2108） +     Windowsローカルプロトコル（XNET）の使用時に、次に利用可能なマップ番号が不正に計算され、その結果、サーバーが既存のマップ番号を再利用しようとすることができていました。新しいマップのタイムスタンプが既存のマップのタイムスタンプと等しい場合、get_free_slot()関数が失敗していました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-2107） +     高負荷下で、Windows版クラシックサーバーへのTCP\IP接続の確立に失敗することがありました。 + V. Khorsunが修正しました。 +     ~ ~ ~      + + （CORE-1923） +     instsvc.exeの削除が正常に行われた時に、完了コードとして0ではなく1を返していました。 + D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1820） +     セットアッププログラムが稼働中のサーバーの検出に失敗していました。 + P. Reeves、D. Yemanovが修正しました。 +     ~ ~ ~      + + （CORE-1105、 + CORE-1390、 + CORE-1566 および + CORE-1639） +     XNET接続でエイリアスが適切に機能していませんでした。 + D. Yemanovが修正しました。 +     ~ ~ ~      + +
+ +
+ MacOSX固有の問題 + （CORE-2065） +     MacOSXのインストールパッケージが、動的ローダの検索パスにクライアントライブラリを含んでおらず、プラットフォームのルールに違反していました。 + P. Beach、A. Peshkovが修正しました。 +     ~ ~ ~      + +
+ +
+ Miscellaneous Bugs + （CORE-2282） +     -1より小さい負の数で、UDFの切り捨てが失敗していました。 + C. Valderramaが修正しました。 +     ~ ~ ~      + + （CORE-2281） +     負の数でUDFを丸めるのに失敗していました。 + C. Valderramaが修正しました。 +     ~ ~ ~      +
+ +
+ + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/Compatibility25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/Compatibility25.docbook new file mode 100644 index 00000000..9ec15d12 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/Compatibility25.docbook @@ -0,0 +1,154 @@ + + + 互換性問題 + + Dmitry + Yemanov + + + バージョン2.0またはバージョン2.1.xデータベースからFirebird 2.5に移行する際、既存のデータベースまたはアプリケーションに影響する可能性がある多くの非互換性に注意する必要があります。あなたがこれらの問題を解決するまで、移行の開始はお勧めできません。 + + + 古いクライアントとの非互換性 + 64bitサーバーで統計ルーチンが適切に動作する新しいストラクチャーで、32bitツールが正しく動作できるようにするため、いくつかの新しい内部API関数（struct perf64とperf64_xxx）を導入し、またこれらを使用するようにisqlとqliを変更する必要がありました。このことは、バージョン2.5のisqlとqliプログラムが古いFirebirdクライアントと互換性がないことを意味しています。 + 詳細は、エンジンの章のデータベースの統計が64bit値で適切に動作するようにの項を参照して下さい。 + + +
+ Unicodeメタデータへの影響 + あなたがこれまでにデータベースのメタデータ中のテキストオブジェクトをUTF-8キャラクタ・セットへと更新していない場合、バージョン2.5以前のデータベースのリストアは不正な形式の文字列のエラーを起こして失敗します。この問題の解決には、あなたがインストールした/misc/upgrade/metadataディレクトリ内のファイル群に注意し、また、gbakコマンドラインで新しい-fix_fss_dataと-fix_fss_metadataスイッチを使う必要があります。 +
+ +
+ 設定パラメータの削除 + 非推奨の設定パラメータOldParameterOrderingとCreateInternalWindowは今後サポートされず、firebird.confからも削除されました。 + 以前のバージョンではLockSemCountとLockSignalという二つのパラメータを使ってロックマネージャの調整ができましたが、新しいロックマネージャの実装では必要なくなり、削除されました。 + パラメータMaxFileSystemCacheはFileSystemCacheThresholdにリネームされました。 +
+ +
+ SQL言語の変更 + SQL言語の実装にいくつか変更が加えられましたので、注意する必要があります。 + +
+ 予約語 + いくつかの新しい予約語が導入される一方で、予約語リスト全体は劇的に縮小され、Firebirdのパーサ文法は、従来は予約語だった大部分の非標準キーワードを非予約語と見なすようになりました。従来からの予約語と新たに予約語となったSQL標準キーワードのリストについては予約語とその変更の章で確認できます。 +
+ +
+ 実行結果 + いくつかの変更により、gbakユーティリティのコード（バックアップとリストア）実行時に実行されるものを含むクエリのランタイム実行時に例外を発生させるようになりました。 + +
+ 不正な形式の文字列 + UNICODE_FSS文字列とテキストBLOBに対して適格性のチェックが実行されるようになりました。これにより、新規のまたは既存のUNICODE_FSSが不正な形式だった場合、実行時に例外が発生します。 +
+ +
+ SET句でのロジックの変更 + 従来は、UPDATE文のSET句が新しい値をカラムに割り当てる際、ただちに新しい値が元の値に置き換わっていました。同じカラムが割り当てられたり、一度以上の割り当てがあった場合、現在の値は最後に行われた割り当ての値となっていました。言い換えると、従来は割り当ての順序が重要となっていました。 + Firebirdを標準に合わせるため、このバージョン以降、SET句では、カラムのもとの値だけが任意の割り当てに対してアクセス可能となっています。 + しばらくは、firebird.conf内の一時的なパラメータOldSetClauseSemanticsの設定によって従来の挙動に戻すことができます。このパラメータは将来のリリースで非推奨となり、廃止されます。 +
+
+
+ +
+ ユーティリティ + Firebirdコマンドラインユーティリティに加えられた以下の変更の影響に注意して下さい。 + +
+ fb_lock_print + バージョン2.5ではサーバー上の各データベースのセパレートロックストラクチャーが維持されているので、fb_lock_printがロックテーブルを表示するためにデータベースのパス名を要求するようになっています。コマンドラインで新しいスイッチ-d <path name>を付けて、分析したいデータベースのファイルシステム・パスを指定して下さい。 +
+ + 将来廃止予定の非推奨機能 + Firebird 3コードベースから組み込み関数isc_ddlが削除されることを見越して、現在gdefとgpreツールで利用できるいくつかの機能が非推奨となりました—そのため、バージョン2.5では動作するかもしれませんが、Firebird 3では失敗するでしょう。 + + + gdefはもうサポートされていません。通常のDDLコマンドとしては、代わりにisqlを使用して下さい。 + + + gpreのプリプロセッシングとして、全てのDDLオペレーションを次のものと置き換えて下さい。 + + EXEC SQL + EXECUTE IMMEDIATE "..." + + + + 全てのカスタムアプリケーションで、isc_ddlの呼び出しは、SQLのDDL文の要求に置き換えなければなりません。 + + + + +
+ +
+ APIの変更 + クライアントライブラリに実装されるアプリケーションプログラミングインターフェース（API）に以下の変更が加えられましたので、注意して下さい。 + +
+ 矛盾するTPBオプションのリジェクト + API関数isc_start_transaction()とisc_start_multiple()が一緒にあるべきではないトランザクションパラメータバッファ（TPB）アイテムの組み合わせをリジェクトするようになりました。 + + 例えば、ゼロではないwait timeoutはno waitオプションと矛盾します；また、no record versionは任意のトランザクション分離モードと矛盾します。本来のあいまいさについて、いくぶん恣意的で（そして恐らく不正確な）仮定を行う代わりに、エンジンはこのような組み合わせを無効としてリジェクトするようになりました。 + 詳細は、Firebirdエンジンの変更の章のトランザクションの診断の項を参照して下さい。 +
+ +
+ SQL_NULL定数の追加 + SQL_NULL定数が導入されたことで、OR ? IS NULL句が認識され、未知のデータ型の例外を発生させることなく処理され、期待された結果を出せようになりました。このことは、XSQLVAR構造体がこの種のクエリに配置される仕方に影響を与えます。詳細は、DMLの章のSOME_COL = ? OR ? IS NULL Predicationの項を参照して下さい。 +
+
+ +
+ セキュリティの強化 + 以下の変更に注意して下さい。 + +
+ SYSDBA自動マッピングの廃止（Windows版） + バージョン2.1では、Windows管理者グループのメンバーは、デフォルトでSYSDBAにマッピングされていました。バージョン2.5以降は、SYSDBAのマッピングは新しいSQLコマンドを使ってデータベースごとに制御されます。 + ALTER ROLE RDB$ADMIN SET/DROP AUTO ADMIN MAPPING + 詳細は、セキュリティに関する章を参照して下さい。 +
+ +
+ デフォルトの認証方法（Windows） + Windowsの信頼された認証が導入されたバージョン2.1では、デフォルトの認証方法はmixedです。つまり、DPBやSPBは、nativeのFirebirdログインもtrustedのユーザーログインもアクセプトします。そのため、firebird.conf内のAuthenticationパラメータはデフォルトでmixedを示していました。 + バージョン2.5以降、デフォルトはnativeとなりました。mixedまたはtrustedとするには、このパラメータを明示的に設定する必要があります。 + トラッカー・リファレンス CORE-2376 +
+
+ + + +
+ サービスへのアクセスパス + Firebirdの以前の一部のバージョンでは、データベース名の引数としてサーバーのフルパスが与えられていれば、SYSDBAパスワードがクライアントとサーバーの両方で同じだった場合、サービスへのリモートアクセスが有効になっていたようです。これらの条件下では、例外がスローされず、アクセスは成功していました。 + 例えば、リモートのクライアントがリモートサーバーと同じSYSDBAパスワードを持ったFirebirdサーバーを稼動していた場合、gbakへのリモートの呼び出しのための以下の構文が有効となっていたようです。 + +gbak -b -se dbhost:service_mgr dbhost:dbalias + /var2/backups/mydb.fbk -user SYSDBA -password masterke + + 一部の開発者は長い間これをドキュメント化されていない機能かと思っていましたが、残念ながら、この異常はバグでした。バージョン2.5では、どのような条件の下でも、この構文は例外となります。正しい構文は次の通り： + +gbak -b -se dbhost:service_mgr dbalias + /var2/backups/mydb.fbk -user SYSDBA -password masterke + +gbak -b -se dbhost:service_mgr d:\databases\mydb.fdb + x:\backups\mydb.fbk -user SYSDBA -password masterke + +
+ +
+ プラットフォーム固有の既知の問題 + エンジンなどの変更により、一般的な問題以外に、いくつかのプラットフォームで固有の影響が出る可能性があります。既知の問題は以下に記載されています。 +
+ MacOSX版 + マルチスレッド環境で新しいエンジンを正しく動作させるには、Grand Central Dispatchを使う必要があります。これはMacOSX 10.6（Snow Leopard）で最初にリリースされたため、MacOSXのユーザーは、Firebird 2.5がMacOSX 10.6以上のバージョンでなければ起動しないことを認識して下さい。 + + OSXの以前のバージョンを使いたい場合は、Firebirdも以前のバージョンのものを使う必要があります。 + +
+
+ diff --git a/src/docs/rlsnotes-ja/rlsnotes25/ConfigParams25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/ConfigParams25.docbook new file mode 100644 index 00000000..844dfbcd --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/ConfigParams25.docbook @@ -0,0 +1,186 @@ + + + 設定パラメータの追加と変更 + + firebird.confへの以下の変更・追加に注意して下さい： + +
+ + AuditTraceConfigFile + V.Khorsun + + このパラメータは、Firebirdエンジンが次のシステム監査トレースに必要なイベントのリストを決定するために読むべきファイルの名前と配置を示します。デフォルトではこのパラメータの値は空で、どのシステム監査トレースも設定されていないことを示しています。 + + Firebirdのルートディレクトリ内にあるテンプレートファイルfbtrace.confには、監査トレース設定ファイルを記述するためのフォーマット、ルール、構文と、利用可能なイベントの完全なリストが含まれています。 + + 詳細は、新しい管理機能に関する章、トレースと監査サービスの節のシステム監査トレースのセッションの項を参照して下さい。 +
+ +
+ ファイルシステムのキャッシュの利用に影響するパラメータ + Firebirdとファイルシステムのキャッシュとの相互作用の仕方を設定するパラメータは二つあります。 + +
+ + FileSystemCacheSize + N.Samofatov + + Firebird 2.5で新たに導入されたFileSystemCacheSizeは、64bit Windows XPやService Pack 1以降のMicrosoft Server 2003ホストでWindowsファイルシステム・キャッシュが使用するRAMの最大量を制御します。 + バージョン2.5の当初のリリースでは、これによるPOSIXホスト・システムへの影響はありません。 + このパラメータの設定値は、OSが利用可能なトータルの物理RAMのパーセンテージを表す整数となります。有効な値となるためには設定値が10〜95（％）の範囲に収まらなければなりませんが、明示的に0と設定することでホストのキャッシング設定を適用することもできます。これ以外の数値は、デフォルトの30（％）と見なされます。 + firebird.confの設定をしても、サーバーのプロセスが再起動されるまで、変更は有効になりません。 + + + Windowsのセキュリティ権限 + OSのユーザーは、ファイルシステムのキャッシュ設定の調整にSeIncreaseQuotaPrivilegeが必要となります。この権利は管理者権限を持つユーザーとサービスアカウントに組み込まれており、Firebirdサービスアカウントにも、Windowsインストーラーによって明示的に付与されます。 + 異なる状況、例えば、エンベデッド版や、Firebirdサーバーをアプリケーションとして稼働する場合、またはカスタムサービスによるインストールの場合、ユーザーはこの権限を持っていないことがあります。このような設定ミスがあっても結果的にプロセスのスタートアップが失敗することはありません：firebird.logに警告が書き込まれ、スタートアップは単純にホストOSの設定により進行します。 + +
+ +
+ + FileSystemCacheThreshold + V.Khorsun + + + このパラメータはバージョン2.1でMaxFileSystemCacheとして導入されていますが、名称が変更されましたので、アップグレードする方への注意喚起のため、ここで改めて説明します。 + + FileSystemCacheThresholdは、Firebirdがページキャッシュとファイルシステム・キャッシュとの重複を許可するか否かを決める敷居値を設定します。このパラメータがゼロより大きい任意の（整数の）値に設定されている場合の効果は、ページキャッシュの現在のデフォルトサイズによって異なります：デフォルトのページキャッシュ（ページ単位）がMaxFileSystemCacheの値（ページ単位）よりも小さい場合にはファイルシステムのキャッシングは有効、それ以外の場合は無効となります。 + + このことは、ページキャッシュのバッファサイズが、DefaultDBCachePagesによって暗黙に設定されている場合にも、データベースのヘッダ属性として明示的に設定されている場合にも、いずれの場合にも適用されます。また、これは全てのプラットフォームに適用されます。 + + 従って、 + + + ファイルシステムのキャッシングを常に無効にするには、FileSystemCacheThresholdの値にゼロを設定します。 + + + ファイルシステムのキャッシングを常に有効にするには、FileSystemCacheThresholdの値に、データベースのページキャッシュのサイズを超える充分大きな整数値を設定します。ただし、この値による効果がページキャッシュのサイズに対するその後の変更によって影響を受けることに留意して下さい。 + + + + + + FileSystemCacheThresholdのデフォルトの設定値は65536ページです。つまり、ファイルシステムのキャッシングは有効となっています。 + + + 特定のデータベースに対して設定されたキャッシュサイズがFileSystemCacheThresholdの値より大きい場合、FileSystemCacheSizeの設定値（上記）はそのデータベースに影響を与えません。 + + + +
+ +
+ MaxFileSystemCache + Firebird 2.1で導入されたMaxFileSystemCacheは、もう有効なパラメータではありません。 +
+
+ +
+ + ConnectionTimeout + D.Yemanov + + 高負荷のWindowsシステムでは、サーバーがxnet_response_eventを設定するのを待つ間にクライアントがタイムアウトし、ローカル接続（XNET）に失敗することがありました。この問題を解決するため、ConnectionTimeoutパラメータが、TCP/IPに加えてXNET接続にも作用するよう拡張されました。 + + このパラメータ向けにドキュメント化された注意事項は、ネットワーク・トランスポートには今なお適用可能ですが、XNETのプロトコルには適用できません。 + +
+ +
+ + Authentication + A.Peshkov + + Windowsサーバー・プラットフォームでは、バージョン2.1以来、デフォルト以外のサーバー認証モードの設定が必要な場合にAuthenticationが使われてきました。 + + バージョン2.5でのモード設定はこれと同じです。すなわち、 + + + trustedは、Windowsの信頼された認証を利用します。適切な条件下では、Windows上で最もセキュアな認証方法となります。 + + + nativeは、従来のFirebirdサーバーの認証モードを設定します。セキュリティ・データベースに登録されたユーザー名とパスワードを用いたログインをユーザーに要求します。 + + + mixedは、trustedとnativeの両方を利用します。 + + + +
+ バージョン2.5での変更点 + + + バージョン2.5でも各モードに変更はありませんが、'mixed'または'trusted'モードに設定された場合、デフォルトでは、Windowsドメイン管理者へのSYSDBA権限の付与が自動で行なわれなくなりました。ODS 11.2データベースのロールRDB$ADMINやドメイン管理者へのSYSDBA権限の自動マッピングに関する管理機能の章の注意を参照して下さい。 + + + デフォルトの設定がmixedからnativeに変更されました。信頼されたユーザー認証を有効にする（mixedまたはtrusted）には、このパラメータの明示的な設定が必要になりました。 + トラッカー・リファレンス CORE-2376 + + +
+
+ +
+ + MaxUserTraceLogSize + V.Khorsun + + サービスAPIの新たなトレース機能を用いたユーザートレース・セッションによって生成されるテンポラリ・ファイル全体のサイズの最大値を設定します。デフォルト値は10MBです。一時的に出力を格納するファイル全体のサイズの最大値の上げ下げには、このパラメータを使用します。 +
+ +
+ + OldSetClauseSemantics + D.Yemanov + + Firebird 2.5より前のバージョンでは、UPDATE文のSET句によりユーザーが指定した順序に従ってカラムが割り当てられ、割り当てられた新しいカラムの値がその後の割り当てに即時に使用されていました。これは、カラムの開始値がSQL文の実行の間に維持されることを求めているSQL標準に準拠していませんでした。 + 現在は、SET句中のどの割り当てに対しても、元のカラムの値だけがアクセス可能となっています。 + 必要な場合は、OldSetClauseSemanticsの設定によって、このOldSetClauseSemanticsを介して、従来の挙動に戻すことができます。値を1に設定すると従来のもの、0（デフォルト）に設定すると修正後の挙動を示します。 + + + + このパラメータを変更すると、サーバー上の全てのデータベースに影響が出ます。 + + + このパラメータは後方互換性のための一時的な措置として提供されたものです。Firebirdの将来のバージョンでは非推奨となる予定です。 + + + +
+ +
+ + クラシックサーバー、スーパークラシックサーバーでのRemoteAuxPort + DmitryYemanov + + トラッカー・エントリー：CORE-2263 + クラシックサーバーとスーパークラシックサーバーで、RemoteAuxPortで指定された単一のポートからイベントの通知を受けるよう設定できるようになりました。スーパーサーバーではバージョン1.5から可能となっています。 + 待望されたこの改善により、アプリケーションが、使用するサーバー・モデルに関わらず、ファイアウォール越しであれ、セキュアなトンネル越しであれ、インターネット経由でデータベースに接続してイベントを利用することが可能になりました。 +
+ +
+ + RemoteBindAddressでのホスト名の使用 + AlexPeshkov + + トラッカー・エントリー：CORE-2094 + RemoteBindAddressの設定されたFirebirdサーバーが稼働しているホストのホスト名を使用できるようになりました。以前はIPアドレスしか使用できませんでした。 + + RemoteBindAddressはユーザー接続をホスト・サーバー上の特定のNICカードに固定的に割り当てるために使えます。指定したホスト名が一つ以上のIPアドレスに同時に関連づけられることのないよう注意して下さい！特に、ホスト・ステーション自体を含む全てのステーションで、etc/hostsファイルをチェックして下さい。 + +
+ +
+ + RemoteFileOpenAbility + NickolaySamofatov + + トラッカー・エントリー：CORE-2263 + POSIX版で、NFSデバイス上のデータベースへのアクセスを長時間許可する機能と合わせて、この極端なオプションをWindowsで利用可能にするため、また、ネットワーク上で共有されたデータベースを開けるようにするため、Red Soft社由来のコードが組み込まれました。 + これは、異なるプラットフォーム間で機能の整合性を維持するための試みです。アーキテクチャの変更に関わるものではなく、実際にこれを使用したからといって従来より安全になると考えられるというようなものでもありません。しかし、明確で、充分にテストされた、安全な目的のために、マッピングされた配置場所にデータベースのシャドウイングを行ない、外部のファイルシステム上のデータベースに接続することを可能にします。例えば、ときおり単発的なセキュリティタスクを実行するためディスクレスのワークステーションに差し込まれたUSBデバイス上にある鍵付きデータベースなど。 + + これをアクティベートする前に、firebird.conf内の注意をお読み下さい！ + +
+ diff --git a/src/docs/rlsnotes-ja/rlsnotes25/DDL25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/DDL25.docbook new file mode 100644 index 00000000..7a889c99 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/DDL25.docbook @@ -0,0 +1,576 @@ + + + データ定義言語（DDL） + + バージョン2.5では、DDLに対して重要な追加と拡張が施されました。 + + + + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/DML25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/DML25.docbook new file mode 100644 index 00000000..6c4d2d87 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/DML25.docbook @@ -0,0 +1,652 @@ + + + データ操作言語（DML） + + この章では、Firebird 2.5でSQLのデータ操作言語サブセットに施された追加と改善を扱います。 + + + + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/Engine25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/Engine25.docbook new file mode 100644 index 00000000..9881e83f --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/Engine25.docbook @@ -0,0 +1,355 @@ + + + Firebirdエンジンの変更 + + このリリースの主な目的は、マルチプロセッサのハードウェアが持つ対称型マルチプロセッシング（SMP）の性能を活用するため、Firebirdのスレッド・アーキテクチャをリファクタリングすることでした。これにより、複数のデータベースが同時にアクセスされるようなスーパーサーバーのスケーラビリティに著しい効果が得られます。しかし、その重要な成果は、Firebird 3に向けて開発中の、きめ細かなマルチスレッディングを支えるスーパークラシックサーバーモデルの登場です。 + +
+ + 新しいスレッド・アーキテクチャ + + DmitryYemanov + VladyslavKhorsun + AlexPeshkov + さらに─ + NickolaySamofatov + RomanSimakov + + + スーパーサーバーでは、新しいアーキテクチャの大きな利点として次の二点が挙げられます： + + + + + 複数データベース環境では、各データベースに対するスーパーサーバーのスレッドが、利用可能なプロセッサに均等に割り当てられます。 + + デフォルトのCpuAffinity設定では、スーパーサーバーはシングルプロセッサにバインドされたままです。複数のデータベースを活用する際にこの改善の恩恵を受けるには、firebird.confの設定を変更する必要があります。 + + + + SMPハードウェア上では、単一のデータベースを利用する場合でも、スケーリングのわずかな改善が認められるはずです。 + + + + クラシックサーバーでは、さらに顕著な効果が得られます： + + + クラシックサーバーがマルチスレッド化できるようになりました。1プロセスに1ワーカースレッドというモデルは従来通りですが、非同期のシャットダウン、スイープ、ロックマネージャとのプロセス間通信など並行したタスクの処理に追加のスレッドを利用できるようになりました。 + + + POSIX版では、クラシックサーバーでも、以前のようにフォークしたプロセスではなく、スレッドでサービスを運用できるようになりました。 + + Windows版のクラシックサーバーでは、サービスはバージョン2.1ですでにスレッド化されていました。 + + + + エンベデッドライブラリ—POSIX版ではlibfbembed.so、Windows版ではfbembed.dll—は、マルチスレッドに対応し、スレッドセーフとなっています。そのため、これらはマルチスレッドアプリケーションから利用できます。 + + + テストでは、このバージョンのクラシックサーバーのパフォーマンスは以前のバージョンに比べて相当速くなることが示されています。 + + + +
+ <quote>スーパークラシックサーバー</quote> + この、クラシックサーバーのマルチスレッド・モードは、単一のサーバー・プロセス内で—割り当て中またはプーリング中—の複数のワーカースレッドを処理する能力から、スーパークラシックサーバーと名づけられています。通常の機能については全てクラシックサーバーと共通していますが、二三の相違点があります： + + + どのプラットフォーム上でも、サーバーエンジンの安全かつ完全なシャットダウンが可能です。 + + + あるTPCベンチマークでは、クラシックサーバーを15〜20％ほど上回るパフォーマンスを示しています。 + + + カーネル・リソースの使用量が少なくなります（メモリ使用は減りませんが）。 + + + スーパークラシックサーバーのプロセスがクラッシュした場合、全ての接続が道連れになります。 + + + アタッチメント／アクティブユーザーのリストを取得できないなど、クラシックサーバー用サービスAPIに見られる制限は、スーパークラシックサーバーには適用されません。 + + + POSIX版のスーパークラシックサーバーが[x]inetdを必要としません。 + + + + エンベデッドサーバーに関する注意 + + + WindowsのDLLライブラリであるエンベデッドサーバーfbembed.dllが、以前のスーバーサーバーではなく、スーパークラシックサーバーを利用するようになり、このモデルをPOSIX上のスーパークラシックサーバーへのローカル接続に統合します。以前には単一のアプリケーション空間への接続を制限していたデータベースのファイルロックが、異なるエンベデッドサーバー・モジュールから同じデータベースへの同時アクセスを可能にするグローバルロックテーブルに置き換えられました。アプリケーションの同時デバッグやgbakやgstatのようなネイティブのユーティリティ・ツールの利用を容易にします。 + + + 単一のアタッチメント・ハンドルが同時スレッドに共有されるようになりました。（トラッカー・リファレンス CORE-2498 A. dos Santos Fernandes）。 + + + + +
+ 使用上の注意 + +
+ Windows版 + Windows版では、同じfb_inet_server.exeバイナリが、スイッチの設定によって、クラシックサーバーとスーパークラシックサーバー、いずれの作業モードをも提供します。デフォルトはクラシックサーバー・モードです。 + スーパークラシック・モードをサービスとして利用するには、次のように、コマンドラインでinstsvc.exeに-m[ulti-threaded]スイッチを付けます。 + +instsvc install -multithreaded + + スーパークラシックサーバーをアプリケーションとして運用したい場合は、次のようにします。 + +fb_inet_server -a -m + +
+ +
+ POSIX版の新バイナリ + POSIX版では、スーパークラシックサーバー・モデルとして新しいバイナリfb_smp_serverが提供されました。これにはネットワークリスナーが含まれているため、アタッチメント・リクエストに関してfbserverと同様に働き、[x]inetdを必要としません。 + + fb_smp_serverが使用するマルチスレッド・エンジンは、OSRI要請に従い、libfbembed.soとなっています。クラシックサーバーのパッケージにはfbguard（Guardian）も含まれます。これは、スーパークラシックサーバーのインストールの際に、fbserverではなくfb_smp_serverを開始します。スーパーサーバー・モデルがGuardianと一緒にインストールされた際に行われることと同様です。 + + 従来のクラシックサーバーの運用中にはfbguardを使用しないで下さい。 + +
+
+
+
+ +
+ + + DmitryYemanov + VladyslavKhorsun + AlexPeshkov + + スレッドセーフ・クライアント・ライブラリ + + トラッカー・リファレンス CORE-707 + エンベデッドライブラリを含むクライアント・ライブラリが、アプリケーションレベルでの同期なしでも、マルチスレッドアプリケーションで使用できるようになりました。 +
+ +
+ 改善点 + 実装された改善点は以下の通り： + +
+ + VladyslavKhorsun + クラシックサーバーで接続の切れたクライアントの即時検出 + + + クラシックサーバーが、クライアントの切断によって壊れたサーバーのプロセスを、すぐに検出できるようになりました。これに対し、未完了の活動を終了させたり、アクティブなトランザクションをロールバックしたり、ネットワークの接続を閉じたりといった対応をします。 + トラッカー・リファレンス CORE-818 +
+ +
+ 最適化 + 重要な最適化は以下の通り： + +
+ + DmitryYemanov + データの取得 + + 最適化により、どのフィールドもアクセスされていないテーブルについて、データ取得のパフォーマンスが改善されました。これは、例えば、SELECT COUNT(*)型のクエリに適用されます。 + トラッカー・リファレンス CORE-1598 +
+ +
+ + BLOBメモリの使用法 + Adrianodos Santos Fernandes + + 最適化により、それぞれの一時的なBLOBに割り当てる際に生成された、<ページサイズ>バイトのメモリ消費を避けることができます。 + トラッカー・リファレンス CORE-1658 +
+ +
+ + 更新パフォーマンスの改善 + V.Khorsun + + + この改善の狙いは、careful writeによる更新手続きの際にエンジンが優先的に行う書き込みの量を減らすことでした。従来の手続きでは、大規模な更新、特に同一のトランザクションで同一のレコードへの複数回の更新を行うupdates-in-placeのパフォーマンスに目立った影響が出ていました。最悪の場合には、更新の際に生成された全ての単一の新しいレコードのバージョンのために、ディスクにページが書き込まれることもありました。 + 内部で何が起きているのかについての簡単な技術的解説は、トラッカー・リファレンス (CORE-2672)を参照して下さい。 + + この解決策では、正しい優先順位を維持するためレコードの新バージョンと旧バージョンとが置かれたページ間で起きる循環参照から、書き込み操作を保護することに関わるプロセスで多大な時間を要する可能性があったという事態に対処しています。 +
+ +
+ +
+ + 64bitサーバーでのキャッシュサイズ制限の拡大 + V.Khorsun + + + トラッカー・リファレンス CORE-1687 + 以前の64bit版Firebirdサーバーでは、64bitアドレス空間の恩恵が受けられず、データベースのキャッシュを2GB（16K * 128K）以上に設定することができませんでした。この問題は今回のバージョンで修正されました。64bit版Firebirdでは、リソースが利用可能な場合、RAM内に5〜10GBのデータベースに完全に対応できる十分な大きさのキャッシュを設定することが可能になりました。 + + Firebirdのキャッシングは、ファイルシステムのキャッシュから多くの恩恵を受けることができますが、このことは、主に読み取りに負荷がかかる高スループット・システムにとって、おそらく重要な機能となっています。x64版Firebirdサーバーでのキャッシュの理論上の上限は2^31 -1（2,147,483,647）ページとなっています。 + +
+ +
+ + デフォルトでのデータベースの配置 + A.Peshkov + + + トラッカー・リファレンス CORE-1643 + 設定パラメータDatabaseAccessに、さらに多くの意味が付け加えられました。特に指定がない場合、エンジンは、Restrictリスト内のDatabaseAccessで最初に登録された配置場所を、新規にデータベースを作成する際や、接続パラメータによってエイリアスもフルパスも指定されていないデータベースを見つけるための、デフォルトの配置として受け取ります。 + この探索ロジックは、RestrictリストからExternalFileAccessパラメータに渡されて、外部テーブルを見つけるために使われるのと同様のものです。すなわち、 + + + Restrctリスト内の全てのディレクトリが最初に探索されます。 + + + 指定されたデータベースが見つからない場合： + + + CREATE DATABASEが含まれる場合、Restrictリスト内の最初の配置場所が使われます。 + + + そうでない場合、アタッチは期待通りには行なわれません。 + + + + + + + 注意 :: 現在の作業ディレクトリ + この機能は、直接ローカル接続するために指定されたデータベース・ファイルの暗黙の配置場所として現在の作業ディレクトリを使用することを禁ずるものではありません。これらの場合には、従来とまったく同様に、Y-valveがパス解決を処理します。 + データベースがどこにあるのか確かめる方法がないからといって、リモート・サブシステムを介して稼働中のスタンドアロンのサーバーが、パスの記述がないデータベース・ファイル名を使って接続しようとするというのは、まずありえない状況ですが、推奨されません。例えば、Windows版では、こうした状況での現在の作業ディレクトリは%system%となります。 + +
+ + + +
+ + Adrianodos Santos Fernandes + Windows版エンベデッドエンジン向けDLLのロード + + アプリケーション構成のインストール時に、いわゆるDLL地獄に陥った場合に共通して起こる問題を避けるため、Windows版エンベデッドエンジン向けのルート決定メカニズムが変更されました。以前には、ユーザーアプリケーションのメインの実行ファイルを含むディレクトリが暗黙のルートディレクトリとなっていました。今後は、リネームされたfbembed.dllライブラリが置かれているディレクトリとなります。 + トラッカー・リファレンス CORE-1814 +
+ +
+ + VladKhorsun + 大きな外部テーブルのサポートが有効に + + Firebirdの以前のバージョンでは、外部テーブルを使用する際に32bit I/Oを使っていたため、外部ファイルのサイズは2GB未満に制限されていましたが、64bit I/Oがサポートされるファイルシステム上では、外部テーブルメカニズムがこれを利用するよう拡張されたことで、2GBの制限は事実上撤廃されました。 + トラッカー・リファレンス CORE-2492 +
+ +
+ + データベースの統計が64bit値で適切に動作するように + + V.Khorsun + A.Peshkov + + + トラッカー・リファレンス CORE-2619 + Firebirdの以前のバージョンでは、メモリその他の統計が64bit値を適切に処理していませんでした。このイシューには二つの要素があります： + + + エンジンが統計に64bit整数を使えるように、AtomicCounterの内部が変更されました。 + + + isqlおよびqliのツールを64bit値に見合った動作をするよう改良する必要がありました。 + + + + 古いクライアントとの非互換性 + 32bitのツールが64bitのサーバーで正しく動作するため、いくつかの新しい内部API機能（struct perf64やperf64_xxx）を導入し、またそれらを使用するisqlやqliを変更する必要がありました。このことは、バージョン2.5のisqlとqliのプログラムが古いFirebirdクライアントとの互換性を持たないことを意味します。 + +
+ +
+ + Adrianodos Santos Fernandes + UDFのセーフガード + + トラッカー・リファレンス CORE-1937 + Firebirdサーバーがアクセスしているのと同じランタイムによって割り当てられていないポインタを返すような文字列UDFが書かれている場合、その宣言中のFREE_ITキーワードの存在が、メモリを汚染し、サーバーをクラッシュさせます。そのような異常なUDFに対するセーフガードとして、エンジンは… + + + そのようなUDFを検出し、例外をスローします。 + + + エンベデッド版を含む全てのサーバー・モデルで、更新されたib_utilライブラリがパスの中に存在するか否かに依存します。 + + +
+ +
+ 診断 +
+ + ClaudioValderrama + トランザクションの診断 + + TPBの内容に不正がある場合の診断とエラーレポートが改善されました。新たなTPB検証ロジックは、以下のものをリジェクトします： + + + 同じカテゴリの中で明らかに矛盾するオプション。例えば、一緒に指定された{WAIT}と{NOWAIT}、あるいは、{READ COMMITTED}と{SNAPSHOT}、あるいは、{READ ONLY}と{WRITE}。 + + + 無意味なオプション。例えば、SNAPSHOT分離モードに指定された[NO] RECORD VERSION。 + + + テーブル予約オプションの誤った命令。例えば、{READ <TABLE> PROTECTED}と間違えて{PROTECTED READ <TABLE>}。 + + + トラッカー・リファレンス CORE-1600 +
+ +
+ + AlexPeshkov + アクセス権のエラーメッセージ + + カラムに対するアクセス権の例外が起きた時、テーブル名とカラム名の両方が報告されるようになりました。 + トラッカー・リファレンス CORE-1234 +
+ +
+ + メッセージの改善 + V.Khorsun + + + トラッカー・リファレンス CORE-2587 + エンジンがWindowsの他のセッションで別のエンジンのプロセスによってすでにマッピングされた共有メモリを作成できない場合の診断メッセージが、少しだけユーザーフレンドリーになりました。従来は次のようなメッセージでした： + +The requested operation cannot be performed on a file with a user-mapped section open. + + （要求された操作はユーザーマップセクションで開いたファイルでは実行できません。） + これが、次のようなメッセージとなります： + +Database is probably already opened by another engine instance in another Windows session. + + （データベースはおそらく他のWindowsセッションの他のエンジンのインスタンスによりすでに開かれています。） +
+ +
+ +
+ メタデータの改善 + +
+ + Adrianodos Santos Fernandes + キャラクタ・セットをデフォルトのコレーションに保存 + + システムテーブルRDB$CHARACTER_SETS内のRDB$DEFAULT_COLLATE_NAMEの現在の値がバックアップ／リストアのサイクルの中で維持されるように改善されました。このカスタマイズのためのメカニズムが新しいALTER CHARACTER SETコマンドです。 + トラッカー・リファレンス CORE-789 +
+
+
+ + + + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/GeneralNotes25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/GeneralNotes25.docbook new file mode 100644 index 00000000..291faa10 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/GeneralNotes25.docbook @@ -0,0 +1,247 @@ + + + 一般的注記事項 + + + +
+ Firebird 2.5.4サブリリース + Firebird 2.5のこのサブリリースでは、一件の有用な新機能と、内部BLOB管理の改善が追加されています： + + + このサブリリースから、オンライン上にあるデータベースのテーブルとインデックスの検証を実行できるようになりました。 + 詳細は、Firebird APIとODSの変更の章のオンラインでの検証サービスの実行の項を参照してください。 + + + （CORE-4671）：メモリとディスク領域の解放のため、内部BLOBのリリースが早められました。 + Vlad Khorsunが実装しました。 + + + 2.5.3サブリリース以降のバグフィックス集はこちら。 +
+ + +
+ Firebird 2.5.3セキュリティアップデート1 + スーパーサーバーとスーパークラシックサーバーには公開された脆弱性があり、不正な形式のネットワーク・パケットによってセグメンテーション違反を起こし、クラッシュする可能性がありました。クラシックサーバーではこの問題はありませんでした。 + この脆弱性はAlex Peshkovによって修正されました。ビルド番号26778以下の全てのFirebirdスーパーサーバーとスパークラシックサーバーのバイナリ、また、2014年12月3日より前の全てのスーバーサーバーとスーパークラシックサーバーのスナップショットにはこの脆弱性が含まれます。 +
+ + +
+ Firebird 2.5.3サブリリース + + Firebird 2.5.1で作成またはリストアされたデータベースについての警告 + Firebird 2.5.1から上位のサブリリースへアップグレードする場合、データベース移行の際に、gbakを使用してバックアップ／リストアを行うことを強く推奨します。これを行えない場合でも、データベース移行時には最低でも全ての複合インデックスを再作成して下さい。 + Firebirdの比較的古いバージョン（ODS11.1以下）またはバージョン2.5.0からアップグレードするデータベースは、この不具合の影響を受けません。 + + + このサブリリースでは新機能の追加はありませんが、バージョン2.5.2以降に累積した多くのバグフィックスを含んでいます。このサブリリースでの改善点はわずかで小さなものです。すなわち、 + + + + 現在の接続と現在のトランザクションについての詳細情報を取得するため、SYSTEM名前空間に新しいコンテキスト変数が追加されました。 + 追加された変数：現在の接続についてはSYSTEM::CLIENT_PIDおよびSYSTEM::CLIENT_PROCESS、現在のトランザクションについてはSYSTEM::LOCK_TIMEOUTおよびSYSTEM::READ_ONLY。 + + + + 上限の拡大： + + + Windows上のスーパーサーバーとスーパークラシックサーバーへの最大接続数が1024から2048に拡大されました。 + + + 外部関数（UDF）の入力パラメータ数の上限が15まで拡大されました。 + + + + + + エラーレポートの改善： + + + 使用中のオブジェクトのエラーに関するレポートが詳細になりました。 + + + エラーを起こした文脈を特定しやすくするため、整合性制約検証エラーメッセージのテキスト中にリレーション名が追加されました。 + + + インデックスと制約の違反に関するエラーレポートが拡張され、問題のあるキーの値を含むようになりました。 + + + + + + 物理バックアップ（ALTER DATABASE BEGIN/END BACKUPコマンドやnBackupユーティリティを用いるもの）で、バックアップ状態がストールドからマージに切り替わる時、メインのデータベース・ファイルの伸張が高速化されるよう改善されました。 + + データベースの物理バックアップ状態がストールした時のアロケーションテーブル・ロックの競合が低減されました。 + + + fallocate()をサポートするLinuxシステム上では、ファイルサイズのより高速な拡大が可能となりました。 + + + アロケーションテーブルが初めて読み込まれる時にアタッチメントが他をブロックすることがなくなりました。 + + + + + + SET STATISTICS INDEX文を実行しても同時接続中のアタッチメントがブロックされたり遅延したりしなくなりました。 + + + + スイープ終了時のlimboトランザクションのスキャンが改善されました。 + + + + エンベデッドSQL（ESQL）にUPDATE OR INSERT文とRETURNING句のサポートが実装されました。 + + + +
+ + +
+ Firebird 2.5.2セキュリティアップデート1 + 2013年3月にFirebirdサーバーでのリモートスタック・バッファオーバーフローが見つかりました。これにより、認証されていないユーザーがサーバーをクラッシュさせたり、リモートからコードを実行することが可能となっていました。 + この脆弱性はAlex Peshkovによって修正されました。ビルド番号26539以下の全てのFirebirdバイナリと、2013年3月8日より前の全てのスナップショットにはこの脆弱性があります。 +
+ + +
+ Firebird 2.5.2サブリリース + RFC-4122の要請に正しく準拠するため、GEN_UUID()関数の実装に重大な変更が加えられました。詳細情報はこちらの項参照。 + ビッグエンディアンのプラットフォーム上で関数CHAR_TO_UUIDとUUID_TO_CHARの結果、問題のあるバイトオーダーやキャラクタオーダーが生成されていたバグが修正されました。この修正により、Firebird 2.5や2.5.1では、ビッグエンディアンのホスト上でこれらの関数を呼び出していたコードに影響が出ます。 + + バージョン2.5.1以降数ヶ月での累積分以上のバグフィックスに加え、このサブリリースでは、少数の小さな改善、特に管理者支援に関する改善が施されました。概要： + + + トレース・サービスにいくつかの歓迎すべき改善が施されました。すなわち、 + + + 手動・自動スイープ活動のログを取るためのセッションが設定できるようになりました。このオプションに関するドキュメントは、トラッカー・チケットCORE-3656で見ることができます。 + + + TRACEが、トランザクション終了後に起こるアクションの統計情報を生成するようになりました。トラッカー・チケットCORE-3598参照。 + + + TRACEに、実行時に発生したエラー（ロックコンフリクトやキー違反など）のログを取る機能が提供されました。トラッカー・チケットCORE-3539参照。 + + + + + + リモートのバックアップ／リストアを実行するAPIが利用できるようになりました。 + リモート・バックアップファイルによるバックアップとリストア参照。 + + + + 自動スイープの開始時、firebird.logにログが書き込まれるようになりました。 + + + + FirebirdのビルドシステムにCプリプロセッサフラグのサポートが追加されました。 + + + +
+ +
+ Firebird 2.5.1サブリリース + このサブリリースでは、かなりの数のバグフィックスに加え、先のリリースでは見落とされていた少数の小さな改善と最適化が施されています。概要： + + + MacOSX 10.7で、スーパーサーバーとスーパークラシックサーバーの起動に失敗するという重大なバグがありました。このバグは、トラッカー・チケットCORE-3589に記載され、このサブリリースのBug Fixes listにも載せられています。 + + + + WHEN文中でエラー条件のテストに使われるコンテキスト変数GDSCODEやSQLCODEに相当するコンテキスト変数SQLSTATEがPSQLで利用できるようになりました。 + + + + グローバル一時表（GTT）使用時のパフォーマンスを向上させる二三の改善が施されました。 + + + トランザクションをロールバックする際、ON COMMIT DELETE ROWSオプション付きで生成されたGTTに加えられた変更の取り消しは、不要なオーバーヘッドだったため、回避されました。 + + + グローバル一時表のガベージコレクションは他のアタッチメントでアクティブなトランザクションによって必要以上に遅くなっていました。このボトルネックは解消されました。 + + + + + + 小さなチャンクの割り当てに関して、テンポラリ・スペース・マネージャに必要な最適化が施されました。 + + + + DELETE FROM MON$xxxやfb_cancel_operationのいずれの要求にも応じない他のトランザクションが終了するまで、トランザクションがWAITモードのまま果てしなく待機し続けるというような状況を回避するため、待機状態をキャンセルできるロックマネージャが提供されました。 + + + + クエリオプティマイザが実際のレコード圧縮比を推定することで、テーブル内に格納されたレコード数のより正確な推測が可能になりました。 + + + + リモートインターフェースにいくつかの小さな改善が施されました： + + + メッセージ・バッファ内の未使用のVARCHAR値のバイト数がゼロに設定されるようになりました。 + + + SO_KEEPALIVEオプションをクライアントのTCPソケットに設定して下さい。 + + + + + + MON$STATEMENT_ID値の定数が監視中のスナップショットの間でも定数として維持されるようになりました。 + + + + このサブリリースでは、Linux/HPPAおよびLinux/Alpha向けのポーティングも完了しています。 + + + + +
+
+ + + バグレポート + + + + このリリースで新たなバグを発見したと思った方は、Firebirdプロジェクトのウェブサイト中の記事[[有効なバグレポートの書き方]]で、バグレポートに関する説明をぜひお読み下さい。 + + + バグフィックスが無効だったり不具合を起こしていると思った方は、トラッカーの中からもとのバグレポートを見つけ出し、必要ならそれを再開した上、以下の説明に従って下さい。 + + + 発見したバグをご自身で分析する場合は、以下のガイドラインに従って下さい： + + + + Firebirdの正確なビルド番号を記述し、詳細なバグレポートをお書き下さい。また、OSプラットフォームの詳細情報も記述して下さい。レポートには再現可能なテストデータを付けて、われわれのトラッカーにポストして下さい。 + + + + あなたがfield-testersメーリングリストに参加し、最善を尽したバグの記述をポストして、このプレリリース版のフィールドテスターとして名乗りを上げれば、温かく迎え入れられるでしょう。 + + + + バグや実装に関するディスカッションのスレッドを開始したい場合は、firebird-develメーリングリストに参加した上で行って下さい。フォーラム内でこのアルファ版に関するトラッカー・チケットをポストしておけば、フィードバックを受けられるかもしれません。 + + + + +
+ +
+ ドキュメント + このリリースノートで参照している全てのREADMEドキュメントは—参照されていない多くの他のドキュメントも—Firebird 2.5がインストールされたディレクトリのサブディレクトリ内にあります。 + トラッカー内に自動生成された"リリースノート"ページでは、このプレリリース・バージョンと他のプレリリース・バージョンに関連した全てのトラッカー・チケットのリストとリンクが提供されています。このリンクを利用して下さい。 + + --Firebirdプロジェクト +
+ diff --git a/src/docs/rlsnotes-ja/rlsnotes25/Installation25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/Installation25.docbook new file mode 100644 index 00000000..13c0aae7 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/Installation25.docbook @@ -0,0 +1,198 @@ + + + インストールの注意 + + + Firebird 2.5.1で作成またはリストアされたデータベースについての警告 + Firebird 2.5.1から上位のサブリリースへアップグレードする場合、データベースの移行の際に、gbakを用いてバックアップ／リストアを行うことを強く推奨します。これが実行できない場合でも、データベース移行時に、最低でも全ての複合インデックスの再作成を行って下さい。 + 比較的古いバージョン（ODS11.1以下）またはバージョン2.5.0からアップグレードするデータベースは、この不具合の影響を受けません。 + + + インストールと移行のガイド + Firebirdバージョン2.0.xと2.1.x向けのインストールと移行ガイド最新版の内容は、バージョン2.5シリーズにも適用できます。この文書のコピーが/doc/ディレクトリ内に存在しなくても、Firebirdのウェブサイトからダウンロードできます。 + + バイナリパッケージのインストールで問題が起きる可能性がありましたが、解決のためいくつかの改善が施されました。 + +
+ Linux（POSIX）版 + POSIX版のインストールに適用済みの改善内容は以下の通りです。 +
+ + インストール・スクリプトの刷新 + + AlexPeshkov + + + + + （CORE-2195）：Linux版クラシックサーバーのインストール・スクリプトが見直され、ドキュメントその他のコンポーネントの所有権とアクセス権の割り当てが改善されました。 + + + （CORE-2392）：アクティブなPOSIX版スーパーサーバー、スーパークラシックサーバー向けポートの全てのインストール・スクリプトが刷新され、これらのプラットフォーム上で起きていたGuardianに関する問題への対処が行われました。 + + + （CORE-2626）：/etc/init.d中のスタートアップ・スクリプトは、これまでホスト・システム内の/var/run/firebirdディレクトリと/tmp/firebirdディレクトリの存在を考慮に入れていませんでした。スタートアップの失敗には様々なタイプのものがありますが、多くはこの欠陥に由来するものでした。 + バージョン2.5とそれ以降のビルドで配布されるスタートアップ・スクリプトではこの問題は対処済みで、解決しています。 + + + + （バージョン2.5.1 CORE-3467）：make installにサイレントインストール・スイッチ（-silent）が追加され、シンプルなインストールと、ビルドとテスト実行の自動化が実現されました。このスイッチを使うとFirebirdのインストールは一切プロンプトを出さずに進行し、SYSDBA用にランダムパスワードが生成されます。このランダムパスワードは、セキュリティ・データベースsecurity2.fdbと同じ配置場所にあるファイルに保存されます。 + + +
+ +
+ + Firebirdの'configure'専用スイッチ + + AlexPeshkov + + + POSIXプラットフォーム上でインストール・ディレクトリの微調整に使われる標準的なconfigureスイッチの多くは、Firebirdには役立ちません。 + 標準的なGNUのスイッチをデフォルト設定を変更せずに機能させるのは不可能に近く、簡単明瞭とはほど遠い煩雑なものでした。これらに代わり、configure用の新たなスイッチのセットが追加され、Firebirdのファイル群のきめ細かな配置の設定が可能になりました。 + ib_utilローダーも改善され、設定されたレイアウトに応じてエンジンが正しく動作するようになりました。 +
+ 利用可能なスイッチ + + --with-fbbin 実行ファイルを含むディレクトリ（PREFIX/bin） + --with-fbsbin システム管理用実行ファイルを含むディレクトリ（PREFIX/bin） + --with-fbconf 設定ファイルを含むディレクトリ（PREFIX） + --with-fblib オブジェクトコード・ライブラリを含むディレクトリ（PREFIX/lib） + --with-fbinclude C/C++ヘッダファイルを含むディレクトリ（PREFIXinclude） + --with-fbdoc ドキュメント類を含むディレクトリ（PREFIX/doc） + --with-fbudf URFを含むディレクトリ（PREFIX/UDF） + --with-fbsample サンプルを含むディレクトリ（PREFIX/examples） + --with-fbsample-db サンプルデータベースを含むディレクトリ（PREFIX/examples/empbuild） + --with-fbhelp QLIのヘルプを含む（PREFIX/help） + --with-fbintl 国際化用ディレクトリ（PREFIX/intl） + --with-fbmisc その他のファイルを含むディレクトリ（PREFIX/misc） + --with-fbsecure-db セキュリティデータベースを含むディレクトリ（PREFIX） + --with-fbmsg メッセージファイルを含むディレクトリ（PREFIX） + --with-fblog ログファイルを含むディレクトリ（PREFIX） + --with-fbglock ガーディアン・ロックを含むディレクトリ（PREFIX） + --with-fbplugins プラグインを含むディレクトリ（PREFIX） + +
+
+ +
+ + Firebirdバイナリのパス検出 + + Adrianodos Santos Fernandes + + + トラッカー・リファレンス CORE-2398 + POSIXビルド向けに、バイナリがインストールされた場所のパスをFirebirdに正しく検出させる機能が実装されました。 + + 現状、これは実験段階であり、配布版のバイナリでは無効になっています。これをアクティベートするには、Firebirdをソースからビルドする際に、autogen.shに--enable-binrelocを渡して下さい。 + +
+
+ +
+ Windows版 +
+ + エンベデッド版向けのデプロイ構造 + + + Adrianodos Santos Fernandes + + + VladKhorsun + + + + トラッカー・エントリー：CORE-1814 + このリリースでは、エンベデッド版のアプリケーション・コンポーネントの配置を従来よりやや柔軟に設定できます。ここでの変更は、アプリケーション開発者の間で問題となっていた、相互に関連するいくつかのイシューに対処したものです。すなわち、 + + + ib_util.dll、またはfbembed.dll中のクライアントコード、または完全な外部ライブラリなど、他のDLLに依存する外部関数ライブラリをFirebirdの擬似ルートディレクトリ（<root>）下の..\UDFフォルダにそのまま置くことはできませんでした。依存しているファイルが通常その配置場所には存在しないからです。そのため、%PATH%変数を使ってちょっとした工夫をする必要がありました。 + + + 従来の擬似<root>の決定ルールは、アプリケーションコードとしてそのフォルダにfbembed.dll（リネームしたものでも可）が存在することを要求していました。その影響で、これを必要とする各アプリケーション用にfbembed.dllの別々のコピーを確保するか、または、実行可能な全てのクライアントを一箇所に配置するか、いずれかの対応が必要でした。 + + + バージョン2.5のエンベデッド版エンジンでは<root>の決定が変更され、もはやそこがアプリケーションのパスである必要はありません。それは、どこであれfbembed.dllの配置によって決まります。このことは、バージョン2.5のエンジンでは、かつてはfbembed.dllをロードしていた任意のエンベデッドアプリケーションやサードパーティ製UDFライブラリやコマンドラインツールのローカルコピーで利用できるFirebirdの擬似<root>のために標準の自己充足的なストラクチャーをセットアップできることを意味します。 + Firebirdの擬似ツリーをアプリケーションから切り離したい場合は、必ず、そのストラクチャーのfirebird.confファイル内で<root>の配置の絶対パスを示すRootDirectoryパラメータを設定して下さい。 + + + 新たなルールが既存のエンベデッドストラクチャーを破壊することはありません。従来通りのやり方でエンベデッドアプリケーションを構築することができます。違いは、実行ファイルをエンベデッド版Firebirdの擬似<root>ストラクチャー専用のコピーと一緒にデプロイする必要がなくなったということです。 + +
+ +
+ + MSCV8アセンブリの管理 + + VladKhorsun + + + トラッカー・エントリー：CORE-2243 + + この変更が施されたのがバージョン2.1.2からだったため、この議論もV.2 インストールと移行に関するドキュメント内に特別なトピックとして登場しています。 + + + Firebird 2.5はVisual Studio 2005のMicrosoft MSVC8コンパイラでビルドされています。Firebirdの全バイナリはビルド時に動的リンキングを用いているため、それらは全てランタイム・ライブラリを必要とします。 + dll地獄問題を避けるため、Microsoftは複数のアプリケーションで共有される可能性のあるコンポーネントの配布に新たなルールを導入しました。Windows XP以降、共有ライブラリ—Visual C++やVisual Cのランタイムmsvcp80.dllやmsvcr80.dll、mscvcm80.dllなど—は、共有アセンブリまたはプライベートアセンブリとして配布される必要があります。 + + + Microsoft MSIインストーラーは共有アセンブリを複数のアプリケーションで使用される共通の特別フォルダSxS内にインストールします。 + + + プライベートアセンブリはアプリケーションと一緒に配布され、アプリケーションフォルダに置かれます。アセンブリが\system32フォルダを使用することはXP、Server2003、Vistaプラットフォーム・ファミリーでは禁止されています。 + + + +
+ 共有アセンブリとしてのランタイムのインストール + ランタイムを共有アセンブリとしてインストールするには、デプロイするシステム上にMSI 3.0がインストールされている必要があり、また、ユーザーが管理者権限を持っていなければなりません。アプリケーションがエンベデッド版Firebirdと一緒にデプロイされていて、これが不可能となる場合がしばしばあります：エンベデッドサーバーはインストールされていて、実行可能な状態でなければなりません。この場合、ランタイムを共有アセンブリとしてインストールすることは計画しないで下さい。 +
+ +
+ プライベートアセンブリとしてのランタイムのインストール + + MSVC8ランタイムライブラリをプライベートアセンブリとしてインストールするには、その内容物—上記の三つのDLLとアセンブリのマニフェストファイルMicrosoft VC80.CRT.manifest—を、これらに依存するバイナリ（.exeまたは.dll）が存在する全てのフォルダに置いておく必要があります。それらのバイナリには、コンパイル時に使用されたライブラリと同等のランタイムの配置が期待されるフォルダに対するチェックが組み込まれているためです。 + 典型的なエンベデッド版Firebirdのインストールでは、MSVC8ランタイムアセンブリの完全なコピーが三つ必要になります：アプリケーションフォルダに一つ、\intlフォルダと\udfフォルダにそれぞれ一つずつ。インストールの膨張問題を避けるため、バージョン2.1.2向けFirebirdバイナリの一部のビルド方法にいくつかの変更が加えられています。（トラッカー・エントリー CORE-2243も参照して下さい）。 + これらは、アプリケーション構成がMSVC8ランタイムアセンブリを組み込んでいない場合でもエンベデッド版Firebirdが動作できるようにするための変更です： + + + ib_util.dll、fbudf.dll、ib_udf.dll、fbintl.dllはエンベデッドマニフェストなしでビルドされています。その効果として、ローダーが対応するDLLと同じフォルダでMSVC8アセンブリを検索するのを避けることができます。ホストのプロセスは、これらのセカンダリDLLをロードしようとする前に、マニフェストを介してMSVC8ランタイムをロードし終えていなければなりません。 + + + 現在のfbembed.dllには、必要となる可能性がある任意のセカンダリDLLをロードする前に、自身のマニフェストからアクティベーションコンテキストを生成しアクティベートするためのコードが含まれています。 + + +
+ + + 注意 + + + MSVC8ランタイムをインストールするMicrosoftの再配布パッケージの利用を強く推奨します！インストール実行ファイルvcredist_x86.exeまたはvcredist_x64.exe（あなたが選択したFirebirdに適したもの）がフルインストール用またはエンベデッド版用のzipファイル一式の中にあるはずです。存在しない場合も、Microsoftのダウンロードサイトから落としてくることができます。 + + + + MSVC8ランタイムアセンブリがプライベートアセンブリとしてインストールされる場合、サードパーティ製UDFは以下の条件のうち一つを満たしている必要があります。UDFライブラリをコンパイルする際に、MSVC8ランタイムは次のいずれかとなります： + + + 使用されない + + + 使用されても、エンベデッドマニフェストなしでビルドが行われる + + + 使用され、エンベデッドマニフェストがビルドに使われる—MSVC IDEのデフォルトオプション。この場合、MSVC8アセンブリは同じフォルダになければなりません + + + + + +
+ +
+ + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/Intl25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/Intl25.docbook new file mode 100644 index 00000000..cf39a559 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/Intl25.docbook @@ -0,0 +1,131 @@ + + + 国際言語のサポート（INTL） + + Adriano + dos Santos Fernandes + + + + このリリースでは、Firebirdによる国際言語環境の処理機能を厳格化し、また拡張するため、いくつかの改善が施されました。 + +
+ + データベースのデフォルトのコレーション属性 + + ODSバージョン11.2以上では、デフォルトのキャラクタ・セットと関連づけられたデフォルトのコレーション属性を持つデータベースを任意に作成できるようになりました。詳細は、DDLの章のデータベースのデフォルトのコレーション属性を参照して下さい。 +
+ +
+ + ALTER CHARACTER SET コマンド + + DDL構文が導入され、データベースレベルで設定されるキャラクタ・セットのコレーションがデフォルトで可能になりました。詳細は、DDLの章のALTER CHARACTER SET コマンドを参照して下さい。 +
+ +
+ 接続文字列とキャラクタ・セット + ファイル名に非ASCIIキャラクタを含む場合に起きがちだった問題を避けるため、APIデータベース接続（DPB）エリアに、サーバーとクライアントのキャラクタ・セットおよび／またはコードページと連携する機能が実装されました。 + Firebird APIとODSの変更の章の接続文字列とキャラクタ・セットの項を参照して下さい。APIに特に興味がない方でも、この種のの問題に悩まされたことがあれば、この項は読んでおく価値があるでしょう。 +
+ +
+ その他の改善点 + +
+ Introducer構文の使用法 + introducer構文、つまり、キャラクタ・セット名にアンダースコアを前置することにより、それに続くリテラルなテキストを強制的にそのキャラクタ・セットに変換させる手法を用いた場合、一つのSQL文が複数のキャラクタ・セットを扱わざるをえない状況で、問題が起きることがありました。実際に起きる問題は、変換エラーや、不正な形式の文字列のエラー、または何らかの予期せぬ挙動を示すといったように、バージョンによって異なります。 + + 二つの違った使用シーンで問題が起きるようです─ + + + あるクエリがMON$STATEMENTSからselectを実行している時に、他のクエリがintroducer構文を使う場合 + + + introducer構文がPSQLモジュールで使用された場合 + + + このような問題を回避するため、リテラルな文字列をintroducerから渡されるASCIIキャラクタによる16進表現に変換できるようになりました。例えば、 + + + select _dos850 '123áé456' from rdb$database + + これが、次のように変換されます + + + select _dos850 X'313233A082343536' from rdb$database + +
+ +
+ 不正な形式のUNICODE_FSSキャラクタの禁止 + トラッカー・リファレンス CORE-1600 + 不正な形式のキャラクタがUNICODE_FSSカラムのデータとして認められなくあんりました。 +
+ +
+ 不正な形式の文字列の修正 + gbakユーティリティ・コードに新しいリストア・スイッチが追加され、影響を受けたデータベースのバックアップをリストアし、不正な形式のUNICODE_FSSデータやメタデータを修正できるようになりました。詳細は、ユーティリティの章のgbakの節をを参照して下さい。 +
+ +
+ 数値ソート属性 + トラッカー・リファレンス CORE-1945 + UNICODEコレーション向けに、数値のソート用オーダーを指定するカスタム属性NUMERIC-SORTが使えるようになりました。 + + フォーマットと使用法 + + NUMERIC-SORT={0 | 1} + + デフォルト値は0で、数値もアルファベットのオーダーでソートされます。例えば： + + 1 + 10 + 100 + 2 + 20 + + 値を1に設定すると、数値のオーダーでソートされます。例えば： + + 1 + 2 + 10 + 20 + 100 + + 例 + +create collation unicode_num for utf8 +from unicode 'NUMERIC-SORT=1'; + +
+ +
+ キャラクタ・セットとコレーション +
+ UNICODE_CI_AI + トラッカー・リファレンス CORE-824 + + UNICODE_CI_AI：UTF8向けに大文字小文字、アクセント記号を無視したコレーションが追加されました。 + +
+
+ WIN_1258 + トラッカー・リファレンス CORE-2185 + 他のWIN*キャラクタ・セットとの整合性のため、キャラクタ・セットWIN1258にエイリアスWIN_1258が追加されました。 +
+
+ キャラクタ・セットSJISおよびEUCJ + トラッカー・リファレンス CORE-2103 + キャラクタ・セットSJISとEUCJの文字列で適格性の検証が行われるようになりました。 +
+
+ キャラクタ・セットGB18030 + トラッカー・リファレンス CORE-2636 + GB18030は、中国国内のソフトウェアに必須の言語・キャラクタをサポートする中国語の国家規格です。ICUからアクティベートされています。 +
+
+ +
+ + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/Licence25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/Licence25.docbook new file mode 100644 index 00000000..7d58d321 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/Licence25.docbook @@ -0,0 +1,11 @@ + + Licence Notice + + このドキュメントの内容はPublic Document Licence バージョン1.0（the License）の下で公開されています；あなたはこのライセンスの条項を遵守する限りにおいて、このドキュメントを使用することができます。このライセンスのコピーはhttp://www.firebirdsql.org/pdfmanual/pdl.pdf（PDF）およびhttp://www.firebirdsql.org/manual/pdl.html（HTML）より入手可能です。 + + オリジナルのドキュメントのタイトルはFirebird 2.5 Release Notesです。 + + オリジナルのドキュメントの筆頭執筆者は、Helen Borrieです。各担当で名前の挙げられた人たちが寄稿しています。 + + Copyright (C) 2004-2009。すべての権利を保有しています。筆頭執筆者連絡先：helebor at users dot sourceforge dot net. + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/NewFeatures25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/NewFeatures25.docbook new file mode 100644 index 00000000..c9bd31ab --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/NewFeatures25.docbook @@ -0,0 +1,203 @@ + + + Firebird 2.5の新機能 + + + + + + Firebird 2.5では、より低レベルな同期とスレッドの安全性を概ね確保できる新しいスレッド・アーキテクチャの基礎を確立し、これをスーパーサーバー、クラシックサーバーからエンベデッドモデルにまで全面的に適用していくことが大きな目標でした。 + +
+ Firebird 2.5.4リリース（2015年3月） + このサブリリースについての一般的注記事項を参照して下さい。 +
+ +
+ Firebird 2.5.3セキュリティアップデート（2014年12月） + このパッチリリースについての一般的注記事項を参照して下さい。前回リリースのスーパーサーバーとスーパークラシックサーバーに存在した脆弱性が修正されています。 +
+ +
+ Firebird 2.5.3リリース（2014年7月） + このサブリリースについての一般的注記事項を参照して下さい。 +
+ +
+ Firebird 2.5.2セキュリティアップデート1（2013年3月） + このパッチリリースについての一般的注記事項を参照して下さい。 +
+ +
+ Firebird 2.5.2リリース（2012年10月） + このサブリリースについての一般的注記事項を参照して下さい。 +
+ +
+ Firebird 2.5.1リリース（2011年9月） + バージョン2.5では、最初のリリース以来数ヶ月にわたる数多くのトラッカー・イシューへの取り組みにより、「broken（壊れている）」「bent（挙動が怪しい）」「compromised（欠陥がある）」との報告を受けた事柄への対処が行われてきました。バグフィックスの長いリストに加え、少数の小さな改善が加えられています。概要： + + + SQLSTATEコードがPSQLのコンテキスト変数として、WHEN .. exception文中でのGDSCODEやSQLCODEと同様の方法で利用できるようになりました。 + + + 読み取り専用のデータベース中でグローバル一時表への書き込みが可能になりました。 + + + 内部トレース・エラーの診断が改善されました。 + + + fbtracemgrユーティリティが定期的に出力への書き込みを行うようになりました。 + + + データ書き込み段階でのgbakによるリストアのパフォーマンスが改善されました。 + + + BLOBと他のデータタイプとの変換がAPIの機能で可能になりました。 + + + サービスAPIがmetadata-onlyリストアをサポートするようになりました。 + + + POSIXでのmake installにサイレントインストールスイッチが実装されました。 + + + メッセージ・バッファ内の未使用のVARCHAR値のバイト数がゼロに設定されるようになりました。 + + + オプティマイザで実際のレコード圧縮比が推定されるようになりました。 + + + MON$STATEMENT_ID値が監視中のスナップショットの間でも定数として維持されるようになりました。 + + + 最近のWindowsシステムによる攻撃的なソケットのタイムアウトから保護するための措置として、SO_KEEPALIVEオプションがクライアントのTCPソケットに設定されるようになりました。 + + + ロックマネージャの使用により果てしない待機状態をキャンセルできるようになりました。 + + + バージョン2.5.1のLinuxとAlpha向けのポーティングが行われました。 + + + +
+ +
+ Firebird 2.5リリース（2010年10月） + SQLの拡張はこのリリースの主たる目的ではありませんでしたが、SQLにCREATE/ALTER/DROP USER文や、ALTER VIEWとCREATE OR ALTER VIEW向けの構文が実装されたことで、初めてユーザー管理が可能になりました。PSQLの改善には、自律型トランザクションの導入や、EXECUTE STATEMENTを介して別のデータベースにクエリを発行する機能などが含まれます。 +
+
+ その他の新機能 + このリリースでの他の新機能と改善点は、以下の通り： + +
+ 管理の強化 + + + サービスAPIを介したシステム監査トレースとユーザートレースのセッションにより、データベース内で動作中のあらゆる事柄をリアルタイムで監視・分析することが可能になりました。 + + + + ODS 11.2データベースで追加された新しいシステムロールRDB$ADMINにより、SYSDBAがデータベースごとに自身の権限を他のユーザーへ譲渡できるようになりました。 + + + モニタリングテーブル内の情報が詳細になりました。 + + + 接続を非同期にキャンセルできるようになりました。 + + + 通常のユーザーが、CURRENT_CONNECTIONだけでなく自身のどのアタッチメントに対しても監視を行えるようになりました。 + + + +
+ + +
+ 他のSQL言語の追加と拡張 + + + SIMILAR TO句を用いた正規表現がサポートされました。 + + + 計算項目に対するALTER COLUMNが実装されました。 + + + PSQLモジュール（ストアドプロシージャ、トリガ、動的に実行可能なPSQL文）内での自律型トランザクションが利用可能になりました。 + + + ビュー定義でのストアドプロシージャへのアクセスが拡張されました。 + + + + GRANT文やREVOKE文のオプションGRANTED BY（またはAS）により、CURRENT_USER（デフォルト）以外のユーザーを権限付与者とすることが可能になりました。 + + + REVOKE ALL構文により、一度にユーザーやロールの全ての権限を取り消すことが可能になりました。 + + + WHERE SOME_COL = ? OR ? IS NULL句がサポートされました。 + + + 標準SQLの予約語ではないキーワードの内、一部のものを除いて予約語から解除しました。 + + + +
+ +
+ データ処理の拡張 + + + 新しい組み込み関数により、UUID CHAR(16) OCTETS文字列からRFC4122-compliantフォーマットへの変換とその逆の変換が可能になりました。 + + + 32-bit整数と64-bit整数を、数値リテラル形式およびX-prefixedバイナリの文字列リテラル形式のhexadecimalとして渡せるようになりました。 + + +
+ +
+ APIの追加 + + + SQL文が、SQL-2003標準の英数5文字のSQLSTATEコードを返すようになりました。 + + + バージョン2.5.1サブリリースで、SQLSTATEコードがPSQLのコンテキスト変数に追加され、WHEN .. exception文中でのGDSCODEやSQLCODEと同様の方法で利用できるようになりました。 + + + + 新しい定数DSQL_unprepareをisc_dsql_free_statementで利用することによって、プリペアドステートメントを効率的にアンプリペアすることができるようになりました。 + + + + + +
+ +
+ 国際言語のサポート + + + CREATE DATABASE文でデフォルトCOLLATE句を指定できるようになりました。 + + + 使用するキャラクタ・セットに合わせてデフォルトCOLLATEを変更できるようになりました。 + + + + GBAKのリストア・スイッチFIX_FSS_DATAとFIX_FSS_METADATAにより、スクリプトや手作業に頼らずに、UNICODE_FSSデータおよび／またはメタデータを含むレガシー・データベースを正しくリストアできるようになりました。 + + + + Unicodeのアクセントを区別しないコレーションが可能になりました。 + + + +
+ +
+ diff --git a/src/docs/rlsnotes-ja/rlsnotes25/PSQL25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/PSQL25.docbook new file mode 100644 index 00000000..4723ecc0 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/PSQL25.docbook @@ -0,0 +1,615 @@ + + + 手続き型SQL（PSQL） + + Firebirdの手続き型言語（PSQL）にいくつかの重要な変更があります。すなわち、トリガ用の言語セット、ストアドプロシージャ、特にEXECUTE STATEMENTの新しい拡張機能に関連した動的に実行可能な文、といったものです。また、このリリースでは自律型トランザクションの到来が告げられます。 + + + +
+ + 自律型トランザクション + + Adriano + dos Santos Fernandes + + + トラッカー・リファレンス CORE-1409 + この新たな実装により、PSQLモジュール内の自律型トランザクションでコードの一部の実行ができるようになりました。これは、例外を発生させる必要があるけれどもデータベースの変更をロールバックしたくないという状況では便利です。 + + 新しいトランザクションは、起動しているもののと同じ分離レベルで開始されます。自律型トランザクション内の文で発生した任意の例外は変更を引き起こし、ロールバッックされます。その文が終わりまで実行された場合はトランザクションはコミットされます。 + + 自律型トランザクションは起動しているものから独立しているので、この機能は、デッドロックを避けるよう注意して使う必要があります。 + + 構文パターン + +IN AUTONOMOUS TRANSACTION +DO + <単純な文 | 複合文> + + + 使用例 + +create table log ( + logdate timestamp, + msg varchar(60) +); + +create exception e_conn 'Connection rejected'; + +set term !; + +create trigger t_conn on connect +as +begin + if (current_user = 'BAD_USER') then + begin + in autonomous transaction + do + begin + insert into log (logdate, msg) values (current_timestamp, 'Connection rejected'); + end + + exception e_conn; + end +end! + +set term ;! + +
+ +
+ + PSQLの変数にデータベースのカラムの型を借用 + + Adriano + dos Santos Fernandes + + + トラッカー・リファレンス CORE-1356 + この機能はバージョン2での実装を拡張したものです。これによって、PSQLで変数を宣言するためのデータ型としてドメインが利用できるようになりました。この用途のために、テーブルまたはビューからカラム定義のデータ型を借用できるようになりました。 + + 構文パターン + + data_type ::= + <組み込みデータ型> + | <ドメイン名> + | TYPE OF <ドメイン名> + | TYPE OF COLUMN <テーブルまたはビュー>.<カラム> + + + + TYPE OF THEはカラムの型のみ取得します。カラムに定義された任意の制約またはデフォルト値は無視されます。 + + + 例 + +CREATE TABLE PERSON ( + ID INTEGER, + NAME VARCHAR(40) + ); + +CREATE PROCEDURE SP_INS_PERSON ( + ID TYPE OF COLUMN PERSON.ID, + NAME TYPE OF COLUMN PERSON.NAME + ) + AS +DECLARE VARIABLE NEW_ID TYPE OF COLUMN PERSON.ID; +BEGIN + INSERT INTO PERSON (ID, NAME) + VALUES (:ID, :NAME) + RETURNING ID INTO :NEW_ID; +END + + + + トラップに注意！ + バージョン2.5以上では、カラムのデータ型の変更が可能になっています。そのカラムがストアドプロシージャやトリガで参照されていたとしても、例外がスローされることはありません。ただし、コンパイル済みのPSQLはBLOB内でバイナリ表現（BLR）として静的に格納されているため、オリジナルのBLRはバックアップやリストアを行なっても残っています。BLRは静的であるため、データ型を変更しても更新されません。 + このことは、TYPE OF構文や、テーブルから影響を受けるカラム、また、それらのテーブルから派生した任意のビューのカラムを使って変数が宣言されている場合、コンパイル済みBLRがデータ型の変更によって破壊されてしまうことを意味します。最善の場合、BLRは注意が必要のフラグを付けられますが、テストでは、どんな条件でもフラグ付けが行なわれるわけではないことが分かっています。 + つまり、フィールドがコンパイル済みPSQLに何らかの依存関係を持っていたとしても、あなたがそのフィールドの型を変更するのをエンジンはもう止めてくれなくなった、ということです。変更された状況の管理のため、影響を受けるプロシージャやトリガを特定したり、変更に対応してそれらを再コンパイルしたりすることは、あなた自身の問題となります。 + + +
+ +
+ EXECUTE文の新たな拡張 + われわれのリリースノートでは珍しく、この章はPSQLのEXECUTE STATEMENT文の完全で新しく拡張された構文から始め、その後で、さまざまな新機能とその使い方の説明に移ります。 + + +[FOR] EXECUTE STATEMENT <query_text> [(<input_parameters>)] + [ON EXTERNAL [DATA SOURCE] <connection_string>] + [WITH {AUTONOMOUS | COMMON} TRANSACTION] + [AS USER <user_name>] + [PASSWORD <password>] + [ROLE <role_name>] + [WITH CALLER PRIVILEGES] + [INTO <variables>] + + + オプションの句の順序は固定されておらず、例えば、次のモデルに基づく文も有効となります： + + [ON EXTERNAL [DATA SOURCE] <接続文字列>] + [WITH {AUTONOMOUS | COMMON} TRANSACTION] + [AS USER <ユーザー名>] + [PASSWORD <パスワード>] + [ROLE <ロール名>] + [WITH CALLER PRIVILEGES] + + 句の重複はできません。 + + +
+ コンテキスト・イシュー + ON EXTERNAL DATA SOURCE句がない場合、EXECUTE STATEMENTは通常、CURRENT_CONNECTIONの文脈内で実行されます。AS USER句が省略されている場合、または、これがCURRENT_USERと同じ<ユーザー名>引数を持っている場合は、その通りです。 + しかし、<ユーザー名>がCURRENT_USERと異なる場合、文は、同じエンジン・インスタンス内で、Y-Valveとリモートレイヤーなしに確立された別の接続で実行されます。 + + AS USER <ユーザー名>句がない場合はCURRENT_USERがデフォルトとなります。 + + +
+ 認証 + CURRENT_CONNECTIONとは異なる接続にサーバー認証が必要な場合、例えば、外部のデータソースでEXECUTE STATEMENTコマンドを実行するには、AS USERやPASSWORD句が必要になります。しかし、いくつかの条件のもとで、PASSWORDが省略できることがあります。その効果は以下の通りです： + + + + Windowsでは、信頼された認証がアクティブとなっており、AS USERパラメータが欠けているか無効、またはCURRENT_USERと同じ場合、CURRENT_CONNECTION（つまり、外部データソースではなく）に信頼された認証が実行されます。 + + + 外部データソース・パラメータが与えられ、その<接続文字列>がCURRENT_CONNECTIONと同じデータベースを参照している場合は、有効なユーザーアカウントはCURRENT_USERのものとなります。 + + + 外部データソース・パラメータが与えられ、その<接続文字列>が、CURRENT_CONNECTIONがアタッチしているものとは異なるデータベースを参照している場合、有効なユーザーアカウントは、Firebirdプロセスが現在稼働しているOSのアカウントとなります。 + + + PASSWORD句が欠けている他の場合には、isc_dpb_user_nameだけはDPB（アタッチメントパラメータ）で与えられ、native認証が試行されます。 +
+ +
+ トランザクションの挙動 + この新しい構文はトランザクションの挙動を設定するオプションの句を含んでいます：WITH AUTONOMOUS TRANSACTIONとWITH COMMON TRANSACTIONです。デフォルトはWITH COMMON TRANSACTIONであり、特に指定する必要はありません。トランザクションの有効期間はCURRENT_TRANSACTIONの有効期間によって決まり、CURRENT_TRANSACTIONに従ってコミットまたはロールバックされます。 + WITH COMMON TRANSACTIONによる挙動は以下の通りです： + + + + 外部データソースでの任意のトランザクションを、CURRENT_TRANSACTIONと同じパラメータで開始します；あるいは、 + + + CURRENT_TRANSACTION内の文を実行します；または、 + + + CURRENT_CONNECTION内で開始される別のトランザクションを使用します。 + + + + WITH AUTONOMOUS TRANSACTION設定は、新しいトランザクションをCURRENT_TRANSACTIONと同じパラメータで開始します。文が例外を発生させずに実行されればトランザクションはコミットされ、エラーがあった場合はロールバックされます。 +
+ +
+ + アクセス権限の継承 + + Vladyslav + Khorsun + + + トラッカー・リファレンス CORE-1928 + 設計上、EXECUTE STATEMENTのもともとの実装では、実行可能なコードは実行されるストアドプロシージャまたはトリガのアクセス権限から分離され、CURRENT_USERが利用できる権限へと戻されます。この戦略は、任意の文を実行されてしまう脆弱性を低減できるため、概ね賢いものです。しかし、堅牢な環境やプライバシーが問題にならない状況では、制約と感じられることがあります。 + オプションの句WITH CALLER PRIVILEGESの導入により、実行可能な文に、実行されるストアドプロシージャやトリガのアクセス権限を継承させられるようになりました。文は呼び出し先のストアドプロシージャやトリガに適用される任意の追加権限を使用して作成されます。その効果は、文がストアドプロシージャやトリガによって直接実行された場合と同様のものです。 + + WITH CALLER PRIVILEGESオプションはON EXTERNAL DATA SOURCEオプションとは互換性がありません。 + + +
+
+ +
+ + PSQLからの外部クエリ + + Vladyslav + Khorsun + + + トラッカー・リファレンス CORE-1853 + EXECUTE STATEMENTに<接続文字列>引数を付けたON EXTERNAL DATA SOURCE句を含めることで、外部データベースに対するクエリがサポートされました。 + +
+ <接続文字列>引数 + <接続文字列>のフォーマットはごく普通のもので、API関数isc_attach_database()に渡されます。すなわち、 + + [<ホスト名><プロトコル区切り文字>]データベースのパス + +
+ +
+ キャラクタ・セット + 外部のデータソースへの接続には、CURRENT_CONNECTIONの文脈で使われているものと同じキャラクタ・セットが使われます。 +
+ +
+ アクセス権限 + 外部のデータソースが別のサーバー上にある場合、AS USER <ユーザー名>句とPASSWORD <パスワード>句が必要となります。 + 外部のデータソースが別のサーバ上にある場合、WITH CALLER PRIVILEGES句は無視されます。 + 情報が足りないよ！ロールはどうなってるの？ +
+ + + 外部接続での二相トランザクションはバージョン2.5では利用できません。 + +
+ +
+ + EXECUTE STATEMENTでの動的パラメータ + + VladyslavKhorsun + AlexPeshkov + + + トラッカー・リファレンス CORE-1221 + + 新たな拡張により、パラメータ化されたDSQL文に似た方法で、動的な入力パラメータ（プレースホルダ）を使って文を作成することができるようになりました。クエリのテキストそのものをパラメータとして渡すことも可能です。 + +
+ 構文の表記規則 + この仕組みには、実行時のパーシングを容易にし、また、DSQLパラメータを扱うポピュラーなクライアント・ラッパー層（Delphiなど）と互換性のあるスタイルでのパラメータ命名オプションを許可するいくつかの表記規則が採用されています。API自体が持つ表記規則もサポートされており、定義された順序で名前なしパラメータを渡すことができます。ただし、名前付き、名前なしパラメータを混在させることはできません。 + +
+ 新しい拘束演算子 + この点について、動的パラメータ機能の実装の中で、同等性テストでのクラッシュを避けるために、実行時の値を名前付きパラメータに拘束する新しい代入演算子を導入する必要がありました。この新しい演算子はPascalの代入演算子を真似たもの:=です。 +
+ +
+ パラメータを定義する構文 + + + <input_parameters> ::= + <named_parameter> | <input_parameters>, <named_parameter> + + <named_parameter> ::= + <parameter name> := <expression> + + 名前付き入力パラメータの例 + 例えば、次のPSQL文は<query_text>と<input_parameters>（<named_parameter>）の両方を定義します： + +EXECUTE BLOCK AS + DECLARE S VARCHAR(255); + DECLARE N INT = 100000; + BEGIN + /* 通常のPSQL文字列としての<query_text>の割り当て */ + S = 'INSERT INTO TTT VALUES (:a, :b, :a)'; + + WHILE (N > 0) DO + BEGIN + /* 各ループの実行は文字列の値と入力パラメータに + 拘束される値の両方に適用されます */ + + EXECUTE STATEMENT (:S) (a := CURRENT_TRANSACTION, b := CURRENT_CONNECTION) + WITH COMMON TRANSACTION; + N = N - 1; + END + END + + 名前なし入力パラメータの例 + 同様の文で、今度は名前なし入力パラメータを使用し、定数の引数を直接渡します。 + +EXECUTE BLOCK AS + DECLARE S VARCHAR(255); + DECLARE N INT = 100000; + BEGIN + S = 'INSERT INTO TTT VALUES (?, ?, ?)'; + + WHILE (N > 0) DO + BEGIN + EXECUTE STATEMENT (:S) (CURRENT_TRANSACTION, CURRENT_CONNECTION, CURRENT_TRANSACTION); + N = N - 1; + END + END + + + 次の点に注意して下さい。<query_text>と<input_parameters>の両方を使用する場合、必ず<query_text>を括弧で囲みます。すなわち、 + + EXECUTE STATEMENT (:sql) (p1 := 'abc', p2 := :second_param) ... + + +
+
+
+
+ 例外処理 + 例外の取り扱いは、ON EXTERNAL DATA SOURCE句が与えられているかどうかで異なります。 + +
+ ON EXTERNAL DATA SOURCE句がある場合 + ON EXTERNAL DATA SOURCE句があると、Firebirdは未知のデータソースから与えられるエラーコードを解釈することができず、エラー情報そのものを解釈し、文字列にラップして自身のエラー・ラッパー（isc_eds_connectionまたはisc_eds_statement）へと渡します。 + リモートエラーを解釈したテキストには、エラーコードと対応するメッセージの両方が含まれます。 + + + isc_eds_connectionエラーのフォーマット + +テンプレート文字列 + Execute statement error at @1 :\n@2Data source : @3 +ステータスベクター・タグ + isc_eds_connection, + isc_arg_string, <失敗したAPI関数名>, + isc_arg_string, <外部エラーを解釈したテキスト>, + isc_arg_string, <データソース名> + + + + + isc_eds_statementエラーのフォーマット + +テンプレート文字列 + Execute statement error at @1 :\n@2Statement : @3\nData source : @4 +ステータスベクター・タグ + isc_eds_statement, + isc_arg_string, <失敗したAPI関数名>, + isc_arg_string, <外部エラーを解釈したテキスト>, + isc_arg_string, <クエリ>, + isc_arg_string, <データソース名> + + + + PSQLレベルでは、これらのエラーのシンボルは、それらを他のgdscodeと同様に扱うことで処理することができます。例えば、 + + + WHEN GDSCODE eds_statement + + + 現状では、エラーコード生成元にWHEN文ではアクセスできません。この状況は将来改善されるかもしれません。 + +
+ +
+ ON EXTERNAL DATA SOURCE句がない場合 + ON EXTERNAL DATA SOURCE句がない場合は、エラーの元のステータスベクターが呼び出し元であるPSQLコードにそのまま渡されます。 + 例えば、動的な文がisc_lock_conflictの例外を引き起こした場合、例外は呼び出し元に渡され、通常のハンドラで取り扱われます： + + + WHEN GDSCODE lock_conflict + +
+
+ +
+ EXECUTE STATEMENTの使用例 + 以下の例は、EXECUTE STATEMENTの拡張をアプリケーションに適用する方法のサンプルを提供しています。 + +
+ テスト接続とトランザクション + 設定のバリエーションを比較できるように、テストを二つ挙げておきます： + +
+ テスト a）：同じトランザクションでこの文を数回実行する─現在のデータベースへの新しい接続を三つ作成し、呼び出しがあるたびにそれを再利用する。トランザクションは再利用される。 + +EXECUTE BLOCK + RETURNS (CONN INT, TRAN INT, DB VARCHAR(255)) +AS + DECLARE I INT = 0; + DECLARE N INT = 3; + DECLARE S VARCHAR(255); +BEGIN + SELECT A.MON$ATTACHMENT_NAME FROM MON$ATTACHMENTS A + WHERE A.MON$ATTACHMENT_ID = CURRENT_CONNECTION + INTO :S; + + WHILE (i < N) DO + BEGIN + DB = TRIM(CASE i - 3 * (I / 3) + WHEN 0 THEN '\\.\' WHEN 1 THEN 'localhost:' ELSE '' END) || :S; + + FOR EXECUTE STATEMENT + 'SELECT CURRENT_CONNECTION, CURRENT_TRANSACTION + FROM RDB$DATABASE' + ON EXTERNAL :DB + AS USER CURRENT_USER PASSWORD 'masterkey' -- ただの例です + WITH COMMON TRANSACTION + INTO :CONN, :TRAN + DO SUSPEND; + + i = i + 1; + END +END + +
+ +
+ テスト b）：同じトランザクションでこの文を数回実行する─呼び出しがあるたびに、現在のデータベースへの新しい接続を三つ作成する。 + +EXECUTE BLOCK + RETURNS (CONN INT, TRAN INT, DB VARCHAR(255)) +AS + DECLARE I INT = 0; + DECLARE N INT = 3; + DECLARE S VARCHAR(255); +BEGIN + SELECT A.MON$ATTACHMENT_NAME + FROM MON$ATTACHMENTS A + WHERE A.MON$ATTACHMENT_ID = CURRENT_CONNECTION + INTO :S; + + WHILE (i < N) DO + BEGIN + DB = TRIM(CASE i - 3 * (I / 3) + WHEN 0 THEN '\\.\' + WHEN 1 THEN 'localhost:' + ELSE '' END) || :S; + + FOR EXECUTE STATEMENT + 'SELECT CURRENT_CONNECTION, CURRENT_TRANSACTION FROM RDB$DATABASE' + ON EXTERNAL :DB + WITH AUTONOMOUS TRANSACTION -- 自律型トランザクションに注意 + INTO :CONN, :TRAN + DO SUSPEND; + + i = i + 1; + END +END + +
+
+ +
+ 入力の評価のデモ + 一度だけ評価される入力式のデモ： + +EXECUTE BLOCK + RETURNS (A INT, B INT, C INT) +AS +BEGIN + EXECUTE STATEMENT ( + 'SELECT CAST(:X AS INT), + CAST(:X AS INT), + CAST(:X AS INT) + FROM RDB$DATABASE') + (x := GEN_ID(G, 1)) + INTO :A, :B, :C; + + SUSPEND; +END + +
+ +
+ 書き込み速度テスト + パラメータ化していない形式のEXECUTE STATEMENTと比較するため、われわれが以前に挙げていた入力パラメータの使用例を再掲します： + +RECREATE TABLE TTT ( + TRAN INT, + CONN INT, + ID INT); + +-- 直接の書き込み： + +EXECUTE BLOCK AS + DECLARE N INT = 100000; +BEGIN + WHILE (N > 0) DO + BEGIN + INSERT INTO TTT VALUES (CURRENT_TRANSACTION, CURRENT_CONNECTION, CURRENT_TRANSACTION); + N = N - 1; + END +END + +-- プリペアされた動的な文を介した書き込み +-- 名前付き入力パラメータを使用： + +EXECUTE BLOCK AS + DECLARE S VARCHAR(255); + DECLARE N INT = 100000; +BEGIN + S = 'INSERT INTO TTT VALUES (:a, :b, :a)'; + + WHILE (N > 0) DO + BEGIN + EXECUTE STATEMENT (:S) + (a := CURRENT_TRANSACTION, b := CURRENT_CONNECTION) + WITH COMMON TRANSACTION; + N = N - 1; + END +END + +-- プリペアされた動的な文を介した書き込み +-- 名前なし入力パラメータを使用： + +EXECUTE BLOCK AS +DECLARE S VARCHAR(255); +DECLARE N INT = 100000; +BEGIN + S = 'INSERT INTO TTT VALUES (?, ?, ?)'; + + WHILE (N > 0) DO + BEGIN + EXECUTE STATEMENT (:S) (CURRENT_TRANSACTION, CURRENT_CONNECTION, CURRENT_TRANSACTION); + N = N - 1; + END +END + +
+
+
+ +
+ PSQLのその他の改善点 + 既存のPSQL構文の改善には以下のものが含まれます： +
+ + PSQL式としてのサブクエリ + A.dos Santos Fernandes + + + トラッカー・リファレンス CORE-2580 + 従来は、PSQL式として使われるサブクエリは、SQLの項としてロジカルに有効な場合でも、例外を返していました。例えば、以下の構文ではすべてエラーが返されました： + +var = (select ... from ...); +if ((select ... from ...) = 1) then +if (1 = any (select ... from ...)) then +if (1 in (select ... from ...)) then + + + このような有効と見られる式は認められるようになりました。これで、SELECT...INTOを使って何が何でもスカラサブクエリの出力を取得して中間変数に渡すといった必要はなくなりました。 +
+ + + +
+ + コンテキスト変数としてのSQLSTATE + D.Yemanov + + トラッカー・リファレンス CORE-2890 + （バージョン2.5.1）SQLSTATEがPSQLコンテキスト変数として利用可能になりました。WHEN文中の例外処理部でGDSCODEやSQLCODEと同様に使われます。 +
+
+ diff --git a/src/docs/rlsnotes-ja/rlsnotes25/PlatformPorts25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/PlatformPorts25.docbook new file mode 100644 index 00000000..27c2ec5e --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/PlatformPorts25.docbook @@ -0,0 +1,124 @@ + + + プラットフォーム・ポート + + この章の各項は、Firebirdのメインストリーム以外のプラットフォーム向けポーティングについてのものです。以前に各ポーティングに施されてきた変更・改善についてのメモも添えられています。 + +
+ HPPA + +
+ + Linux/HPPA + + D.Ivanov + A.Peshkov + + + HPPA版Linux向けFirebird 2.5.1ポーティングです。 + トラッカー・リファレンス CORE-3184 +
+ +
+ + Linux/Alpha + + D.Ivanov + A.Peshkov + + + Alpha版Linux向けFirebird 2.5.1ポーティングです。 + トラッカー・リファレンス CORE-3184 +
+
+ +
+ IBM eServer z-Series + +
+ + Linux/s390 （32-bit） + + D.Ivanov + A.Peshkov + + + + トラッカー・リファレンス CORE-2625 + Linux/s390（32bit）プラットフォーム向けポーティング。s390xアーキテクチャでビルドされています。 + このポーティング向けのパッチでは、prefix.linux_s390xから-DS390Xが削除され、gccより提供される__s390__および__s390x__定義のチェックで置き換えられています。そのため、どちらのポーティングでも同じプレフィックス・ファイルを利用できます。 + + s390にはアライメントの制限がありません。 + +
+ +
+ + Linux/s390x（64-bit） + + D.Horak + A.Peshkov + + + トラッカー・リファレンス CORE-2559 + Linux/s390x（64bit）プラットフォーム向けポーティングです。 +
+
+ +
+ + Linux/sh4（Renesas SH） + + N.Iwamatsu + D.Ivanov + A.Peshkov + + + + トラッカー・リファレンス CORE-2655 + Linux/sh4（Renesas SH）プラットフォーム向けポーティングです。 + Linux/sh4（Renesas SH）アーキテクチャにはリトルエンディアンのものとビッグエンディアンのものがあります。このポーティングはいずれもサポートしています。SHにはアライメントの制約があります。 +
+ +
+ HP-UX + +
+ + HP-UX版のロックテーブルの改善 + A.Peshkov + + + トラッカー・リファレンス CORE-2644 + + HP-UXを除くPOSIXプラットフォーム向けの全てのポーティングで、ロックテーブルは、最初にそれ用に割り当てられたスペースが使い果たされても伸張できるようになっています。HP-UXのポーティングでは、PA-RISCプラットフォームのハードウェア制限により、同一プロセス内で同一のファイル領域を異なる仮想アドレスへとリマッピングする機能がサポートされていないため、同様の動的リサイジングを実装することができません。そのため、ISC_remap_fileは機能せず、ロックテーブルは伸張できませんでした。 + SAS社のチームは、プロジェクトVulcanのSAS版向けコードで、このプラットフォームでのロックテーブルの伸張を可能とするソリューションを開発しました。このソリューションはHP-UX向けFirebird 2.5ポーティングにインポートされています。 +
+
+ +
+ + Windows 32bitプラットフォーム向けポーティング + N. Samofatovのリクエストによる + + + トラッカー・リファレンス CORE-2609 + 通知されていたように、Firebirdバージョン2.1.x以上ではMicrosoft Windows 98、ME、NT4はサポートされません。しかし、Red Soft社は今後もWin98/MEや、ロシア政府各部局でいまだに使われ続けメンテナンスされているNT4といったバージョンのサポートを行うとしており、別々のユニットに切り分けて再実装されたコンパイラコンディションのインクルージョンのパーミッションをリクエストし、これらの古い、あるいは年季の入ったWindowsプラットフォーム向けFirebird 2.5のポートをビルドができるようにしました。 + + これらのポートはFirebird 2.5のメインストリーム向け配布版には含まれていません！ + + + Firebirdプロジェクトで配布されているWindowsバイナリにはこのサポートを含まれません。 + + + これらのどのポートもプロジェクトのQAテストを受けていません。 + + + これらのポートに関するQAテスト、将来のメンテナンスや開発、またバグフィックスは、使用者の責任となります。 + + + + +
+ + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/ReservedWords25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/ReservedWords25.docbook new file mode 100644 index 00000000..90aa54d1 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/ReservedWords25.docbook @@ -0,0 +1,51 @@ + + + 予約語とその変更 + + + アスタリスク（*）は、Firebirdの文法によって予約されたキーワードまたはそれ以外にキーワードとして認識されるもののうち、標準SQLでは予約語となっていないものを示しています。 + + +
+ + 予約語の刷新 + A.Peshkov + + + トラッカー・リファレンス CORE-2638 + Firebird独自の予約語の数はかなり減りました。これで、他のデータベースからFirebirdに移行する際にキーワードの競合で苦労することが少なくなるはずです。SQL標準で予約語となっていないものは、可能な限り、Firebirdの文法でも予約語ではなくなりました。 + まだ少数、SQL標準の予約語でないものがFirebirdの予約語として残されています。次のリストの通り： + + + ADD * DB_KEY * GDSCODE * INDEX * + LONG * PLAN * POST_EVENT * RETURNING_VALUES * + SQLCODE * VARIABLE * VIEW * + + + + 他の非標準のキーワードで、以前に予約語だったものは全て、任意の目的で利用できるようになりました。 +
+ +
+ 新しい予約語 + + + SIMILAR SQLSTATE + +
+ +
+ 非予約語として追加されたキーワード + + AUTONOMOUS * BIN_NOT * CALLER * + CHAR_TO_UUID * COMMON * DATA + FIRSTNAME * GRANTED LASTNAME * + MIDDLENAME * MAPPING * OS_NAME * + SOURCE * TWO_PHASE * UUID_TO_CHAR * + + +
+ + + + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/SQLStates.docbook b/src/docs/rlsnotes-ja/rlsnotes25/SQLStates.docbook new file mode 100644 index 00000000..2adf4b94 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/SQLStates.docbook @@ -0,0 +1,1099 @@ + + SQLSTATE +
+ SQLSTATEコードとメッセージ + この付録では、現在サポートされている全SQLSTATEコードを網羅しています： + + + SQL CLASS（2文字）とSQL SUBCLASS（3文字）からなる状態配列として返される5文字のSQLSTATEコードです。 + + + 対応するものが知られている場合は、非推奨のSQLCODEへの一対一のマッピングが含まれます。 + + + 多くの場合、SQLCODE対SQLSTATEのマッピングは一対一ではありませんが、これはSQL標準委員会が意図した通りです。SQLCODEの使用を完全に非推奨とすることが長年にわたる彼らの目標でした。 + + + + + + + + + + + + SQLSTATEコード + マッピングされたメッセージ + SQLCODEへのマッピング + + + + + + + SQLCLASS 00 成功（Success） +   + + + + 00000 + 成功（Success） + + + + + SQLCLASS 01 警告（Warning） +   + + + + 01000 + 一般的警告（General Warning） + + + + 01001 + カーソル操作の競合（Cursor operation conflict） + + + + 01002 + 接続切断エラー（Disconnect error） + + + + 01003 + NULL値がset関数から除外されました（NULL value eliminated in set function） + + + + 01004 + 文字列データの右端が切り捨てられました（String data, right-truncated） + + + + 01005 + アイテム記述子エリアが不足しています（Insufficient item descriptor areas） + + + + 01006 + 権限を削除できません（Privilege not revoked） + + + + 01007 + 権限を付与できません（Privilege not granted） + + + + 01008 + 暗黙のゼロbitパディング（Implicit zero-bit padding） + + + + 01100 + SQL文がunpreparedにリセットされました（Statement reset to unprepared） + + + + 01101 + 実行中のトランザクションがコミットされました（Ongoing transaction has been committed） + + + + 01102 + 実行中のトランザクションがロールバックされました（Ongoing transaction has been rolled back） + + + + SQLCLASS 02 データがありません（No Data） +   + + + 02000 + データが見つかりません、または、影響を受ける行がありません（No data found or no rows affected） + + + + SQLCLASS 07 動的SQLエラー（Dynamic SQL error） +   + + + 07000 + 動的SQLエラー（Dynamic SQL error） + + + + 07001 + 入力パラメータの数が正しくありません（Wrong number of input parameters） + + + + 07002 + 出力パラメータの数が正しくありません（Wrong number of output parameters） + + + + 07003 + カーソル指定を実行できません（Cursor specification cannot be executed） + + + + 07004 + 動的パラメータにUSING句が必要です（USING clause required for dynamic parameters） + + + + 07005 + プリペアされたSQL文がカーソル指定のものではありません（Prepared statement not a cursor-specification） + + + + 07006 + 制限付データ型の属性違反（Restricted data type attribute violation） + + + + 07007 + 結果フィールドにUSING句が必要です（USING clause required for result fields） + + + + 07008 + 無効な記述子カウント（Invalid descriptor count） + + + + 07009 + 無効な記述子インデックス（Invalid descriptor index） + + + + SQLCLASS 08 接続の例外（Connection Exception） +   + + + 08001 + クライアントが接続を確立できません（Client unable to establish connection） + + + + 08002 + 接続名が使用中です（Connection name in use） + + + + 08003 + 接続が存在しません（Connection does not exist） + + + + 08004 + サーバーが接続をリジェクトしました（Server rejected the connection） + + + + 08006 + 接続に失敗しました（Connection failure） + + + + 08007 + トランザクションの解決が不明です（Transaction resolution unknown） + + + + SQLCLASS 0A 非サポート機能（Feature Not Supported） +   + + + 0A000 + 機能がサポートされていません（Feature Not Supported） + + + + SQLCLASS 0B 無効なトランザクション初期化（Invalid Transaction Initiation） +   + + + 0B000 + 無効なトランザクションの初期化（Invalid transaction initiation） + + + + SQLCLASS 0L 無効な権限付与者（Invalid Grantor） +   + + + 0L000 + 無効な権限付与者（Invalid grantor） + + + + SQLCLASS 0P 無効なロール指定（Invalid Role Specification） +   + + + 0P000 + 無効なロール指定（Invalid role specification） + + + + SQLCLASS 0U 更新不可のカラムへの割り当て試行（Attempt to Assign to Non-Updatable Column） +   + + + 0U000 + 更新できないカラムへ割り当てを行おうとしています（Attempt to assign to non-updatable column） + + + + SQLCLASS 0V オーダリングカラムへの割り当て試行（Attempt to Assign to Ordering Column） +   + + + 0V000 + オーダリングカラムへ割り当てを行おうとしています（Attempt to assign to Ordering column） + + + + SQLCLASS 20 case文でcaseが見つからない（Case Not Found For Case Statement） +   + + + 20000 + case文でcaseが見つかりません（Case not found for case statement） + + + + SQLCLASS 21 濃度違反（Cardinality Violation） +   + + + 21000 + 濃度違反（Cardinality violation） + + + + 21S01 + 挿入値リストがカラムリストにマッチしません（Insert value list does not match column list） + + + + 21S02 + 派生テーブルの次数がカラムリストにマッチしません（Degree of derived table does not match column list） + + + + SQLCLASS 22 データの例外（Data Exception） +   + + + 22000 + データの例外（Data exception） + + + + 22001 + 文字列データの右側が切り捨てられました（String data, right truncation） + + + + 22002 + NULL値またはインジケータパラメータがありません（Null value, no indicator parameter） + + + + 22003 + 数値が範囲内にありません（Numeric value out of range） + + + + 22004 + NULL値は許可されていません（Null value not allowed） + + + + 2205 + 割り当てエラー（Error in assignment） + + + + 2206 + フィールド参照にNULL値があります（Null value in field reference） + + + + 2207 + 無効なデータ日時フォーマット（Invalid datetime format） + + + + 22008 + 日時フィールドのオーバーフロー（Datetime field overflow） + + + + 22009 + 無効なタイムゾーンのディスプレースメント値（Invalid time zone displacement value） + + + + 2200A + 参照先がNULL値です（Null value in reference target） + + + + 2200B + エスケープキャラクタの競合（Escape character conflict） + + + + 2200C + エスケープキャラクタ使用が無効です（Invalid use of escape character） + + + + 2200D + 無効なエスケープoctet（Invalid escape octet） + + + + 2200E + 配列ターゲットにNULL値があります（Null value in array target） + + + + 2200F + ゼロ長のキャラクタ文字列（Zero-length character string） + + + + 2200G + 明確な型の不一致（Most specific type mismatch） + + + + 22010 + 無効なインジケータパラメータ値（Invalid indicator parameter value） + + + + 22011 + 部分文字列エラー（Substring error） + + + + 22012 + ゼロ除算（Division by zero） + + + + 22014 + 無効な更新値（Invalid update value） + + + + 22015 + インターバルフィールドのオーバーフロー（Interval field overflow） + + + + 22018 + castのキャラクタ値が無効です（Invalid character value for cast） + + + + 22019 + 無効なエスケープキャラクタ（Invalid escape character） + + + + 2201B + 無効な正規表現（Invalid regular expression） + + + + 2201C + テーブルでNULL行は許可されていません（Null row not permitted in table） + + + + 22020 + 無効な制限値（Invalid limit value） + + + + 22021 + キャラクタがレパートリにありません（Character not in repertoire） + + + + 22022 + インジケータのオーバーフロー（Indicator overflow） + + + + 22023 + 無効なパラメータ値（Invalid parameter value） + + + + 22024 + キャラクタ文字列が適切に終了していません（Character string not properly terminated） + + + + 22025 + 無効なエスケープシークケンス（Invalid escape sequence） + + + + 22026 + 文字列データ、長さの不一致（String data, length mismatch） + + + + 22027 + 切り捨てエラー（Trim error） + + + + 22028 + 行がすでに存在しています（Row already exists） + + + + 2202D + mutator関数にNULLインスタンスがあります（Null instance used in mutator function） + + + + 2202E + 配列要素エラー（Array element error） + + + + 2202F + 配列データ、右端切り捨て（Array data, right truncation） + + + + SQLCLASS 23 整合性制約違反（Integrity Constraint Violation） +   + + + 23000 + 整合性制約違反（Integrity constraint violation） + + + + SQLCLASS 24 無効なカーソル状態（Invalid Cursor State） +   + + + 24000 + 無効なカーソル状態（Invalid cursor state） + + + + 24504 + UPDATE、DELETE、SET、またはGET文で指定されたカーソルが行に配置されていません（The cursor identified in the UPDATE, DELETE, SET, or GET statement is not positioned on a row） + + + + SQLCLASS 25 無効なトランザクション状態（Invalid Transaction State） +   + + + 25000 + 無効なトランザクション状態（Invalid transaction state） + + + + 25 + xxxx + + + + 25S01 + トランザクション状態（Transaction state） + + + + 25S02 + トランザクションがまだアクティブです（Transaction is still active） + + + + 25S03 + トランザクションがロールバックされています（Transaction is rolled back） + + + + SQLCLASS 26 無効なSQL文名（Invalid SQL Statement Name） +   + + + 26000 + 無効なSQL文名（Invalid SQL statement name） + + + + SQLCLASS 27 トリガデータの変更違反（Triggered Data Change Violation） +   + + + 27000 + トリガデータの変更違反（Triggered data change violation） + + + + SQLCLASS 28 無効な認証指定（Invalid Authorization Specification） +   + + + 28000 + 無効な認証指定（Invalid authorization specification） + + + + SQLCLASS 2B まだ存在する依存検眼記述子（Dependent Privilege Descriptors Still Exist） +   + + + 2B000 + 依存権限記述子がまだ存在します（Dependent privilege descriptors still exist） + + + + SQLCLASS 2C 無効なキャラクタ・セット名（Invalid Character Set Name） +   + + + 2C000 + 無効なキャラクタ・セット名（Invalid character set name） + + + + SQLCLASS 2D 無効なトランザクション終了（Invalid Transaction Termination） +   + + + 2D000 + 無効なトランザクション終了（Invalid transaction termination） + + + + SQLCLASS 2E 無効な接続名（Invalid Connection Name） +   + + + 2E000 + 無効な接続名（Invalid connection name） + + + + SQLCLASS 2F SQLルーチンの例外（SQL Routine Exception） +   + + + 2F000 + SQLルーチンの例外（SQL routine exception） + + + + 2F002 + SQLデータの修正は許可されていません（Modifying SQL-data not permitted） + + + + 2F003 + SQL文の試行は禁止されています（Prohibited SQL-statement attempted） + + + + 2F004 + SQLデータの読み込みが許可されていません（Reading SQL-data not permitted） + + + + 2F005 + 関数がreturn文を実行しません（Function executed no return statement） + + + + SQLCLASS 33 無効なSQL記述子名（Invalid SQL Descriptor Name） +   + + + 33000 + 無効なSQL記述子名（Invalid SQL descriptor name） + + + + SQLCLASS 34 無効なカーソル名（Invalid Cursor Name） +   + + + 34000 + 無効なカーソル名（Invalid cursor name） + + + + SQLCLASS 35 無効な条件番号（Invalid Condition Number） +   + + + 35000 + 無効な条件番号（Invalid condition number） + + + + SQLCLASS 36 カーソル感度の例外（Cursor Sensitivity Exception） +   + + + 36001 + リクエストがリジェクトされました（Request rejected） + + + + 36002 + リクエストに失敗しました（Request failed） + + + + SQLCLASS 37 無効な識別子（Invalid Identifier） +   + + + 37000 + 無効な識別子（Invalid identifier） + + + + 37001 + 識別子が長すぎます（Identifier too long） + + + + SQLCLASS 38 外部ルーチンの例外（External Routine Exception） +   + + + 38000 + 外部ルーチンの例外（External routine exception） + + + + SQLCLASS 39 外部ルーチン呼び出しの例外（External Routine Invocation Exception） +   + + + 39000 + 外部ルーチン呼び出しの例外（External routine invocation exception） + + + + SQLCLASS 3B 無効なセーブポイント（Invalid Save Point） +   + + + 3B000 + 無効なセーブポイント（Invalid save point） + + + + SQLCLASS 3C あいまいなカーソル名（Ambiguous Cursor Name） +   + + + 3C000 + カーソル名があいまいです（Ambiguous cursor name） + + + + SQLCLASS 3D 無効なカタログ名（Invalid Catalog Name） +   + + + 3D000 + 無効なカタログ名（Invalid catalog name） + + + + 3D001 + カタログ名が見つかりません（Catalog name not found） + + + + SQLCLASS 3F 無効なスキーマ名（Invalid Schema Name） +   + + + 3F000 + 無効なスキーマ名（Invalid schema name） + + + + SQLCLASS 40 トランザクションロールバック（Transaction Rollback） +   + + + 40000 + 実行中のトランザクションがロールバックされました（Ongoing transaction has been rolled back） + + + + 40001 + シリアライズの失敗（Serialization failure） + + + + 40002 + トランザクション整合性制約違反（Transaction integrity constraint violation） + + + + 40003 + SQL文の完了が不明です（Statement completion unknown） + + + + SQLCLASS 42 構文エラーまたはアクセス違反（Syntax Error or Access Violation） +   + + + 42000 + 構文エラーまたはアクセス違反（Syntax error or access violation） + + + + 42702 + カラム参照があいまいです（Ambiguous column reference） + + + + 42725 + 関数参照があいまいです（Ambiguous function reference） + + + + 42818 + 演算子または関数のオペランドに互換性がありません（The operands of an operator or function are not compatible） + + + + 42S01 + ベースのテーブルまたはビューがすでに存在しています（Base table or view already exists） + + + + 42S02 + ベースのテーブルまたはビューが見つかりません（Base table or view not found） + + + + 42S11 + インデックスがすでに存在しています（Index already exists） + + + + 42S12 + インデックスが見つかりません（Index not found） + + + + 42S21 + カラムがすでに存在しています（Column already exists） + + + + 42S22 + カラムが見つかりません（Column not found） + + + + SQLCLASS 44 WITH CHECKオプション違反（With Check Option Violation） +   + + + 44000 + WITH CHECKオプション違反（WITH CHECK OPTION Violation） + + + + SQLCLASS 45 処理されないユーザー定義の例外（Unhandled User-defined Exception） +   + + + 45000 + ユーザー定義の例外が処理されません（Unhandled user-defined exception） + + + + SQLCLASS 54 プログラム制限の超過（Program Limit Exceeded） +   + + + 54000 + プログラム制限を超過しています（Program limit exceeded） + + + + 54001 + SQL文が複雑すぎます（Statement too complex） + + + + 54011 + カラムが多すぎます（Too many columns） + + + + 54023 + 引数が多すぎます（Too many arguments） + + + + SQLCLASS HY CLI固有の状態（CLI-specific Condition） +   + + + HY000 + CLI固有の状態です（CLI-specific condition） + + + + HY001 + メモリ割り当てエラー（Memory allocation error） + + + + HY003 + アプリケーション記述子に無効なデータ型があります（Invalid data type in application descriptor） + + + + HY004 + 無効なデータ型（Invalid data type） + + + + HY007 + 関連するSQL文がプリペアされていません（Associated statement is not prepared） + + + + HY008 + 操作がキャンセルされました（Operation canceled） + + + + HY009 + NULLポインタの使用が無効です（Invalid use of null pointer） + + + + HY010 + 関数シーケンスエラー（Function sequence error） + + + + HY011 + 現在、属性の設定はできません（Attribute cannot be set now） + + + + HY012 + 無効なトランザクション操作コード（Invalid transaction operation code） + + + + HY013 + メモリ管理エラー（Memory management error） + + + + HY014 + ハンドル数の制限を超過しています（Limit on the number of handles exceeded） + + + + HY015 + 利用可能なカーソル名がありません（No cursor name available） + + + + HY016 + 実装行記述子を修正できません（Cannot modify an implementation row descriptor） + + + + HY017 + 自動で割り当てられた記述子ハンドルの使用が無効です（Invalid use of an automatically allocated descriptor handle） + + + + HY018 + サーバーがキャンセルのリクエストを拒否しました（Server declined the cancellation request） + + + + HY019 + 文字列以外のデータは分割して送信できません（Non-string data cannot be sent in pieces） + + + + HY020 + NULL値を連結しようとしています（Attempt to concatenate a null value） + + + + HY021 + 記述子の情報が矛盾しています（Inconsistent descriptor information） + + + + HY024 + 無効な属性値（Invalid attribute value） + + + + HY055 + 文字列以外のデータは文字列ルーチンで使えません（Non-string data cannot be used with string routine） + + + + HY090 + 無効な文字列長またはバッファ長（Invalid string length or buffer length） + + + + HY091 + 無効な記述子フィールド識別子（Invalid descriptor field identifier） + + + + HY092 + 無効な属性識別子（Invalid attribute identifier） + + + + HY095 + 無効な関数ID指定（Invalid FunctionId specified） + + + + HY096 + 無効な情報型（Invalid information type） + + + + HY097 + カラム型が範囲内にありません（Column type out of range） + + + + HY098 + スコープが範囲内にありません（Scope out of range） + + + + HY099 + nullable型が範囲内にありません（Nullable type out of range） + + + + HY100 + 一意性オプション型が範囲内にありません（Uniqueness option type out of range） + + + + HY101 + accuracyオプション型が範囲内にありません（Accuracy option type out of range） + + + + HY103 + 無効な検索コード（Invalid retrieval code） + + + + HY104 + 無効なLengthPrecision値（Invalid LengthPrecision value） + + + + HY105 + 無効なパラメータ型（Invalid parameter type） + + + + HY106 + 無効な取得操作（Invalid fetch orientation） + + + + HY107 + 行の値が範囲内にありません（Row value out of range） + + + + HY109 + 無効なカーソル配置（Invalid cursor position） + + + + HY110 + 無効なドライバ完了（Invalid driver completion） + + + + HY111 + 無効なブックマーク値（Invalid bookmark value） + + + + HYC00 + オプション機能が実装されていません（Optional feature not implemented） + + + + HYT00 + タイムアウトしました（Timeout expired） + + + + HYT01 + 接続がタイムアウトしました（Connection timeout expired） + + + + SQLCLASS XX 内部エラー（Internal Error） +   + + + XX000 + 内部エラー（Internal error） + + + + XX001 + データが破損しています（Data corrupted） + + + + XX002 + インデックスが破損しています（Index corrupted） + + + + + + +
+ diff --git a/src/docs/rlsnotes-ja/rlsnotes25/Security25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/Security25.docbook new file mode 100644 index 00000000..865102fd --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/Security25.docbook @@ -0,0 +1,23 @@ + + + セキュリティの強化 + + + +
+ Windowsプラットフォーム + + +
+ SYSDBAを自動マッピングしない（Windows） + バージョン2.1では、Windowsの管理者グループのメンバーは、デフォルトでSYSDBAにマッピングされていました。バージョン2.5以降では、SYSDBAの自動マッピングは次の新たなSQLコマンドを使うことでデータベースごとに制御されます。 + ALTER ROLE RDB$ADMIN SET/DROP AUTO ADMIN MAPPING + + + ロールRDB$ADMINの全容については、管理機能の章の新しいシステムロールRDB$ADMINの項を参照して下さい。 + + +
+ +
+ diff --git a/src/docs/rlsnotes-ja/rlsnotes25/Utilities25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/Utilities25.docbook new file mode 100644 index 00000000..f869998d --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/Utilities25.docbook @@ -0,0 +1,410 @@ + + + コマンドライン・ユーティリティ + + + + 以前のクライアントとの非互換性 + 統計ルーチンを64bitサーバーで正しく動作させる新たなストラクチャーで、32bitツールが正しく動作できるようにするため、いくつかの新しい内部API関数（struct perf64とperf64_xxx）を導入し、それらを使用するisqlとqliを変更する必要がありました。このことは、バージョン2.5のisqlとqliのプログラムが以前のFirebirdクライアントと互換性がないことを意味します。 + 詳細は、エンジンの章のデータベースの統計が64bit値で適切に動作するようにの項を参照して下さい。 + + +
+ + fbtracemgr + + VladKhorsun + + + トラッカー・リファレンス CORE-2524 + これは新たなトレース機能のインターフェースとなる新しいCLIユーティリティです。使用法は以下の通り─ + + fbtracemgr <アクション> [<パラメータ>] + + +
+ アクションスイッチ + + -STA[RT] トレースのセッションを開始 + -STO[P] トレースのセッションを停止 + -SU[SPEND] トレースのセッションを中断 + -R[ESUME] トレースのセッションを再開 + -L[IST] トレースのセッションの一覧 + +
+ +
+ パラメータ + アクションパラメータ + + -N[AME] <文字列> セッション名 + -I[D] <番号> セッションID + -C[ONFIG] <文字列> 設定ファイル名 + + + 接続パラメータ + + -SE[RVICE] <文字列> サービス名 + -U[SER] <string> ユーザー名 + -P[ASSWORD] <文字列> パスワード + -FE[TCH] <文字列> ファイルからパスワードを取得 + -T[RUSTED] <文字列> フォース・トラステッド認証 + +
+ +
+ fbtracemgrの使用例 + + fbtracemgr -SE remote_host:service_mgr -USER SYSDBA -PASS masterkey -LIST + fbtracemgr -SE service_mgr -START -NAME my_trace -CONFIG my_cfg.txt + fbtracemgr -SE service_mgr -SUSPEND -ID 2 + fbtracemgr -SE service_mgr -RESUME -ID 2 + fbtracemgr -SE service_mgr -STOP -ID 4 + +
+ + + 注意 + + + 全てのスイッチ識別子とパラメータ識別子は大文字小文字を区別しません。 + + + 対話型トレースセッションを停止するには、プラットフォームに関わらず、Ctrl-Cを押して下さい。 + + + + +
+ バージョン2.5.1での改善点 + 内部トレース・エラーの診断が改善されました（トラッカー・リファレンス CORE-3413）。 + 出力が定期的に書き込まれるようになりました（トラッカー・リファレンス CORE-3324）。 + +
+ +
+ +
+ + ファイル、プロンプトからのパスワード取得 + + AlexPeshkov + + + -passwordパラメータを取る任意のコマンドライン・ユーティリティには、パスワード盗聴に対する脆弱性があります。バージョン2.1以降、POSIXプラットフォームのプロセスリストで平文で示されていた引数 [PASSWORD] はアスタリスク（ * ）で表示されるよう改善されました。 + 認証のないユーザーからパスワードを秘匿する第二段階として、このリリースでは、パスワードをファイルまたは（POSIXでは）STDINから取得できるようになりました。 + +
+ 新しい -fetch_passwordスイッチ + Firebird 2.5では、認証用のパスワードを取得する全てのコマンドライン・ユーティリティ向けに、オプションで-pa[ssword]と置き換え可能な-fet[ch_password]スイッチが新たに導入されました。このスイッチは一定のルールに従って右側から短縮して使用できます。 + + 注意して下さい + + + qliユーティリティはこのルールの例外で、有効なスイッチは-Fだけです。 + + + この新しいスイッチをgsecユーティリティの-pwスイッチの代わりに使うことはできません。 + + + +
+ -fetch_passwordの使い方 + このスイッチは一つのパラメータを要求します。これはパスワードを含むファイルのファイルパスで、クオテーションのない文字列で表します。その呼び出しがスーパーユーザー／管理者の権限を持つシステムユーザーからのものでない場合、それは呼び出しを行うシステムユーザーがアクセスできる配置場所でなければなりません。 + + 例えば、 + + isql -user sysdba -fet passfile server:employee + + このコマンドは、現在の作業ディレクトリ内にあるpassfileという名前のファイルから一行目を抽出し、呼び出しの引数 [PASSWORD] としてロードします。 + + filenameをstdinとして指定することができます： + + isql -user sysdba -fet stdin server:employee + + stdinがターミナルの場合は、次のようなプロンプトが現れます— + + Enter password: + + —このように、オペレータにパスワード入力を求めます。 + + + POSIX版では、次のように指定した場合も、プロンプトが現れます。 + + -fetch /dev/tty + + このテクニックは、例えば、stdin（全てを一行で書く場合）からリストアする必要がある場合に役立つでしょう。 + + bunzip2 -c emp.fbk.bz2 | gbak -c stdin /db/new.fdb + -user sysdba -fetch /dev/tty + + +
+
+
+ +
+ gsec + gsecに施された改善は以下の通りです： +
+ + WindowsのAdministrators用マッピング・スイッチ + + AlexPeshkov + + + バージョン2.1以来、Windowsドメイン管理者はユーザー管理機能へのフルアクセスが許可されていました。バージョン2.5では、SYDBAがセキュリティ・データベースをそのように設定しない限り、これらの権限は自動では付与されません。 + + 管理機能の章には、新しいシステムロールRDB$ADMINについての詳しい解説があります。そこに、SYSDBAがWindowsのAdministratorsをデータベースのロールRDB$ADMINに自動マッピングする機能の有効・無効の切り替えに用いる新しいALTER ROLE構文についての説明があります。これには、セキュリティ・データベースでのユーザーの作成・変更・削除も含まれます。 + + 自動マッピングはgsecコマンドライン呼び出しで新しい-mappingスイッチを使っても実現できます。 + +
+ OS管理者をロールRDB$ADMINへマッピングする + 新しい-mappingスイッチは、OSのユーザーとセキュリティ・データベースのロールRDB$ADMINとの関連付けを有効・無効にするために使用します。これは引数を一つ取ります：setで関連付けは有効に、dropで無効になります。構文は次の通り： + + -mapping {set | drop} + +
+ +
+ ロールRDB$ADMINをFirebirdユーザーに付与する + + システムロールRDB$ADMINの導入により、通常のユーザーの権限昇格を行なえるようになりました。しかし、SYSDBAも含めてどのユーザーも、どのユーザーに対しても、セキュリティ・データベースに直接アタッチして他のユーザーを管理するユーザーに必要なパーミッションを付与することはできませんでした（今もできません）。新しいCREATE USERとALTER USER分の構文に含まれるパラメータ—GRANT ADMIN ROLE—は、セキュリティ・データベースですでにロールRDB$ADMINを手にしているSYSDBAや他のユーザーが、ロールRDB$ADMINを通常のユーザーに、言わば手の届く範囲で、適用することを可能にしています。 + + 同じことは、gsecで新しい-adminスイッチを使うことで実現できます。これは引数を一つ取ります：YES（security2.fdbで指定のユーザーにロールRDB$ADMINを付与）またはNO（削除）です。構文は次の通り： + + -admin {YES | NO} + +
+
+ +
+ + gsecのコマンドライン・ヘルプ + + ClaudioValderrama + + + トラッカー・リファレンス CORE-756 + gsecにはパラメータ・ヘルプ機能が実装されています。-helpまたは-?スイッチを使ってアクセスできます。 +
+
+ +
+ fbsvcmgr + システムロールRDB$ADMINに関連してgsecとサービスパラメータブロック（SPB）に追加された機能は、fbsvcmgrユーティリティを用いた適切なサポートによってカバーされます。 + + + gsec -mappingに対しては、二つの新しいタグアイテムがあります：isc_action_svc_set_mappingとisc_action_svc_drop_mappingです。 + + + gsec -adminに対しては：spb_longの新しいパラメータisc_spb_sec_admin。この値は0（REVOKE ADMIN ROLEを意味する）またはゼロ以外（GRANT ADMIN ROLEを意味する）となります。 + + + ロールRDB$ADMINの全容については、管理機能の章の新しいシステムロールRDB$ADMINの項を参照して下さい。 +
+ + +
+ gbak + +
+ + 不正な形式の文字列の修正 + + Adriano + dos Santos Fernandes + + + トラッカー・リファレンス CORE-1831 + gbakユーティリティに、不正な形式のUNICODE_FSSキャラクタを含むデータやメタデータをそれぞれ修正するための新しいリストア・スイッチが二つ追加されました。影響を受けたデータベースをバックアップからリストアする際に使用します。 + + Switch Syntax + + -FIX_FSS_D(ATA) <charset> -- 不正な形式のUNICODE_FSSデータを修正 + -FIX_FSS_M(ETADATA) <charset> -- 不正な形式のUNICODE_FSSメタデータを修正 + + + リストアのヒントと不正な形式の文字列の例外 + （CORE-2754、A. dos Santos Fernandes） + 不正な形式の文字列のためリストアに失敗した場合、gbakは詳細表示出力でヒントを出し、ユーザーに-FIX_FSS_METADATAと-FIX_FSS_DATAスイッチの使用を促します。 + +
+ +
+ + Adrianodos Santos Fernandes + キャラクタ・セットのデフォルトのコレーションを保存する + + システムテーブルRDB$CHARACTER_SETS内のRDB$DEFAULT_COLLATE_NAMEの現在の値がバックアップ／リストアのサイクルの中で維持されるよう改善されました。 + トラッカー・リファレンス CORE-789 +
+ +
+ + Adrianodos Santos Fernandes + リストア時の書き込みパフォーマンスの改善 + + （バージョン2.5.1）リストアのレコード書き込み段階でのパフォーマンスが改善されました。 + トラッカー・リファレンス CORE-3433 +
+ +
+ + + +
+ nBackup +
+ 新たなスイッチの追加 + NBackupに四つのスイッチが追加されました： + + -FE <ファイル名> ファイルからパスワードを取得 + -Z バージョン情報の表示 + -? ヘルプ + -D ON|OFF ダイレクトI/Oの強制的なon/off + + + + + -FE :: 認証パスワードをファイルから取得する機能をサポートします。詳細は、この章の新しい-fetch_passwordスイッチを参照して下さい。 + + + -Z :: 実行可能なnbackupの詳細なバージョン情報を表示します。 + + + -? :: スイッチとオプションの使い方を簡単なリストで表示します。 + + + -D :: オプションONで、ダイレクトI/O操作が有効になります；OFFで無効になります。デフォルトの設定は、以下の通り、OSとFirebirdのバージョンによって異なります： + + + Windowsサービス対応プラットフォーム + + 全てのバージョンでONとなります。 + + + + POSIX + + バージョン2.0〜2.0.5、2.1〜2.1.2、2.1.4、2.5以降ではOFF + O_DIRECTを利用できる場合、2.1.3、2.0.6ではONとなります；それ以外の場合はOFFとなります。利用可能な場合は、POSIX_FADV_NOREUSEも設定されます。 + + O_DIRECTもPOSIX_FADV_NOREUSEも利用できない場合、エラーや警告は出ませんが、-D ONは何の効果も持ちません。 + + + + + + 新しい-Dスイッチのサポートは、このバージョンでのサービスAPIの変更の中にも含まれています。詳細は、Firebird APIとODSの変更の章のisc_spb_nbk_direct on|offを参照して下さい。 + + + +
+ +
+ POSIX版でのI/Oリソース負荷の低減 + POSIX版で、増分バックアップユーティリティnBackupのフルバックアップツールが大きなデータベースのバックアップの際にI/Oリソースを占有し、生産的な作業が停止してしまうという問題に対処するための改善が施されました。nBackupは、ディスクからの読み込みを行う前に、OSのキャッシュからの読み込みを試みるようになりました。これにより、I/O負荷はかなり低減されました。 + + その対価として、高負荷状況下では、フルバックアップ完了までにかかる時間が10〜15％増加することがあります。 + + トラッカー・リファレンス CORE-2316 +
+
+ +
+ isql + 対話型クエリツールisqlにいくつかの変更が施されました。 + +
+ + SQLCODEに代わるSQLSTATE + + ClaudioValderrama + + + isqlはエラーの診断用に、非推奨になったSQLCODEに代わり、SQLSTATEコードを返すようになりました。詳細は、Firebird APIとODSの変更の章のSQLSTATEコードのサポートの項を参照して下さい。 +
+ +
+ + 数値の指数表示の改善 + + ClaudioValderrama + + + トラッカー・リファレンス CORE-1171 + isqlは、Windows版とPOSIX版とで常に異なる数値フォーマットで出力していました。POSIX版では二桁の指数部を持ちますが、MicrosoftやIntelのコンパイラのデフォルトの挙動では、指数部はゼロパディングにより何であれ三桁となります。例えば、 + + select cast ('-2.488355210669293e+39' as double precision) + from rdb$database; + + + + POSIXでは、結果は -2.488355210669293e+39 です。 + + + + Windowsでは、結果は -2.488355210669293e+039 でした。 + + + Windows版での出力を他のプラットフォームのものに合わせるようにisqlの出力は修正されました。 +
+ +
+ SHOW COLLATIONSのヘルプを追加 + isqlのコマンドライン・ヘルプにSHOW COLLATIONS用のヘルプが追加されました。（トラッカー・リファレンス CORE-2432、A. dos Santos Fernandes）。 +
+ + +
+ + SET ROWCOUNT文の追加 + + MarkO'Donohue + + + このコマンドは、主にテスターの支援のために追加されたもので、クエリが対話型isqlシェルに返す行数に制限をかけることができます。 + 使用例 + 次のisql文は、出力の10,000行目で．以降の行を返すのを止めます： + + SQL>set rowcount 10000; + +
+ +
+ +
+ gpre（プリコンパイラ） + +
+ + 若干のアップデート + + StephenBoyd + Adrianodos Santos Fernandes + + + トラッカー・リファレンス CORE-1527 + GPREが、コンテキスト変数CURRENT_*の完全なセットに加えて、IS NOT DISTINCT句とCASE/NULLIF/COALESCE/SUBSTRING関数をサポートするようになりました。 +
+ + 非推奨の機能がユーティリティに将来及ぼす影響 + Firebird 3コードベースから組み込み関数Risc_ddlが削除されることを見越して、現在gdefとgpreツールで利用できるいくつかの機能が非推奨になりました—そのため、バージョン2.5では動作するかもしれませんが、Firebird 3では失敗するでしょう。詳細は、互換性の章ををご覧ください。 + +
+ +
+ + gstat + + Claudio + Valderrama + + + トラッカー・リファレンス CORE-1411 + 統計レポートユーティリティgstatに、利用可能なスイッチと引数に関するヘルプを参照するためのスイッチ-?と-helpが追加されました。 +
+ + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/fbteamsr25.docbook b/src/docs/rlsnotes-ja/rlsnotes25/fbteamsr25.docbook new file mode 100644 index 00000000..c1990e32 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/fbteamsr25.docbook @@ -0,0 +1,148 @@ + + + + Firebird 2.5 プロジェクトチーム + + + + + Firebird開発チーム + + + + + + + + 開発者 + 出身国 + 担当作業 + + + + + + Dmitry Yemanov + ロシア連邦 + フルタイムDBエンジニア／実装、コアチームリーダー + + + Alex Peshkov + ロシア連邦 + フルタイムセキュリティ機能コーディネータ；ビルドマスター；移植オーソリティ + + + Claudio Valderrama + チリ + コード検査；バグ発見、修正；ISQL拡張；UDF修正、設計、実装 + + + Vladyslav Khorsun + ウクライナ + フルタイムDBエンジニア、SQL機能設計／実装 + + + Adriano dos Santos Fernandes + ブラジル + 新国際キャラクタ・セット処理；テキストおよびテキストBLOB拡張；新DSQL機能；コード検査 + + + Nickolay Samofatov + ロシア連邦 + エンジンへの寄与 + + + Roman Simakov + ロシア連邦 + エンジンへの寄与 + + + Paul Beach + フランス + リリースマネージャ；HP-UXビルド；MacOSビルド；Solarisビルド + + + Pavel Cisar + チェコ共和国 + QAツール設計／コーディネート + + + Philippe Makowski + フランス + QAテスト；Linuxディストリビューションビルド + + + Pavel Zotov + ロシア連邦 + QAテスト／ツール開発 + + + Paul Reeves + フランス + Win32インストーラおよびビルド + + + Mark Rotteveel + オランダ + Jaybird実装およびコーディネート + + + Jiri Cincura + チェコ共和国 + .NETプロバイダの開発およびコーディネート + + + Alexander Potapchenko + ロシア連邦 + Firebird用ODBC/JDBCドライバの開発およびコーディネート + + + Stephen Boyd + カナダ + GPREへの寄与 + + + Paul Vinkenoog + オランダ + コーディネート、Firebirdドキュメントプロジェクト；ドキュメント執筆およびツール開発／実装 + + + Norman Dunbar + イギリス + ドキュメント執筆 + + + Pavel Menshchikov + ロシア連邦 + ドキュメント翻訳 + + + Tomneko Hayashi + 日本 + ドキュメント翻訳 + + + Umberto (Mimmo) Masotti + イタリア + ドキュメント翻訳 + + + Helen Borrie + オーストラリア + リリースノート編集；思想警察長官 + + + さらに + + + + + リトラル・コート・ドパール大学の学生たち + フランス + QAテスト開発 + + + +
+ + diff --git a/src/docs/rlsnotes-ja/rlsnotes25/rlsnotes25.xml b/src/docs/rlsnotes-ja/rlsnotes25/rlsnotes25.xml new file mode 100644 index 00000000..b88e3cf4 --- /dev/null +++ b/src/docs/rlsnotes-ja/rlsnotes25/rlsnotes25.xml @@ -0,0 +1,81 @@ + + + + + Firebird 2.5 リリースノート + + + Helen Borrie + （校正／編集） + + + + Tsutomu + Hayashi + Translation into Japanese + + + Yoshiyuki + Iwasaki + Translation into Japanese + + + Yasuro + Tanigawa + Translation into Japanese + + + + 2015年9月7日 ─ ドキュメント・バージョン0254_01-ja ─ Firebird 2.5.4 用 + + +&gennotes25; +&new25; +&engine25; +&apiods25; +&reservedwords25; +&config25; +&admin25; +&security25; +&ddl25; +&dml25; +&psql25; +&intl25; +&utils25; +&install25; +&compat25; +&ports25; +&bugs25; +&teams25; +&sqlstates25; +&licence25; + + \ No newline at end of file From 672610b864a47180b2196fc5b381ae7192703ae6 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Mon, 25 Apr 2016 01:01:58 +0000 Subject: [PATCH 24/33] Added 3.0 QSG and 2 new images for it. --- src/docs/firebirddocs.xml | 2 + .../firebirddocs/images/InstallScreen-3.0.png | Bin 0 -> 38560 bytes src/docs/firebirddocs/images/Services-3.png | Bin 0 -> 51890 bytes src/docs/firebirddocs/quickstartguide-3.xml | 4200 +++++++++++++++++ 4 files changed, 4202 insertions(+) create mode 100644 src/docs/firebirddocs/images/InstallScreen-3.0.png create mode 100644 src/docs/firebirddocs/images/Services-3.png create mode 100644 src/docs/firebirddocs/quickstartguide-3.xml diff --git a/src/docs/firebirddocs.xml b/src/docs/firebirddocs.xml index 42de6ec6..7ce43809 100644 --- a/src/docs/firebirddocs.xml +++ b/src/docs/firebirddocs.xml @@ -36,6 +36,7 @@ + @@ -73,6 +74,7 @@ + diff --git a/src/docs/firebirddocs/images/InstallScreen-3.0.png b/src/docs/firebirddocs/images/InstallScreen-3.0.png new file mode 100644 index 0000000000000000000000000000000000000000..3bcc8c853cda7965be0b84fe21f06072b0becec4 GIT binary patch literal 38560 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 K+D?!Bf^TTs#Hx9e+bG2ISX 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

J%EZGH2lHV`ejv88 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 iDYjazN~KaRm;VEY@_1tCF3EQQ0000 + +

+ + Firebird 3 Quick Start Guide + + Firebird 3 Quick Start + + + IBPhoenix Editors + + Firebird Project members + + + 25 April 2016, document version 5.2 — covers Firebird 3 + + + + +
+ About this guide + + The Firebird Quick Start Guide is an + introduction for the complete newcomer to a few essentials for getting off + to a quick start with a Firebird binary kit. The guide first saw the light + as Chapter 1 of the Using Firebird manual, sold on + CD by IBPhoenix. Later it + was published separately on the Internet. In June 2004, IBPhoenix donated + it to the Firebird Project. Since then it is maintained, and regularly + updated, by members of the Firebird documentation project. + + + Before you read on, verify that this guide matches your Firebird + version. This document covers Firebird 3. For all other Firebird + versions, get the corresponding Quick Start Guide at http://www.firebirdsql.org/en/documentation/. + +
+ +
+ The Firebird licenses<indexterm> + <primary>Licenses</primary> + </indexterm><indexterm> + <primary>Firebird licenses</primary> + </indexterm><indexterm> + <primary>IPL</primary> + </indexterm><indexterm> + <primary>IDPL</primary> + </indexterm> + + Firebird is a free, open-source database management system, but + free does not mean that everything is permitted. The use of + Firebird is governed by two licenses: the IPL (InterBase Public License) + and the IDPL (Initial Developer's Public License). The first one covers + the parts of the source code that were inherited from InterBase; the + second applies to the additions and improvements made by the Firebird + Project. Both licenses offer similar rights and restrictions. In + short: + + + + Use of the software is free, even for commercial purposes. You + may also redistribute the software, separately or with a product of + your own, but you may not claim ownership or credit for it. Any + license notices included with Firebird must remain intact. + + + + You may modify and recompile the Firebird source code or parts + of it. You may distribute such modified versions, but if you do so, + you must document your modifications and make + them publicly available, at no cost, under the same license as the + original code. + + + + You may include Firebird source code (modified or not) in a + larger work and distribute that larger work, in source and/or compiled + form, under a license of your own choosing. You need not publicize the + source code for the entire larger work, but you + must fulfill the license conditions for the parts + that were taken from Firebird, whether they were modified or + not. + + + + Please notice that the above is a simplified overview. Only the + original license texts are legally binding. You can find them here: + +
+ http://www.firebirdsql.org/ipl/ + (IPL) + + http://www.firebirdsql.org/idpl/ + (IDPL) +
+
+ +
+ <indexterm> + <primary>Installation</primary> + </indexterm>Installing Firebird + + The instructions given below for the installation of Firebird on + Windows and Linux should be sufficient for the vast majority of cases. + However, if you experience problems or if you have special needs not + covered here, be sure to read the Release Notes. + This is especially important if you are upgrading from a previous version + or if there are remnants of an old (and maybe long gone) InterBase or + Firebird installation floating around your system (DLLs, Registry entries, + environment variables...) + +
+ <indexterm> + <primary>Installation kits</primary> + </indexterm>Installation kits + + At the Firebird website – http://firebirdsql.org – the + installation kits have names like: + +
+ Firebird-3.0.0.bbbbb_p_x64.exe + (Windows executable installer) + + Firebird-3.0.0.bbbbb-p_x64.zip + (Windows zip kit for manual installation) + + Firebird-3.0.0.bbbbb_p_Win32.exe + (Windows executable installer, 32 bits) + + Firebird-3.0.0.bbbbb-p.amd64.rpm + (Linux RPM kit) + + Firebird-3.0.0.bbbbb-p.amd64.tar.gz + (Linux compressed tarball) + + Firebird-3.0.0.bbbbb-p.i686.rpm + (Linux RPM kit, 32 bits) + + Firebird-3.0.0.bbbbb-x86_64.pkg + (Mac OS-X 64-bit package) + + etc. +
+ + ...where bbbbb is the build number + (32483 for the initial 3.0.0 release) and p + the packaging number (usually 0 or another low one-digit number). + + Firebird 3 packages will also undoubtedly wind up in various Linux + distributions and their online repositories. These will have their own + naming schemes. +
+ +
+ <indexterm> + <primary>Installation</primary> + + <secondary>server</secondary> + </indexterm>Installing the Firebird server + +
+ Before installation + + It is almost always advisable to uninstall any previous Firebird + installations completely (after you've read the + next paragraph!) and also hunt the Windows system dirs for old copies + of gds32.dll and + fbclient.dll. If you're using Linux, the + uninstall scripts should have removed any copies and/or symlinks in + /usr/lib[64], but it won't hurt + to look if anything named libfbclient.* or + libgds.* is still lying around. + + Furthermore, you should be aware that Firebird 3 won't open + databases that were created by older versions. So before taking down + your existing setup, you should back up all your databases in order + that you can restore them later under Firebird 3. + + You may also want to back up your old security database + security2.fdb. Firebird 3 comes with an SQL + script security_database.sql (located in + misc/upgrade/security) that will upgrade the old + security database to Firebird 3, preserving all information + except SYSDBA's and except + any passwords. For more information, see Compatibility + Issues :: Upgrading a v.2.x Security + Database in the Firebird 3 Release Notes. +
+ +
+ <indexterm> + <primary>Installation</primary> + + <secondary>drives</secondary> + </indexterm>Installation drives + + The Firebird server – and any databases you create or connect to + – must reside on a hard drive that is physically connected to the host + machine. You cannot locate components of the server, or any database, + on a mapped drive, a filesystem share or a network filesystem. (Well, + you can, but you shouldn't, and this technique isn't covered + here.) + + + You can mount a read-only database on a CD-ROM drive but you + cannot run Firebird server from one. + +
+ +
+ <indexterm> + <primary>Installation</primary> + + <secondary>script or program</secondary> + </indexterm>Installation script or program + + Although it is possible to install Firebird by a filesystem + copying method – such as untarring a snapshot build or decompressing a + structured .zip archive – it is + strongly recommended that you use the distributed release kit + (.exe for Windows, .rpm for + Linux), especially if this is the first time you install Firebird. The + Windows installation executable, the Linux + rpm program and the + install.sh script in the official .tar.gz for various Posix platforms all + perform some essential setup tasks. Provided you follow the + installation instructions correctly, there should be nothing for you + to do upon completion but log in and go! +
+ +
+ Server modes + + Some installers ask you to choose between Classic, SuperClassic + and Superserver mode. What are they? + + + + Classic mode (aka MultiProcess) + involves a single listening process that spawns off an additional + process for each client connection. Using a locking mechanism, it + allows shared connections to database files. + + + + SuperClassic (ThreadedShared) is a + single server process. Client connections are handled by separate + threads, each having their own database page cache. Other + processes (e.g. embedded servers) may open the same database + simultaneously (hence the Shared). + + + + Superserver (ThreadedDedicated) is + also a single server process with threads handling client + connections. There is a single, common database page cache. The + server requires exclusive access to each database file it opens + (hence the Dedicated). + + + + Each mode is fully stable and there is no reason to + categorically prefer one to the other. Of course you may have your own + specific considerations. When in doubt, just follow the installer + default for now. Changing the server mode later can be done via the + configuration file firebird.conf and requires a + restart but not reinstallation. The server mode can even be configured + per database (consult the Release Notes for details). + + + Users of Firebird 2.5 or earlier: please notice that as from + Firebird 3, Superserver fully supports the use of multiple + processors/cores out of the box, so lack of SMP support is no longer + a reason to avoid it. + +
+ +
+ Installing on Windows + + Make sure you run the installer program as Administrator (i.e. + right-click on the executable and choose Run as + Administrator) or you may run into permission problems + later! + + On Windows server platforms Firebird will run as a system + service by default, but during installation you can also choose to let + it run as an application. Don't do this unless you have a compelling + reason. + + The installer will also ask if you want to enable authorization + for legacy (i.e. pre-3.0) Firebird clients. If security is a concern + (as it should be), don't allow this or allow it only temporarily while + you upgrade your existing clients to Firebird 3.0. The legacy + connection method sends passwords over the wire unencrypted; it also + limits the usable length of the password to 8 characters. + + + + + + + + During installation you have the option of providing a password + for Firebird's superuser, SYSDBA. Firebird + passwords may be up to 255 bytes long, but due to the nature of the + hashing algorithm the effective length is around 20 + bytes, so it's not very useful to enter a password that's much longer + than that. Notice however that if you do enter such a password, you + must supply it in its full length every time you connect – it won't + work if you truncate it to the first 20 characters! + +
+ <indexterm> + <primary>Guardian</primary> + </indexterm><indexterm> + <primary>Firebird Guardian</primary> + </indexterm>Use the Guardian? + + The Firebird Guardian is a utility that monitors the server + process and tries to restart it if it terminates abnormally. During + a Windows install, you can opt to use the Guardian when running in + SuperClassic or Superserver mode. However, since modern Windows + systems have the facility to watch and restart services, there is no + reason to use the Guardian if Firebird runs as a service (which it + should). + + The Guardian may be phased out in future versions of + Firebird. +
+
+ +
+ Installing on Linux and other Unix-like platforms + + In all cases, read the Release Notes for the Firebird version + you're going to install. There may be significant variations from + release to release of any Posix operating system, especially the open + source ones. Where possible, the build engineers for each Firebird + version have attempted to document any known issues. + + Aside from being packaged with the download kits, Release Notes + for all officially released versions of Firebird can also be found at + http://www.firebirdsql.org/en/release-notes/. + + If you have a Linux distribution that supports + rpm installs, consult the appropriate + platform documentation for instructions about using RPM + Package Manager. In most distributions you will have the + choice of performing the install from a command shell or through a GUI + interface. + + For Linux distributions that cannot process + rpm programs, and for Unix flavours for + which no .rpm kit is provided, + use the .tar.gz kit. Quite + often, installation is just a matter of untarring the archive and + running install.sh. In some cases, the Release + Notes or packed Readmes may instruct you to edit the scripts and make + some manual adjustments. +
+
+ +
+ Installing multiple servers + + Firebird allows the operation of multiple servers on a single + machine. It can also run concurrently with Firebird 1.x or InterBase + servers. Setting this up is not a beginner's task though. If you need to + run multiple servers on the same machine, the second and subsequent + servers must be installed and configured manually. They need to have + different service names and should listen on different TCP/IP ports. The + file install_windows_manually.txt in the + doc subdir may be of help if you're doing this on + Windows, but bear in mind that it was written for Firebird 2.1. + + Also read the chapter Configuring the Port Service on + Client and Server in the Firebird 1.5 (!) Release + Notes: + +
+ http://www.firebirdsql.org/file/documentation/release_notes/html/rlsnotes15.html#config-port + + http://www.firebirdsql.org/file/documentation/release_notes/Firebird-1.5.6-ReleaseNotes.pdf#page=96 +
+
+ +
+ <indexterm> + <primary>Testing</primary> + </indexterm>Testing your installation + + If you want to connect to your Firebird server across a network, + then before testing the Firebird server itself you may want to verify + that the server machine is reachable from the client at all. At this + point, it is assumed that you will use the recommended TCP/IP network + protocol for your Firebird client/server connections. (On Windows + networks, NetBEUI is also supported.) + +
+ <indexterm> + <primary>Ping</primary> + </indexterm>Pinging the server + + The ping command – available on most systems + – is a quick and easy way to see if you can connect to a server + machine via the network. For example, if your server's IP address in + the domain that is visible to your client is 192.13.14.1, go to a command shell on + the client machine and type the command + +
+ ping 192.13.14.1 +
+ + substituting this example IP address with the IP address that + your server is broadcasting. If you are on a managed network and you + don't know the server's IP address, ask your system administrator. Of + course you can also ping the server by its name, if you know + it: + +
+ ping vercingetorix +
+ + If you are connecting to the server from a local client – that + is, a client running on the same machine as the server – you can ping + the virtual TCP/IP loopback server: + +
+ ping localhost –or– ping + 127.0.0.1 +
+ + If you have a simple network of two machines linked by a + crossover cable, you can set up your server with any IP address you + like except 127.0.0.1 (which is reserved for a local loopback server) + and, of course, the IP address which you are using for your client + machine. If you know the native IP addresses of your + network cards, and they are different, you can simply use + those. + + Once you have verified that the server machine is reachable from + the client, you can go on to the next step. +
+ +
+ <indexterm> + <primary>Checking the server</primary> + </indexterm>Making sure that the Firebird server is running + + Most – but not all – installation packages start up the Firebird + server as one of the final steps during installation, and also make + sure that Firebird is started at every reboot. + + After being launched, the Firebird server should be + running: + + + + On Linux or other Unix-like systems: + + + As a service. + + + + + On Windows server systems: + + + As a service or as an application. Service is default and + highly recommended. + + + + + The following sections show you how to test the server on each + platform. + +
+ Server check: Linux and other Unices + + + top command (Linux) + Use the top command in a command + shell to inspect the running processes interactively. If a Firebird + 3 server is running, you should see a process named firebird and possibly also fbguard (the Guardian process). + + The following screen shows the output of + top, restricted by + grep to show only lines containing the + string firebird: + + paul@fili ~ $ top -b -n1 | grep [f]irebird + 7169 firebird 20 0 29668 992 560 S 0,0 0,0 0:00.00 fbguard + 7171 firebird 20 0 228160 5876 3048 S 0,0 0,1 0:00.01 firebird + + As an alternative to top, you can + use ps -ax or ps -aux and pipe + the output to grep. + + The process name is firebird regardless if Firebird is + running in Superserver, Classic or SuperClassic mode. However, it is + possible to configure a Classic-mode Firebird in such a way that it + runs as a service under (x)inetd. In that case, you will only see a + firebird process if a + client connection has been made. + + Another way of testing the server after installation is by + starting a Firebird client (e.g. + /opt/firebird/bin/isql) and connecting to a + database or creating one. These operations are described later in + this guide. + + If it turns out that the server hasn't been started after all, + you may need to do this manually, e.g. with + /etc/init.d/firebird start or systemctl + start firebird and systemctl enable + firebird, depending on the type of Linux system and your + Firebird installation package. +
+ +
+ Server check: Windows, running as service + + Open Control Panel -> Administrative Tools -> + Services. + + + Services (Windows) + This illustration shows the Services applet display on + Windows 7. The appearance may vary from one Windows server edition + to another. + + + + + + + + You should at least find the Firebird server in the services + listing. The Guardian may or may not be running, depending on the + choices you made during installation. If you didn't opt to start the + server at the end of the installation process, you may do so now by + right-clicking on the Firebird entry (or the Guardian) and choosing + Start. +
+ +
+ Server check: Windows, running as application + + If Firebird is up and running as an application, it is + represented by an icon in the system tray: + + + + A green and grey server symbol if controlled by the + Guardian; + + + + A round yellow and black graphic if running + standalone. + + + + A flashing icon indicates that the server is in the process of + starting up (or at least trying to do so). A red icon, or an icon + with an overlying red stop sign, indicates that startup has + failed. + + One way to make 100% sure if the server is running or not is + to press Ctrl-Alt-Del and look for the firebird process (and possibly + fbguard) in the task list. + You may need to check the box Show processes of all + users for these processes to become visible. + + On some occasions, you may need to start the Guardian or + server once explicitly via the Start menu even if you opted for + Start Firebird now at the end of the installation + process. Sometimes a reboot is necessary. + + You can shut the server down via the menu that appears if you + right-click on the tray icon. Notice that this also makes the icon + disappear; you can restart Firebird via the Start menu. + + + In Classic mode (but not SuperClassic!) a new process is + launched for every connection, so the number of firebird processes will always equal + the number of client connections plus one. Shutdown via the tray + icon menu only terminates the first process (the + listener). Other processes, if present, + will continue to function normally, each terminating when the + client disconnects from the database. Of course, once the listener + has been shut down, new connections can't be made. + +
+
+
+ +
+ <indexterm class="singular" scope="local"> + <primary>Installation</primary> + + <secondary>client-only</secondary> + </indexterm>Performing a client-only install + + Each remote client machine needs to have the client library – + libfbclient.so on Posix + clients, fbclient.dll on + Windows clients – that matches the release version of the Firebird + server. + + Firebird can install symlinks or copies named after the 1.0 libs + (with the old InterBase names), to maintain compatibility + with third-party products which need these files. + + Some extra pieces are also needed for the client-only + install. + +
+ Windows + + At present, no separate installation program is available to + install only the client pieces on a Windows machine. If you are in the + common situation of running Windows clients to a Linux or other + Unix-like Firebird server (or another Windows machine), you need to + download the full Windows installation kit that corresponds to the + version of Firebird server you install on your server machine. + + Fortunately, once you have the kit, the Windows client-only + install is a breeze. Just run the installation program and when you + arrive at the Select Components screen, choose one of + the client-only options from the drop-down list or uncheck the + Server Components checkbox. +
+ +
+ Linux and some other Posix clients + + A small-footprint client install program for Linux clients is + not available either. Additionally, some Posix flavours – even within + the Linux constellation – have somewhat idiosyncratic requirements for + filesystem locations. For these reasons, not all *x distributions for + Firebird even contain a client-only install option. + + For most Linux flavours, the following procedure is suggested + for a manual Firebird client-only install. Log in as root for this. + + + + Look for libfbclient.so.3.0.n + (n being the patch version number) in + /opt/firebird/lib on the + machine where the Firebird server is installed. Copy it to + /usr/lib on the client (or + /usr/lib64 if both server + and client are 64-bits). + + + + Create chained symlinks using the following commands: + +
+ ln -s + /usr/lib/libfbclient.so.3.0.n + /usr/lib/libfbclient.so.2 + + ln -s /usr/lib/libfbclient.so.2 + /usr/lib/libfbclient.so +
+ + ...replacing + 3.0.n with your + version number, e.g. 3.0.0 or + 3.0.4 + + If you're running applications that expect the legacy + libraries to be present, also create the following + symlinks: + +
+ ln -s /usr/lib/libfbclient.so + /usr/lib/libgds.so.0 + + ln -s /usr/lib/libfbclient.so + /usr/lib/libgds.so +
+ + + + Copy firebird.msg to the client + machine, preferably into the /opt/firebird directory. If you place + it somewhere else, create a system-wide permanent + FIREBIRD environment variable pointing to the right + directory, so that the API routines can locate the + messages. + + + + Optionally copy some of the Firebird command-line tools – + e.g. isql – to the client + machine. + + + + + + Instead of copying the files from a server, you can also pull + them out of a Firebird tar.gz + kit. Everything you need is located in the /opt/firebird tree within the + buildroot.tar.gz archive that's packed inside the + kit. +
+
+
+ +
+ <indexterm> + <primary>Disk locations</primary> + </indexterm>Default disk locations + + The tables below show you where you'll find the Firebird files and + directories after a standard installation. Please notice that the listings + are not exhaustive. + +
+ <indexterm> + <primary>Disk locations</primary> + + <secondary>Linux</secondary> + </indexterm>Linux + + The following table shows the default component locations of a + Firebird installation on Linux. Some of the locations may be different + on other Unix-like systems, or on certain Linux distributions. + + + Firebird 3.0 component locations on Linux + + + + + + + + + + + Component + + File Name + + Default Location + + + + + + Installation directory(referred to + hereafter as + $(install)) + + — + + /opt/firebird(may vary + per distribution) + + + + Configuration files + + firebird.conf, + databases.conf, etc. + + $(install) + + + + Release Notes and other + documentation + + Various files + + $(install)/doc + + + + Firebird server + + firebird + + $(install)/bin + + + + Command-line tools + + isql, + gbak, nbackup, + gfix, gstat, + etc. + + $(install)/bin + + + + Plugins (new in Firebird 3) + + libEngine12.so, + libSrp.so, + libudr_engine.so, etc. + + $(install)/plugins + + + + Sample database + + employee.fdb + + $(install)/examples/empbuild + + + + UDF libraries + + ib_udf.so, + fbudf.so + + + $(install)/UDF + + + + Additional server-side libraries + + libib_util.so + + $(install)/lib + + + + Client libraries + + libfbclient.so.3.0.nThe + usual symlinks (*.so.2, + *.so) are created. Legacy + libgds.* symlinks are also + installed. + + /usr/lib[64](actually, + the real stuff is in $(install)/lib, + but you should use the links in /usr/lib[64]) + + + +
+
+ +
+ <indexterm> + <primary>Disk locations</primary> + + <secondary>Windows</secondary> + </indexterm>Windows + + In the table below, <ProgramDir> refers to the Windows + programs folder. This is usually C:\Program Files but may also be a + different path, e.g. D:\Programmi. Likewise, <SystemDir> refers to the Windows + system directory. Be sure to read the notes below the table, especially + if you're running Firebird on a 64-bit Windows system. + + + Firebird 3.0 component locations on Windows + + + + + + + + + + + Component + + File Name + + Default Location + + + + + + Installation directory(referred to + hereafter as + $(install)) + + — + + <ProgramDir>\Firebird\Firebird_3_0 + + + + Configuration files + + firebird.conf, + databases.conf, etc. + + $(install) + + + + Release Notes and other + documentation + + Various files + + $(install)\doc + + + + Firebird server + + firebird.exe + + $(install) + + + + Command-line tools + + isql.exe, + gbak.exe, nbackup.exe, + gfix.exe, gstat.exe, + etc. + + $(install) + + + + Plugins (new in Firebird 3) + + engine12.dll, + srp.dll, + udr_engine.dll, etc. + + $(install)\plugins + + + + Sample database + + employee.fdb + + $(install)\examples\empbuild + + + + Internationalisation + + fbintl.conf, fbintl.dll + + $(install)\intl + + + + User-defined function (UDF) + libraries + + ib_udf.dll, fbudf.dll + + $(install)\UDF + + + + Additional server-side libraries + + icu*.dll, + ib_util.dll + + $(install) + + + + Client connection libraries + + fbclient.dll(with an + optional gds32.dll, to + support legacy apps) + + $(install)(with + an optional copy in <SystemDir> – see note below + table) + + + + Some necessary Microsoft runtime + libs + + msvcp100.dll, msvcr100.dll + + $(install) + + + + 32-bit library versions for use with 64-bit + Firebird + + fbclient.dll, msvcp100.dll, msvcr100.dll + + $(install)\WOW64(with + an optional copy in SysWOW64 – see second note below + table) + + + +
+ + + The Windows system directory + + A typical location for the Windows system directory – on both + 32-bit and 64-bit systems – is C:\Windows\System32 + + If you run Firebird on a 64-bit system, make sure to also read + the next note. + + + + Important notice for 64-bit Windows users + + On 64-bit Windows systems, the Program Files directory is + reserved for 64-bit programs. If you try to install a 32-bit + application into that folder, it will be auto-redirected to a + directory which – in English versions – is called Program Files (x86). In other + language versions the name may be different. + + In the same vein, the System32 directory is reserved for 64-bit + libraries. 32-bit libraries go into SysWOW64. That's right: 64-bit libraries + are in System32, 32-bit + libraries in SysWOW64. + + If you're not aware of this, you may have a hard time locating + your 32-bit Firebird components on a 64-bit Windows system. + + (Incidentally, WOW stands for + Windows on Windows. Now you can work out for + yourself what LOL means.) + +
+
+ +
+ <indexterm> + <primary>Configuration</primary> + </indexterm><indexterm> + <primary>Management</primary> + </indexterm>Server configuration and management + + There are several things you should be aware of – and take care of – + before you start using your freshly installed Firebird server. This part + of the manual introduces you to some useful tools and shows you how to + protect your server and databases. + +
+ <indexterm> + <primary>gsec</primary> + </indexterm>User management + + In Firebird 3, user management is done entirely through SQL + commands. Users of previous versions are probably familiar with the + gsec utility for this task. It is still + present, but deprecated and it won't be discussed here. + +
+ <indexterm> + <primary>SYSDBA</primary> + </indexterm><indexterm> + <primary>Passwords</primary> + + <secondary>changing</secondary> + </indexterm>Changing the <database>SYSDBA</database> + password + + One Firebird account is created automatically as part of the + installation process: SYSDBA. This account has + all the privileges on the server and cannot be deleted. Depending on + version, OS, and architecture, the installation program will + either + + + + install the SYSDBA user with the + password masterkey, or + + + + ask you to enter a password during installation, or + + + + generate a random password and store that in the file + SYSDBA.password within your Firebird + installation directory. + + + + If the password is masterkey and your server + is exposed to the Internet at all – or even to a local network, unless + you trust every user with the SYSDBA password – + you should change it immediately. Fire up + isql or another Firebird client and connect + to a database. In this example, the employee example + database is used, because its alias is always present in a freshly + installed Firebird setup: + +
+ connect localhost:employee user sysdba password + masterkey; +
+ + If you do this in isql, it should + respond with: + +
+ Database: localhost:employee, User: + SYSDBA +
+ + Now alter the sysdba password: + +
+ alter user sysdba set password + 'Zis4_viZuna83YoYo'; +
+ + The SET keyword is optional, and instead of + USER SYSDBA you can also use + CURRENT USER, which always + refers to the user you are logged in as. + + If the command succeeds, you won't get any feedback. Instead, + isql will just print the next + SQL>-prompt, thus indicating that + all is well and your further input is awaited. + + Please notice that unlike regular user names, + Firebird passwords are always case sensitive. +
+ +
+ <indexterm> + <primary>User accounts</primary> + </indexterm>Adding Firebird user accounts + + Firebird allows the creation of many different user accounts. + Each of them can own databases and also have various types of access + to databases and database objects it doesn't own. + + Assuming you are connected to a database as + SYSDBA, you can add a user account as + follows: + +
+ create user billyboy password + 'TooLongFor8099Comfort' +
+ + The full range of user management commands is: + +
+ CREATE USER name PASSWORD 'password' [<options>] [<tags>]; +[CREATE OR] ALTER USER name [SET] [PASSWORD 'password'] [<options>] [<tags>]; +ALTER CURRENT USER [SET] [PASSWORD 'password'] [<options>] [<tags>]; +DROP USER name; + +<options> ::= <option> [, <option> ...] +<option> ::= {FIRSTNAME | MIDDLENAME | LASTNAME} 'stringvalue' + | ACTIVE + | INACTIVE + +<tags> ::= TAGS (<tag> [, <tag> ...]) +<tag> ::= tagname = 'stringvalue' + | DROP tagname +
+ + Tags are optional key-value pairs that + can be freely defined by the user. The key (tag name) must be a valid + SQL identifier, the value a non-NULL string of at + most 255 bytes. + + Only SYSDBA and co-admins can use all these + commands. Ordinary users can change their own parameters (such as + password, name parts and tags, but not active/inactive) using + ALTER USER name or + ALTER CURRENT USER. It is not possible to change + an account name. + + Examples: + +
+ create user dubya password 'Xwha007_noma' firstname 'GW' lastname 'Shrubbery'; +create user lorna password 'Mayday_domaka' + tags (Street = 'Main Street', Number = '888'); +alter user benny tags (shoesize = '8', hair = 'blond', drop weight); +alter current user set password 'SomethingEvenMoreSecretThanThis'; +alter user dubya set inactive; +drop user ted; +
+
+ +
+ <indexterm> + <primary>Security database</primary> + </indexterm>The security database + + Firebird user accounts are kept in a security + database, which normally resides in the installation + directory and is called security3.fdb (alias: + security.db). Except in the case of so-called + embedded connections (more about those later in this guide), + connecting to a database always involves the security database, + against which the user credentials are verified. Of course this is + done transparently; the user doesn't have to make an explicit + connection to the security database. + + However, in Firebird 3 this is not the end of the story. + Firebird now allows the use of multiple security databases on a + system, each security database governing a specific set of databases. + A database can even act as its own security database. + + Showing how to set this up is outside the scope of this Quick + Start Guide. You can find full details in the Release Notes, chapter + Security. But it is important to realise that + if a system has multiple security databases, + managing user accounts while connected to a database will always + affect the accounts in the security database that governs + that specific database. To be on the safe side, + you may want to connect to the security database itself before issuing + your user management commands. Connecting to the security database + used to be forbidden in recent versions of Firebird, but is now once + again possible, albeit by default only locally (which means that even + the localhost route is + blocked). +
+ +
+ <indexterm> + <primary>Administrators</primary> + </indexterm><indexterm> + <primary><database>RDB$ADMIN</database> role</primary> + + <secondary>in the security database</secondary> + </indexterm>Appointing co-administrators + + Note: What follows here is not + essential knowledge for beginners. You can skip it if you like and go + on to the Security + section. + + In Firebird 2.5 and up, SYSDBA (and others + with administrator rights) can appoint co-administrators. This is done + with the GRANT ADMIN ROLE directive: + +
+ create user bigbill password 'bigsekrit7foryou' grant admin role; +alter user littlejohn grant admin role; +
+ + The first command creates user bigbill as a Firebird administrator, who + can add, alter and drop users. The second command grants administrator + privileges to the existing user littlejohn. + + To revoke administrator privileges from an account, use + ALTER USER ... REVOKE ADMIN + ROLE. + + + Notes + + + + GRANT ADMIN ROLE and REVOKE + ADMIN ROLE are not GRANT and + REVOKE statements, although they look that + way. They are parameters to the CREATE and + ALTER USER statements. The actual role name + involved here is RDB$ADMIN. This role also + exists in regular databases; more about that in a minute. + + + + Every user who has received administrator rights can pass + them on to others. Therefore, there is no explicit + WITH ADMIN OPTION. + + + + Just for completeness, administrators can also grant admin + rights to an existing user by connecting to the security + database and issuing a regular GRANT + statement: + +
+ grant rdb$admin to littlejohn +
+ + + + +
+ Differences between co-administrators and + <database>SYSDBA</database> + + + + Co-admins can create, alter and drop users, but they have + no automatic privileges in regular databases, like + SYSDBA has. + + + + Unlike SYSDBA, co-admins must specify + the RDB$ADMIN role + explicitly if they want to exert their rights as system + administrator: + +
+ connect security.db user bigbill password bigsekrit7foryou role rdb$admin +
+ + + RDB$ADMIN role + + in regular databases + For reasons explained elsewhere in this guide, + connecting to the security database like this may fail if a + Superserver is running. On Windows, you may circumvent this by + prepending xnet:// to the database path or + alias, but on Posix, you're stuck. The only solution there is to + grant the co-admin the RDB$ADMIN role in at + least one regular database as well. (A database that uses the + security database in question, of course.) This is done in the + usual way that roles are granted: + +
+ grant rdb$admin to bigbill +
+ + Grantors can be the database owner, + SYSDBA, and every other user who has the + RDB$ADMIN role in that database and has + specified it while connecting. Every + RDB$ADMIN member in a database can pass the + role on to others, so again there is no WITH ADMIN + OPTION. Once the co-admin has obtained the role, he + can connect to the (regular) database with it and use the SQL + user management commands. It's not the most elegant of + solutions, but it works. + + + + + + + Please remember: + + The RDB$ADMIN role in a database gives + the grantee SYSDBA rights in that + database only! + + + + If it is the security database, the grantee can manage + user accounts, but has no special privileges in other + databases. + + + + If it is a regular database, the grantee can control + that database like he was SYSDBA, but + again has no special privileges in other databases, and has no + user administration privileges. + + + + Of course it is possible to grant a user the + RDB$ADMIN role in several databases, + including the security database. + +
+
+
+ +
+ <indexterm> + <primary>Security</primary> + </indexterm><indexterm> + <primary>Databases</primary> + + <secondary>security</secondary> + </indexterm>Security + + Firebird 3 offers a number of security options, designed to make + unauthorised access as difficult as possible. Be warned however that + some configurable security features default to the old, + insecure behaviour inherited from InterBase and earlier + Firebird versions, in order not to break existing applications. + + It pays to familiarise yourself with Firebird's security-related + configuration parameters. You can significantly enhance your system's + security if you raise the protection level wherever possible. This is + not only a matter of setting parameters, by the way: other measures + involve tuning filesystem access permissions, an intelligent user + accounts policy, etc. + + Below are some guidelines for protecting your Firebird server and + databases. + + + + Run Firebird as non-system user + + + On Unix-like systems, Firebird already runs as user + firebird by default, not + as root. On Windows + server platforms, you can also run the Firebird service under a + designated user account (e.g. Firebird). The default practice – + running the service as the LocalSystem user – poses a security + risk if your system is connected to the Internet. Consult + README.instsvc.txt in the doc subdir to learn more about + this. + + + + + + SYSDBA + Change SYSDBA's password + + + As discussed before, if your Firebird server is reachable + from the network and the system password is + masterkey, change it. + + + + + + SYSDBA + Don't create user databases as SYSDBA + + + SYSDBA is a very powerful account, with + full (destructive) access rights to all your Firebird databases. + Its password should be known to a few trusted database + administrators only. Therefore, you shouldn't use this + super-account to create and populate regular databases. Instead, + generate normal user accounts, and provide their account names and + passwords to your users as needed. You can do this with the SQL + user management commands as shown above, or with any decent + third-party Firebird administration tool. + + + + + Protect databases on the filesystem level + + + Anybody who has filesystem-level read access to a database + file can copy it, install it on a system under his or her own + control, and extract all data from it – including possibly + sensitive information. Anybody who has filesystem-level write + access to a database file can corrupt it or totally destroy + it. + + Also, anybody with filesystem-level access to a database can + make an embedded connection to it posing as + any Firebird user (including + SYSDBA) without having his credentials + checked. This can be especially disastrous if it concerns the + security database! + + As a rule, only the Firebird server process should have + access to the database files. Users don't need, and should not + have, access to the files – not even read-only. They query + databases via the server, and the server makes sure that users + only get the allowed type of access (if at all) to any objects + within the database. + + As a relaxation of this rule, most Firebird configurations + allow users to create and use databases in their own filesystem + space and make embedded connections to them. Since these are + their files and their + data, one may argue that unrestricted and possibly destructive + access should be their own concern, not yours. + + If you don't want or need this relaxation, follow the + instructions in the next item. + + + + + + Embedded connections + + disable + Disable embedded connections + + + If you don't want any type of direct access, you may disable + embedded mode (= direct filesystem-level access) altogether by + opening firebird.conf and locating the + Providers entry. The default (which is probably + commented out) is: + +
+ #Providers = Remote,Engine12,Loopback +
+ + Now, either remove the hash mark and the + Engine12 provider (this is the one that makes + the embedded connections), or – better – add an uncommented + line: + +
+ Providers = Remote,Loopback +
+ + The Remote provider takes care of remote + connections; the Loopback provider is + responsible for TCP/IP connections via localhost, as well as (on Windows) + WNET/NetBEUI and XNET connections to databases on the local + machine. All these connection types require full authentication + and have the server process, not the user process, open the + database file. + + Please notice that you can also set the + Providers parameter on a per-database + basis. You can set a default in firebird.conf + as shown above, and then override it for individual databases in + databases.conf like this: + +
+ bigbase = C:\Databases\Accounting\Biggus.fdb +{ + Providers = Engine12,Loopback +} +
+ + The first line defines the alias (see + next item), and everything between the curly brackets are + parameters for that specific database. You'll find + databases.conf in the same directory as + firebird.conf. Refer to the Release Notes, + chapter Configuration Additions and + Changes, section Per-database + Configuration, for more information about the various + parameters. + + + + + + Aliases + + Databases + + aliases + Use database aliases + + + Database aliases hide physical + database locations from the client. Using aliases, a client can + e.g. connect to frodo:zappa + without having to know that the real location is + frodo:/var/firebird/music/underground/mothers_of_invention.fdb. + Aliases also allow you to relocate databases while the clients + keep using their existing connection strings. + + Aliases are listed in the file + databases.conf, in this format on Windows + machines: + +
+ poker = E:\Games\Data\PokerBase.fdb +blackjack.fdb = C:\Firebird\Databases\cardgames\blkjk_2.fdb +
+ + And on Linux: + +
+ books = /home/bookworm/database/books.fdb +zappa = /var/firebird/music/underground/mothers_of_invention.fdb +
+ + Giving the alias an .fdb (or any other) extension is + fully optional. Of course if you do include it, you must also + specify it when you use the alias to connect to the + database. + + Aliases, once entered and saved, take effect immediately. + There is no need to restart the server. + + + + + Restrict database access + + + The DatabaseAccess parameter in + firebird.conf can be set to + Restrict to limit access to explicitly listed + filesystem trees, or even to None to allow + access to aliased databases only. Default is + Full, i.e. no restrictions. + + Note that this is not the same thing as the filesystem-level + access protection discussed earlier: when + DatabaseAccess is anything other than + Full, the server will refuse to open any + databases outside the defined scope even if it has sufficient + rights on the database files. + + + + + + Authentication + Choose your authentication method(s) + + + Firebird supports three authentication methods when + connecting to databases: + + + + Srp (Secure Remote Password): The + user must identify him/herself with a Firebird username and + password, which the server checks against the security + database. The maximum effective password length is around 20 + bytes, although you may specify longer passwords. Wire + encryption is used. + + + + Win_Sspi (Windows Security Support Provider + Interface): The user is logged in automatically + with his Windows account name. + + + + Legacy_Auth: Insecure method used + in previous Firebird versions. Passwords have a maximum length + of 8 bytes and are sent unencrypted across the wire. Avoid + this method if possible. + + + + Two configuration parameters control Firebird's + authentication behaviour: + + + + AuthServer determines how a user + can connect to the local server. It is usually + Srp or, on Windows machines, + Srp, + Win_Sspi. In the latter case, the + user will be authenticated with his Windows login if he fails + to supply user credentials (causing the Srp + method, which is tried first, to fail). + + + + AuthClient defines how the local + client tries to authenticate the user when making a + connection. It is usually Srp, + Win_Sspi, + Legacy_Auth, allowing the user to + connect to pre-Firebird-3 servers on remote machines. + + + + If Win_Sspi and/or + Legacy_Auth are allowed on the server side, you + must also set the WireCrypt parameter to + Enabled or Disabled, but not + Required. + + Likewise, if a server (not a client!) supports + Legacy_Auth, the + UserManager parameter must be set to + Legacy_UserManager instead of + Srp. (The default Srp user + manager can still be addressed by adding + USING PLUGIN + SRP to your user management commands.) + + The AuthServer, + AuthClient, + WireCrypt and + UserManager parameters are all set in + firebird.conf en can be overridden per + database in databases.conf. + + Please notice: enabling Win_Sspi on the + server activates the plugin but doesn't grant Windows accounts any + type of access to databases yet. Logging in to, say, the + employee database without credentials (and + making sure no embedded connection is made) will result in this + error message: + +
+ SQL> connect xnet://employee; +Statement failed, SQLSTATE = 28000 +Missing security context for employee +
+ + In other words: We know who you are (because the + Win_Sspi plugin identified you) but you can't + come in. + + The solution is to create, as SYSDBA, a + global mapping that gives any Windows account access to databases + – but no special privileges – under the same name. This is done + with the following command: + +
+ create global mapping trusted_auth +using plugin win_sspi +from any user to user +
+ + Trusted_auth is just a chosen name for + the mapping. You may use another identifier. From any + user means that the mapping is valid for any user + authenticated by the Win_Sspi plugin. + To user indicates that every user will be made + known under his own Windows account name in each database he + connects to. If instead we had specified to user + bob, then every Windows user authenticated by the + Win_Sspi plugin would be bob + in every database. + + With the mapping in effect, the Windows + trusted connection succeeds: + +
+ SQL> connect xnet://employee; +Database: xnet://employee, User: SOFA\PAUL +SQL> select current_user from rdb$database; + +USER +=============================== +SOFA\PAUL +
+ + + With embedded connections, i.e. serverless connections + handled by Engine12, where the client process + directly opens the database file, the user is also logged in + under his Windows account name if he doesn't provide a user name + when connecting. However, this doesn't require + Win_Sspi to be enabled, nor does it need any + explicit mapping: + +
+ SQL> connect employee; +Database: employee, User: PAUL +SQL> select current_user from rdb$database; + +USER +=============================== +PAUL +
+ + + + + + + + + Administrators + Consider whether Windows administrators should have + SYSDBA rights + + + In Firebird 2.1, if the (now defunct) configuration + parameter Authentication was + trusted or mixed, + Windows administrators would automatically receive + SYSDBA privileges in all databases, including + the security database. In Firebird 2.5 and later, this is no + longer the case. This reduces the risk that administrators with + little or no Firebird knowledge mess up databases or user + accounts. + + If you still want to apply the automatic + SYSDBA mapping as it was in Firebird 2.1, + login as SYSDBA and give the command: + +
+ create global mapping win_admin_sysdba +using plugin win_sspi +from predefined_group domain_any_rid_admins +to user sysdba +
+ + This grants all Windows administrators automatic + SYSDBA rights in every database (including + the security database, so they can manage user accounts), provided + that they are authenticated by the Win_Sspi + plugin. To achieve this, they must connect + + + + without supplying any user credentials, and + + + + making sure that the Engine12 + provider doesn't kick in. This is easily achieved with a + connection string like + xnet://local-path-or-alias. + + + + To give just one administrator – or indeed any user – full + SYSDBA power, use this command: + +
+ create global mapping frank_sysdba +using plugin win_sspi +from user "sofa\frank" +to user sysdba +
+ + The double quotes are necessary because of the backslash in + the user name. (Specifying just frank will be + accepted by Firebird, but won't result in a working mapping on + most, if not all, Windows systems.) + + You can drop any mapping with the command: + +
+ DROP [GLOBAL] MAPPING mapping_name +
+ + E.g.: + +
+ drop global mapping win_admin_sysdba; +drop global mapping frank_sysdba; +
+ + The GLOBAL keyword is necessary if it + concerns a global mapping and you're not directly connected to the + security database where the mapping is registered. + + + +
+ +
+ <indexterm> + <primary>Admin tools</primary> + </indexterm>Administration tools + + The Firebird kit does not come with a GUI admin tool. It does have + a set of command-line tools – executable programs which are located in + the bin subdirectory of your + Firebird installation (on Windows, they are in the installation + directory itself). One of them, isql, has + already been introduced to you. + + The range of excellent GUI tools available for use with a Windows + client machine is too numerous to describe here. At least one of them, + FlameRobin, is also available for Linux. + + Explore the Download > Tools + > Administration page at http://www.ibphoenix.com for all + of the options. + + + Remember: you can use a Windows client to access a Linux server + and vice-versa. + +
+
+ +
+ <indexterm> + <primary>Databases</primary> + + <secondary>working with databases</secondary> + </indexterm>Working with databases + + In this part of the manual you will learn: + + + + how to connect to an existing database, + + + + how to create a database, + + + + and some things you should know about Firebird SQL. + + + + In as much as remote connections are involved, we will use the + recommended TCP/IP protocol. + +
+ <indexterm> + <primary>Connecting</primary> + + <secondary>connection strings</secondary> + </indexterm>Connection strings + + If you want to connect to a database or create one you have to + supply, amongst other things, a connection string + to the client application (or, if you are a programmer, to the routines + you are calling). A connection string uniquely identifies the location + of the database on your computer, local network, or even the + Internet. + +
+ Local connection strings + + An explicit local connection string consists of the path + + filename specification in the native format of the filesystem used on + the server machine, for example + + + + on a Linux or other Unix-like server: + +
+ /opt/firebird/examples/empbuild/employee.fdb +
+ + + + on a Windows server: + +
+ C:\Biology\Data\Primates\Apes\populations.fdb +
+ + + + Many clients also allow relative path strings (e.g. + ..\examples\empbuild\employee.fdb) + but you should use these with caution, as it's not always obvious how + they will be expanded. Getting an error message is annoying enough, + but applying changes to another database than you thought you were + connected to may be disastrous. + + + Aliases + + + + Databases + + aliases + + + Instead of a file path, the local connection string may also be + a database alias that is defined in + aliases.conf, as mentioned earlier. The format of + the alias depends only on how it's defined in the aliases file, not on + the server filesystem. Examples are: + + + + zappa + + + + blackjack.fdb + + + + poker + + + + Upon receiving a local connection string, the Firebird client + will first attempt to make a direct, embedded connection to the + database file, bypassing authentication but respecting the SQL + privileges and restrictions of the supplied user and/or role name. + That is, if the Engine12 provider is enabled + in firebird.conf or + databases.conf – which it is by default. If the + database file exists but the connection fails because the client + process doesn't have the required access privileges to the file, a + client-server connection is attempted (by the + Loopback provider), in this order: + + + + Using TCP/IP via localhost; + + + + On Windows: using WNET (NetBEUI), aka Named Pipes, on the + local machine; + + + + On Windows: using XNET (shared memory) on the local + machine. + + + + You can force Firebird to use a certain protocol (and skip the + embedded connection attempt) by prepending the protocol in URL + style: + + + URL-style connection strings + + + + + inet://zappa (TCP/IP connection using an + alias on the local machine) + + + + inet:///opt/firebird/examples/citylife.fdb + (TCP/IP connection using an absolute path on the local Posix + machine – notice the extra slash for the root dir) + + + + inet://C:\Work\Databases\Drills.fdb + (TCP/IP connection using an absolute path on the local Windows + machine) + + + + wnet://doggybase (NetBEUI – named pipes – + connection using an alias on the local Windows machine) + + + + wnet://D:\Fun\Games.fdb (NetBEUI – named + pipes – connection using an absolute path on the local Windows + machine) + + + + xnet://security.db (XNET connection using + an alias on the local Windows machine) + + + + xnet://C:\Programmas\Firebird\Firebird_3_0\security3.fdb + (XNET connection using the full path on the local Windows + machine) + + + + + If your XNET connections fail, it may be because the local + protocol isn't working properly on your machine. If you're running + Windows Vista, 2003 or XP with terminal services enabled, this can + often be fixed by setting IpcName to + Global\FIREBIRD in the configuration file + firebird.conf (don't forget to uncomment the + parameter and restart the server). + + If setting IpcName doesn't help and you + don't get the local protocol enabled, you can usually work around + the problem by using inet://, + wnet://, or putting + localhost: before your database + paths or aliases, thus turning them into TCP/IP connection strings + (discussed below). + +
+ +
+ <indexterm> + <primary>Server name and path</primary> + </indexterm><indexterm> + <primary>TCP/IP</primary> + </indexterm>TCP/IP connection strings + + A TCP/IP connection string consists of: + + + + a server name or IP address + + + + an optional slash (/) plus + port number or service name + + + + a colon (:) + + + + either the absolute path + filename on the server machine, + or an alias defined on the server machine. + + + + Examples: + + + + On Linux/Unix: + +
+ pongo:/opt/firebird/examples/empbuild/employee.fdb + + bongo/3052:fury + + 112.179.0.1:/var/Firebird/databases/butterflies.fdb + + localhost:blackjack.fdb +
+ + + + On Windows: + +
+ siamang:C:\Biology\Data\Primates\Apes\populations.fdb + + sofa:D:\Misc\Friends\Rich\Lenders.fdb + + inca/fb_db:D:\Traffic\Roads.fdb + + 127.0.0.1:Borrowers +
+ + + + + Aliases + + Databases + + aliases + Notice how the aliased connection strings don't give any + clue about the server OS. And they don't have to, either: you talk to + a Linux Firebird server just like you talk to a Windows Firebird + server. In fact, specifying an explicit database path is one of the + rare occasions where you have to be aware of the difference. +
+ +
+ <indexterm> + <primary>Server name and path</primary> + </indexterm><indexterm> + <primary>NetBEUI</primary> + </indexterm>NetBEUI connection strings + + A NetBEUI (named pipes) connection string consists of: + + + + two backslashes + (\\) + + + + a server name or IP address + + + + an optional at sign (@) + plus port number or service name + + + + another backslash + (\) + + + + either the absolute path + filename on the server machine, + or an alias defined on the server machine. + + + + Examples: + + + + On Windows, the exact same databases as in the TCP/IP + examples: + +
+ \\siamang\C:\Biology\Data\Primates\Apes\populations.fdb + + \\sofa\D:\Misc\Friends\Rich\Lenders.fdb + + \\inca@fb_db\D:\Traffic\Roads.fdb + + \\127.0.0.1\Borrowers +
+ + +
+ +
+ <indexterm> + <primary>Server name and path</primary> + </indexterm><indexterm> + <primary>URL-style connection strings</primary> + </indexterm>URL-style connection strings + + Local URL-style connection strings have already been + introduced. + + A remote URL-style connection string consists of: + + + + a protocol name (inet or + wnet) followed by a colon and two slashes + (://) + + + + a server name or IP address + + + + an optional colon (:) plus + port number or service name + + + + a slash (/) + + + + either the absolute path + filename on the server machine, + or an alias defined on the server machine. + + + + Examples: + + + + On Linux/Unix: + +
+ inet://pongo//opt/firebird/examples/empbuild/employee.fdb + + inet://bongo:3052/fury + + inet://112.179.0.1//var/Firebird/databases/butterflies.fdb + + inet://localhost/blackjack.fdb +
+ + + + On Windows: + +
+ inet://siamang/C:\Biology\Data\Primates\Apes\populations.fdb + + inet://sofa:4044/D:\Misc\Friends\Rich\Lenders.fdb + + wnet://inca:fb_db/D:\Traffic\Roads.fdb + + wnet://127.0.0.1/Borrowers +
+ + + + Since XNET is a purely local protocol, you can't have remote + connection strings starting with xnet://. +
+ +
+ Third-party programs + + Please be aware that some third-party client programs may have + different requirements for the composition of connection strings. + Refer to their documentation or online help to find out. +
+
+ +
+ <indexterm> + <primary>Connecting</primary> + </indexterm><indexterm> + <primary>Databases</primary> + + <secondary>connecting</secondary> + </indexterm>Connecting to an existing database + + + Databases + + example database + + Sample database + + Example database + A sample database named employee.fdb + is located in the examples/empbuild subdirectory of your + Firebird installation. It is also reachable under its alias + employee. You can use this database to try + your wings. + + If you move or copy the sample database, be sure to place it on a + hard disk that is physically attached to your server machine. Shares, + mapped drives or (on Unix) mounted SMB (Samba) file systems will not + work. The same rule applies to any databases that you create or + use. + + Connecting to a Firebird database requires – implicit or explicit + – authentication. In order to work with objects inside the database, + such as tables, views and functions, you (i.e. the Firebird user you're + logged in as) need explicit permissions on those objects, unless you own + them (you own an object if you have created it) or if you're connected + as user SYSDBA or with the role + RDB$ADMIN. In the example database + employee.fdb, sufficient permissions have been + granted to PUBLIC (i.e. anybody who cares to + connect) to enable you to view and modify data to your heart's + content. + + For simplicity here, we will look at authenticating as SYSDBA using the password + masterkey. Also, to keep the lines in the examples + from running off the right edge, we will work with local databases and + use aliases wherever possible. Of course everything you'll learn in + these sections can also be applied to remote databases, simply by + supplying a full TCP/IP connection string. + +
+ <indexterm> + <primary>isql</primary> + + <secondary>connecting to a database</secondary> + </indexterm><indexterm> + <primary>Databases</primary> + + <secondary>connecting</secondary> + + <tertiary>with isql</tertiary> + </indexterm>Connecting with <application>isql</application> + + Firebird ships with a text-mode client named + isql (Interactive SQL utility). You can use it + in several ways to connect to a database. One of them, shown below, is + to start it in interactive mode. Go to the directory where the + Firebird tools reside (see Default + disk locations if necessary) and type isql + (Windows) or ./isql (Linux) at the command + prompt. + + [In the following examples, ↵ means hit + Enter] + + + Connecting + + CONNECT statement + + + + SQL + + CONNECT statement + + + C:\Programmas\Firebird\Firebird_3_0>isql↵ +Use CONNECT or CREATE DATABASE to specify a database +SQL>connect xnet://employee user sysdba password masterkey;↵ + + + + + In isql, every SQL statement + must end with a semicolon. If you hit Enter and + the line doesn't end with a semicolon, isql assumes that the + statement continues on the next line and the prompt will change + from SQL> to CON>. This + enables you to split long statements over multiple lines. If you + hit Enter after your statement and you've + forgotten the semicolon, just type it after the + CON> prompt on the next line and press + Enter again. + + + + If the connection string doesn't start with a host or + protocol name, a direct serverless connection to the database is + attempted. This may fail if your OS login doesn't have + sufficient access rights to the database file. In that case, + connect to + localhost:path-or-alias + or specify a protocol like xnet:// (Windows + only) or inet://. Then the server process + (usually running as user firebird on Posix or LocalSystem on Windows) will open + the file. On the other hand, network-style connections may fail + if a user created the database in direct-access mode and the + server doesn't have enough access rights. + + + + + + You can optionally enclose the path, the user name and/or the + password in single (') or double + (") quotes. If the path contains spaces, quoting + is mandatory. Case-sensitive user names (created like this: + create user "Jantje" password ...) and user names + with spaces, international characters or other funny + stuff also need to be double-quoted. + + + At this point, isql will inform you + that you are connected: + + Database: xnet://employee, User: SYSDBA +SQL> + + You can now continue to play about with the + employee database. With + isql you can query data, get information + about the metadata, create database objects, run data definition + scripts and much more. + + To get back to the OS command prompt, type: + + SQL>quit;↵ + + You can also type EXIT instead of + QUIT, the difference being that + EXIT will first commit any open transactions, + making your modifications permanent. +
+ +
+ <indexterm> + <primary>Databases</primary> + + <secondary>connecting</secondary> + + <tertiary>with a GUI client</tertiary> + </indexterm>Connecting with a GUI client + + Some GUI client tools take charge of composing the + CONNECT string for you, using server, path (or + alias), user name and password information that you type into + prompting fields. Supply the various elements as described in the + preceding topic. + + + Notes + + + + It is also quite common for such tools to expect the + entire server + path/alias as a single connection string – just + like isql does. + + + + Remember that file names and commands on Linux and other + Unix-like platforms are case-sensitive. + + + +
+
+ +
+ <indexterm> + <primary>isql</primary> + + <secondary>creating a database</secondary> + </indexterm><indexterm> + <primary>Databases</primary> + + <secondary>creating with isql</secondary> + </indexterm>Creating a database using + <application>isql</application> + + There is more than one way to create a database with + isql. Here, we will look at one simple way to + create a database interactively – although, for your serious database + definition work, you should create and maintain your metadata objects + using data definition scripts. + +
+ Starting <application>isql</application> + + To create a database interactively using the + isql command shell, type + isql (Windows) or ./isql (Linux) + at the command prompt in the directory where the Firebird tools + are. + + [In the following examples, ↵ means hit + Enter] + + C:\Programmas\Firebird\Firebird_3_0>isql↵ +Use CONNECT or CREATE DATABASE to specify a database +
+ +
+ <indexterm> + <primary>CREATE DATABASE statement</primary> + </indexterm><indexterm class="singular" scope="local"> + <primary>SQL</primary> + + <secondary>CREATE DATABASE statement</secondary> + </indexterm>The CREATE DATABASE statement + + Now you can create your new database interactively. Let's + suppose that you want to create a database named + test.fdb and store it in a directory named + data on your D drive: + + SQL>create database 'D:\data\test.fdb' page_size 8192↵ +CON>user 'sysdba' password 'masterkey';↵ + + + + + In the CREATE DATABASE statement it + is mandatory to place quote characters + (single or double) around path and password. This is different + from the CONNECT statement. Quoting the + user name is optional, unless it is case-sensitive or contains + spaces, international characters or any other character that is + not allowed in an unquoted identifier. + + + + If the connection string doesn't start with a host or + protocol name, creation of the database file is attempted with + your OS login as the owner. This may or may not be what you want + (think of access rights if you want others to be able to + connect). If you prepend localhost: or a protocol to the + path or alias, the server process will create and own the + file. + + + + + The database will be created and, after a few moments, the SQL + prompt will reappear. You are now connected to the new database and + can proceed to create some test objects in it. + + But to verify that there really is a database there, let's first + type in this query: + + SQL>select * from rdb$relations;↵ + + + Databases + + system tables + + Databases + + metadata + + System tables + Although you haven't created any tables yet, the screen + will fill up with a large amount of data! This query selects all of + the rows in the system table RDB$RELATIONS, where + Firebird stores the metadata for tables. An empty + database is not really empty: it contains a number of system tables + and other objects. The system tables will grow as you add more user + objects to your database. + + To get back to the command prompt type QUIT + or EXIT, as explained in the section on + connecting. +
+ +
+ Creating a database as a non-privileged user + + In Firebird 3, if you try to create a database other than in + embedded mode as someone who is not a Firebird admin (i.e. + SYSDBA or an account with equal rights), you may + be in for a surprise: + + SQL>create database 'xnet://D:\data\mydb.fdb' user 'john' password 'lennon';↵ +Statement failed, SQLSTATE = 28000 +no permission for CREATE access to DATABASE D:\DATA\MYDB.FDB + + Non-admin users must explicitly be granted the right to create + databases by a Firebird admin: + + SQL>grant create database to user john;↵ + + After that, they can create databases. + + Notice that with a serverless connection, i.e. without + specifying a host name or protocol before the database name (and + Engine12 enabled!), Firebird won't deny any + CREATE DATABASE statement. It will only fail if + the client process doesn't have sufficient rights in the directory + where the database is to be created. +
+
+ +
+ <indexterm class="singular" scope="local"> + <primary>SQL</primary> + </indexterm><indexterm class="singular" scope="local"> + <primary>Firebird SQL</primary> + </indexterm>Firebird SQL + + Every database management system has its own idiosyncrasies in the + ways it implements SQL. Firebird adheres to the SQL standard more + rigorously than most other RDBMSes. Developers migrating from products + that are less standards-compliant often wrongly suppose that Firebird is + quirky, whereas many of its apparent quirks are not quirky at + all. + +
+ <indexterm> + <primary>Integer division</primary> + </indexterm>Division of an integer by an integer + + Firebird accords with the SQL standard by truncating the result + (quotient) of an integer/integer calculation to the next lower + integer. This can have bizarre results unless you are aware of + it. + + For example, this calculation is correct in SQL: + +
+ 1 / 3 = 0 +
+ + If you are upgrading from an RDBMS which resolves + integer/integer division to a float quotient, you will need to alter + any affected expressions to use a float or scaled numeric type for + either dividend, divisor, or both. + + For example, the calculation above could be modified thus in + order to produce a non-zero result: + +
+ 1.000 / 3 = 0.333 +
+
+ +
+ <indexterm> + <primary>Strings</primary> + </indexterm>Things to know about strings + +
+ <indexterm> + <primary>Strings</primary> + + <secondary>delimiter symbol</secondary> + </indexterm>String delimiter symbol + + Strings in Firebird are delimited by a pair of single quote + (apostrophe) symbols: 'I am a string' (ASCII code + 39, not 96). If you used earlier versions of + Firebird's relative, InterBase®, you might recall that double and + single quotes were interchangeable as string delimiters. Double + quotes cannot be used as string delimiters in Firebird SQL + statements. +
+ +
+ <indexterm> + <primary>Apostrophes in strings</primary> + </indexterm><indexterm> + <primary>Strings</primary> + + <secondary>apostrophes in strings</secondary> + </indexterm>Apostrophes in strings + + If you need to use an apostrophe inside a Firebird string, you + can escape the apostrophe character by preceding it + with another apostrophe. + + For example, this string will give an error: + +
+ 'Joe's Emporium' +
+ + because the parser encounters the apostrophe and interprets + the string as 'Joe' followed by some unknown + keywords. To make it a legal string, double the apostrophe + character: + +
+ 'Joe''s Emporium' +
+ + Notice that this is TWO single quotes, not one + double-quote. +
+ +
+ <indexterm> + <primary>Strings</primary> + + <secondary>concatenation</secondary> + </indexterm>Concatenation of strings + + The concatenation symbol in SQL is two pipe + symbols (ASCII 124, in a pair with no space between). In SQL, the + + symbol is an arithmetic operator and it will cause + an error if you attempt to use it for concatenating strings. The + following expression prefixes a character column value with the + string Reported by: : + +
+ 'Reported by: ' || LastName +
+ + Firebird will raise an error if the result of a string + concatenation exceeds the maximum (var)char size of 32 Kb. If only + the potential result – based on variable or + field size – is too long you'll get a warning, but the operation + will be completed successfully. (In pre-2.0 Firebird, this too would + cause an error and halt execution.) + + See also the section below, , + about concatenating in expressions involving + NULL. +
+ +
+ <indexterm> + <primary>Double-quoted identifiers</primary> + </indexterm>Double-quoted identifiers + + Before the SQL-92 standard, it was not legal to have object + names (identifiers) in a database that duplicated keywords in the + language, were case-sensitive or contained spaces. SQL-92 introduced + a single new standard to make any of them legal, provided that the + identifiers were defined within pairs of double-quote symbols (ASCII + 34) and were always referred to using double-quote + delimiters. + + The purpose of this gift was to make it easier + to migrate metadata from non-standard RDBMSes to standards-compliant + ones. The down-side is that, if you choose to define an identifier + in double quotes, its case-sensitivity and the enforced + double-quoting will remain mandatory. + + Firebird does permit a slight relaxation under a very limited + set of conditions. If the identifier which was defined in + double-quotes: + + + + was defined as all upper-case, + + + + is not a keyword, and + + + + does not contain any spaces, + + + + ...then it can be used in SQL unquoted and case-insensitively. + (But as soon as you put double-quotes around it, you must match the + case again!) + + + Don't get too smart with this! For instance, if you have + tables "TESTTABLE" and + "TestTable", both defined within + double-quotes, and you issue the command: + +
+ SQL>select * from TestTable; +
+ + ...you will get the records from + "TESTTABLE", not + "TestTable"! + + + Unless you have a compelling reason to define quoted + identifiers, it is recommended that you avoid them. Firebird happily + accepts a mix of quoted and unquoted identifiers – so there is no + problem including that keyword which you inherited from a legacy + database, if you need to. + + + Some database admin tools enforce double-quoting of + all identifiers by default. Try to choose a + tool which makes double-quoting optional. + +
+
+ +
+ <indexterm> + <primary>NULL</primary> + </indexterm>Expressions involving <constant>NULL</constant> + + In SQL, NULL is not a value. It is a + condition, or state, of a data item, in which its + value is unknown. Because it is unknown, NULL + cannot behave like a value. When you try to perform arithmetic on + NULL, or involve it with values in other + expressions, the result of the operation will almost always be + NULL. It is not zero or blank or an empty + string and it does not behave like any of these values. + + Below are some examples of the types of surprises you will get + if you try to perform calculations and comparisons with + NULL. + + The following expressions all return + NULL: + + + + 1 + 2 + 3 + + NULL + + + + not (NULL) + + + + 'Home ' || 'sweet ' || + NULL + + + + You might have expected 6 from the first expression and + Home sweet from the third, but as + we just said, NULL is not like the number 0 or an + empty string – it's far more destructive! + + The following expression: + + + + FirstName || ' ' || LastName + + + + will return NULL if either + FirstName or LastName is + NULL. Otherwise it will nicely concatenate the + two names with a space in between – even if any one of the variables + is an empty string. + + + Think of NULL as + UNKNOWN and these strange results suddenly + start to make sense! If the value of Number is + unknown, the outcome of '1 + 2 + 3 + Number' is + also unknown (and therefore NULL). If the + content of MyString is unknown, then so is + 'MyString || YourString' (even if + YourString is non-NULL). + Etcetera. + + + Now let's examine some PSQL (Procedural SQL) examples with + if-constructs: + + + + if (a = b) then + MyVariable = 'Equal'; +else + MyVariable = 'Not equal'; + + After executing this code, MyVariable + will be 'Not equal' if both + a and b are + NULL. The reason is that 'a = + b' yields NULL if at least one of + them is NULL. If the test expression of an + if statement is + NULL, it behaves like + false: the 'then' block is + skipped, and the 'else' block executed. + + + Although the expression may behave + like false in this case, it's still + NULL. If you try to invert it using + not(), what you get is another + NULL – not + true. + + + + + if (a <> b) then + MyVariable = 'Not equal'; +else + MyVariable = 'Equal'; + + Here, MyVariable will be + 'Equal' if a is + NULL and b isn't, or vice + versa. The explanation is analogous to that of the previous + example. + + + +
+ The <database>DISTINCT</database> keyword comes to the + rescue! + + Firebird 2 and above implement a new use of the + DISTINCT keyword allowing you to perform + (in)equality tests that take NULL into account. + The semantics are as follows: + + + + Two expressions are DISTINCT if they + have different values or if one is NULL and + the other isn't; + + + + They are NOT DISTINCT if they have + the same value or if they are both + NULL. + + + + Notice that if neither operand is NULL, + DISTINCT works exactly like the + <> operator, and + NOT DISTINCT like the + = operator. + + DISTINCT and NOT + DISTINCT always return true or + false, never NULL. + + Using DISTINCT, you can rewrite the first PSQL + example as follows: + + if (a is not distinct from b) then + MyVariable = 'Equal'; +else + MyVariable = 'Not equal'; + + And the second as: + + if (a is distinct from b) then + MyVariable = 'Not equal'; +else + MyVariable = 'Equal'; + + These versions will give you the results that a normal (i.e. + not SQL-brainwashed) human being would expect, whether there are + NULLs involved or not. +
+ +
+ More about <constant>NULL</constant>s + + A lot more information about NULL + behaviour can be found in the Firebird Null + Guide, at these locations: + +
+ http://www.firebirdsql.org/manual/nullguide.html + (HTML) + + http://www.firebirdsql.org/pdfmanual/Firebird-Null-Guide.pdf + (PDF) + + +
+
+
+
+
+ +
+ Protecting your data + +
+ <indexterm> + <primary>Backup</primary> + </indexterm><indexterm> + <primary>Restore</primary> + </indexterm><indexterm> + <primary>Databases</primary> + + <secondary>backup and restore</secondary> + </indexterm>Backup + + Firebird comes with two utilities for backing up and restoring + your databases: gbak and + nbackup. Both can be found in the bin subdirectory of your Firebird + installation. Firebird databases can be backed up while users are + connected to the system and going about their normal work. The backup + will be taken from a snapshot of the database at the time the backup + began. + + Regular backups and occasional restores should be a scheduled part + of your database management activity. + + + Except in nbackup's lock mode, do not use external proprietary + backup utilities or file-copying tools such as + WinZip, tar, + copy, xcopy, + etc., on a database which is running. Not only will the backup be + unreliable, but the disk-level blocking used by these tools can + corrupt a running database. + + + + Study the warnings in the next section about database activity + during restores! + + + More information about gbak can be + found here (HTML and PDF version, same content): + +
+ http://www.firebirdsql.org/manual/gbak.html + + http://www.firebirdsql.org/pdfmanual/Firebird-gbak.pdf + + +
+ + The nbackup manual is here (again same + content in HTML and PDF): + +
+ http://www.firebirdsql.org/manual/nbackup.html + + http://www.firebirdsql.org/pdfmanual/Firebird-nbackup.pdf + + +
+
+ +
+ <indexterm> + <primary>Databases</primary> + + <secondary>corruption</secondary> + </indexterm>How to corrupt a database + + The following sections constitute a summary of things + not to do if you want to keep your Firebird + databases in good health. + +
+ <indexterm> + <primary>Forced writes</primary> + </indexterm>Disabling forced writes + + Firebird is installed with forced writes (synchronous writes) + enabled by default. Modifications are written to disk immediately upon + posting. + + It is possible to configure a database to use asynchronous data + writes – whereby modified or new data are held in the memory cache for + periodic flushing to disk by the operating system's I/O subsystem. The + common term for this configuration is forced writes + off (or disabled). It is sometimes + resorted to in order to improve performance during large batch + operations. + +
+ Disabling forced writes on Windows + + The big warning here is: do not disable + forced writes on a Windows server. It has been observed that the + Windows server platforms do not flush the write cache until the + Firebird service is shut down. Apart from power interruptions, there + is just too much that can go wrong on a Windows server. If it should + hang, the I/O system goes out of reach and your users' work will be + lost in the process of rebooting. +
+ +
+ Disabling forced writes on Linux + + Linux servers are safer for running an operation with forced + writes disabled temporarily. Still, do not leave it disabled once + your large batch task is completed, unless you have a very robust + fall-back power system. + + + + +
+
+ +
+ <indexterm> + <primary>Restore</primary> + + <secondary>to a running database</secondary> + </indexterm><indexterm> + <primary>Databases</primary> + + <secondary>backup and restore</secondary> + </indexterm>Restoring a backup to a running database + + One of the restore options in the + gbak utility (gbak + -rep[lace_database]) allows you to restore a gbak + file over the top of an existing database. It is possible for this + style of restore to proceed without warning while users are logged in + to the database. Database corruption is almost certain to be the + result. + + + Notice that the shortest form of this command is + gbak -rep, not + gbak -r as it used to be in + previous Firebird versions. What happened to gbak + -r? It is now short for gbak + -recreate_database, which functions the same as + gbak -c[reate] and throws an + error if the specified database already exists. You can force + overwriting of the existing database by adding the + o[verwrite] flag though. This flag is only + supported with gbak -r, not + with gbak -c. + + These changes have been made because many users thought that + the -r switch meant restore + instead of replace – and only found out otherwise when it was too + late. + + + + Be aware that you will need to design your admin tools and + procedures to prevent any possibility for any user (including + SYSDBA) to restore to your active database if + any users are logged in. + + + If is practicable to do so, it is recommended to restore to + spare disk space using the gbak + -c[reate] option and test the restored database + using isql or your preferred admin tool. If + the restored database is good, shut down the old database (you can use + the gfix command-line tool for this; see + http://www.firebirdsql.org/manual/gfix.html + or http://www.firebirdsql.org/pdfmanual/Firebird-gfix.pdf). + Make a filesystem copy of the old database just in case and then copy + the restored database file(s) over their existing counterparts. + + +
+ +
+ <indexterm> + <primary>Restore</primary> + + <secondary>user logins during restore</secondary> + </indexterm><indexterm> + <primary>Databases</primary> + + <secondary>backup and restore</secondary> + </indexterm>Allowing users to log in during a restore + + If you do not block access to users while performing a restore + using gbak -rep[lace_database] + then users may be able to log in and attempt to do operations on data. + Corrupted structures will result. +
+
+
+ +
+ <indexterm> + <primary>Help</primary> + </indexterm><indexterm> + <primary>Documentation</primary> + </indexterm>How to get help + + The community of willing helpers around Firebird goes a long way + back, to many years before the source code for its ancestor, InterBase® 6, + was made open source. Collectively, the Firebird community does have all + the answers! It even includes some people who have been involved with it + since it was a design on a drawing board in a bathroom in Boston. + + + + Visit the official Firebird Project site at http://www.firebirdsql.org + and join the user support lists, in particular firebird-support. Look at http://www.firebirdsql.org/en/mailing-lists/ + for instructions. + + + + Use the Firebird documentation index at http://www.firebirdsql.org/en/documentation/. + + + + Visit the Firebird knowledge site at http://www.ibphoenix.com to + look up a vast collection of information about developing with and + using Firebird. IBPhoenix also sells a Developer CD with the Firebird + binaries and lots of documentation. + + + + + Books + + The Firebird Book + + Firebird Book + Order the official three-volume Firebird + Book, Second Edition at http://www.ibphoenix.com/products/books/firebird_book, + for more than 1200 pages jam-packed with Firebird information. + (Notice: at the time of this writing, the + Firebird Book is not yet up-to-date with + Firebird 3.) + + + + Read the Release Notes for your Firebird version! + + +
+ +
+ <indexterm> + <primary>Help</primary> + </indexterm><indexterm> + <primary>Support Firebird</primary> + </indexterm><indexterm> + <primary>Firebird Foundation</primary> + </indexterm>How to give help + + Firebird exists, and continues to be improved, thanks to a community + of volunteers who donate their time and skills to bring you this wonderful + piece of software. But volunteer work alone is not enough to keep an + enterprise-level RDBMS such as Firebird up-to-date. The Firebird + Foundation supports Firebird development financially by + issuing grants to designers and developers. If Firebird is useful to you + and you'd like to give something back, please visit the Foundation's pages + and consider making a donation or becoming a member or sponsor. +
+ +
+ <indexterm scope="local"> + <primary>Project</primary> + </indexterm><indexterm> + <primary>Firebird project</primary> + </indexterm>The Firebird Project + + The developers, designers and testers who gave you Firebird and + several of the drivers are members of the Firebird open source project at + SourceForge, that amazing virtual community that is home to thousands of + open source software teams. The Firebird project's address there is http://sourceforge.net/projects/firebird/. + At that site are the source code tree, the download packages and a number + of technical files related to the development and testing of the code + bases. + + The Firebird Project developers and testers use an email list forum + – firebird-devel@lists.sourceforge.net – as + their virtual laboratory for communicating with one another + about their work on enhancements, bug-fixing and producing new versions of + Firebird. + + Anyone who is interested in watching their progress can join this + forum. However, user support questions are a distraction which they do not + welcome. Please do not try to post your user support questions there! + These belong in the firebird-support group. + + Happy Firebirding! +
+ + + <indexterm> + <primary>Document history</primary> + </indexterm>Document History + + The exact file history is recorded in the manual module in our CVS tree; see http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/quickstartguide-2.5.xml?view=log + + + + 0.0 + + 2002 + + IBP + + + Published as Chapter One of Using + Firebird. + + + + + 1.0 + + 2003 + + IBP + + + Published separately as a free Quick Start Guide. + + + + + 1.x + + June 2004 + + IBP + + + Donated to Firebird Project by IBPhoenix. + + + + + 2.0 + + 27 Aug 2004 + + PV + + + Upgraded to Firebird 1.5 + + Added Classic vs. Superserver section. + + Reorganised and corrected Disk Locations Table. + + Added (new) screenshots. + + Added section on security. + + Updated and completed information on Control Panel + applets. + + Added more examples to Expressions involving + NULL. + + Various other corrections and additions. + + + + + 2.1 + + 20 Feb 2005 + + PV + + + Enhanced GSEC section. + + Added more info to CONNECT and + CREATE DATABASE sections. + + Added version number and document history. + + + + + 2.1.1 + + 1 Mar 2005 + + PV + + + Changed gbak r[estore] to + r[eplace] in two places. + + + + + 2.1.2 + + 8 Apr 2005 + + PV + + + Reordered Firebird SQL subsections. + + Added links to Firebird Null Guide. + + + + + 2.2 + + 2 Dec 2005 + + PV + + + Removed "Using the books by IBPhoenix" as it doesn't make + sense in the QSG. + + Promoted "How to get help" to 1st-level section and removed + "Where to next" shell. + + Removed link to UFB and RefGuide; added a note instead + explaining their current status. + + Updated/corrected classic-super comparison table. + + Moved a number of sections on installing, working with + databases, and (un)safety into newly created top-level + sections. + + + + + 2.2.1 + + 22 Dec 2005 + + PV + + + Corrected statement on SS thread usage in + Classic-vs-Superserver table. + + Fixed broken link. + + + + + 3.0 + + 21 May 2006 + + PV + + + Creation of 2.0 Quick Start Guide, still equal to previous + revision except for some version numbers, XML ids etc. + + + + + 3.2 + + 10 Aug 2006 + + PV + + + Promoted Firebird Project members to + co-authors in articleinfo. + + Updated references to website + (firebird.sourceforge.net -> + www.firebirdsql.org). + + Removed maturity and Service + Manager rows from Classic-vs-Super table; these things are + no longer different in Firebird 2. Also changed the row on local + connections: CS and SS now both allow safe, reliable local + connections on Windows. Added row on Guardian. Prepended a column + with feature names. + + Removed any and all remarks about Classic not having a + (full) Service Manager. + + Removed 2nd paragraph of Default disk + locations section. + + Removed notes stating that Classic/Win connections will fail + without a host name. + + Updated location table and inserted rows for + documentation. + + Edited the Installation sections; added sections on Guardian + and installing multiple servers. Removed + if-you-do-not-find-the-release-notes tip. + + Heavily edited and extended the Testing your + installation sections. + + The Other things you need section is now gone + and its contents distributed across other sections. + + Added a section on gsec (consisting partly of existing + material). + + Greatly enhanced and extended the + Security section, and moved it to another + location. + + Extended and improved the Windows Control Panel + applets section. + + Edited Working with databases. Added a + special section on connection strings. Added information on access + to database objects, the EXIT statement, and + local vs. remote connections. Made some paths in the examples + relative, to keep the lines short. Extended paragraph on + metadata. + + Weakened the claim that Firebird is more SQL-compliant than + any other RDBMS. + + Changed the Expressions involving + NULL section. Added a subsection on + DISTINCT. Changed More about + NULLs subsection somewhat. + + Renamed Safety measures to Preventing + data loss. The Security subsection has been moved + elsewhere. + + Extended Backup section to include + nbackup information. Added links to other documentation. + + In the How to corrupt... part, changed gbak + -r syntax to -rep and added explanatory note. + + Added the IB6 plus rlsnotes as last-resort + option to How to get help. Also mentioned + firebird-support explicitly. + + Corrected more version numbers, paths, and stuff. + + Many sections have been reshuffled, moved up or down the + hierarchy, etc. Many smaller modifications are not listed + here. + + Added Happy Firebirding! to conclude the last + section. + + + + + 3.3 + + 15 Oct 2006 + + PV + + + Default disk locations table: added isql to command line + tools; added row for additional server-side libs. + + Added introductory paragraph to Installing + Firebird. Changed first sentence of Installing on + Linux... + + Changed and extended Server check: Linux and other + Unices. + + Corrected and extended the section on Linux client-only + installs. + + Security section: moved last paragraph of the Protect + databases... listitem into a new item on Classic local + mode. + + Connection strings: improved and extended introductory + paragraph; added a subsection on third party program + requirements. + + Changed 3rd and 4th paragraph of Connecting to an + existing database. Used relative paths in connection + examples. Updated/corrected note on the use of quote + characters. + + Edited first Important item in The + CREATE DATABASE statement. + + Updated the warning about concatenation of long + strings. + + Extended the note in Restoring a backup to a running + database. + + Updated last sentence of first paragraph in The + Firebird Project. + + + + + 3.4 + + 25 Jan 2007 + + PV + + + About this guide: Changed note about + versions and replaced HTML and PDF links with single link to new + doc index page. + + Classic or Superserver?: Replaced + note on Embedded Server with a proper subsection, containing more + info and links to UFB. + + Default disk locations: Created two + subsections (for Linux and Windows); also split table in two and + removed first column. Introduced placeholders <ProgramDir> and <SystemDir>. Changed text + around tables, changed existing note, and added note for Win64 + users. + + Security: Removed statement that 1.5 + Release Notes are included with 2.x packages. + + More about + NULLs: Replaced note about the + Null Guide being updated with a para announcing the availability + of the new version. + + Backup: Updated information on + UFB. + + How to get help: Updated + documentation links and changed text here and there. + + + + + 3.5 + + 14 Mar 2007 + + PV + + + About this guide and + Important notice for 64-bit Windows users: + Minor rewordings. + + User management: gsec and + Connection strings: Added information on + enabling local protocol with + IpcName=Global\FIREBIRD. + + Security :: Use database aliases: + Changed type from <database> to + <literal> to improve output. + + + + + 3.6 + + 21 Sep 2007 + + PV + + + About this guide: Mentioned 2.0.3. + Warned against 2.0.2. + + Expressions involving + NULL: Space added to expected + concatenation result: Home sweet + . + + + + + 3.7 + + 8 Apr 2008 + + PV + + + About this guide: Added 2.0.4 and 2.1 + to covered versions. Mentioned forced writes bug. + + Installing the Firebird server :: Use the + Guardian?: Added warning about Win installer not + detecting existing server. + + How to corrupt a database?: Gave + subsections id + attributes. + + Disabling forced writes on Windows: + Created new parent section Disabling forced + writes, with the Windows and Linux cases as + subsections. Warned against Linux forced writes bug. + + License notice: Copyright end year + now 2008. + + + + + 3.8 + + 18 Jan 2009 + + PV + + + About this guide: Added 2.0.5 and + 2.1.2 to covered versions. + + Preventing data loss :: Backup: + Mentioned nbackup's brokenness in 2.1. + + How to corrupt a database :: Restoring a backup + to a running database: Changed and extended + instructions re. safe restoring. + + How to give help: New section + directing reader to the Foundation. + + License notice: Copyright end year + now 2009. + + + + + 3.9 + + 4 Sep 2010 + + PV + + + About this guide: Added 2.0.6 and + 2.1.3 to covered versions. + + Working with databases :: + Creating a database using + isql :: Starting + isql: Added ↵ means + Enter note, like in Connecting with + isql. + + Preventing data loss :: Backup: + Mentioned nbackup's still-brokenness in 2.1.1 and complete fix in + 2.1.2. + + How to get help: Last list item: + changed version ref. 2.0 to + 2.x. + + License notice: Copyright end year + now 2010. + + + + + 4.0 + + 5 Sep 2010 + + PV + + + Creation of 2.5 Quick Start Guide, still equal to previous + revision except for some version numbers, XML ids etc. Also + removed erroneous id from primary index term in + Document History title. + + + + + 4.1 + + 15 Sep 2010 + + PV + + + About this guide: Removed + 2.0-specific warnings. + + Upgraded and added information for version 2.5. [Details + still to be filled in] + + + + + 4.2 + + 21 Sep 2010 + + PV + + + Classic, SuperClassic or Superserver: + Moved the table into an appendix and left only a concise overview + here so first-time users can make a reasonable choice. Moved the + paragraph about installation packages into a separate + subsection. + + User management: gsec :: Trouble running + gsec: Improved/corrected first listitem. + + Firebird server architectures: New + appendix, containing the (slightly edited) table that used to be + in the Classic, SuperClassic or Superserver + section. + + + + + 4.3 + + 8 Jul 2011 + + PV + + + General: Added IDs to all sections that lacked one. + + About this guide: Changed ulink to + Firebird Doc Index. + + New top-level section: The Firebird + licenses. + + Classic, SuperClassic or Superserver? :: + Multiprocessing: Changed wording. + + Classic, SuperClassic or + Superserver?: After differences listing, changed + advice from flat-out SuperClassic to SuperClassic on 64-bit and + Superserver/Classic on 32-bit systems under high load. Split + paragraph into two. + + Classic, SuperClassic or Superserver? :: + Installation packages: Added instruction on switching + to SuperClassic on Linux. + + What is in the kit? now comes after + the Classic, SuperClassic or Superserver + section. Itemized list now has compact spacing; words + essential reading now wrapped in emphasis element instead of written in + all-caps. + + Default disk locations :: Linux: + Added that default install dir may vary per distribution. + + Installing Firebird :: Testing your installation + :: Note: Updated ulink to IB OpGuide (text and + url). + + Server configuration and management :: User + management: gsec :: Appointing co-administrators :: Differences + between co-administrators and + SYSDBA: Changed wording of 2nd + listitem. Completely rewrote and extended 3rd listitem. In Note, + changed wording of 2nd listitem slightly. + + Server configuration and management :: Security + :: Disable Classic local mode on Linux: Took out + reference to libfbembed + library. + + Server configuration and management :: Windows + Control Panel applets :: Firebird Server Manager: + Edited last para. + + Server configuration and management :: Windows + Control Panel applets :: Firebird Control Center: + Changed almost entire text. + + Server configuration and management :: + Administration tools: Updated ulink text and + url. + + Preventing data loss: Renamed + Protecting your data. + + Protecting your data :: How to corrupt a database + :: Disabling forced writes on Linux: Removed obsolete + indexterm to Linux Forced Writes bug. + + How to get help: Updated ulink to + mailing lists page (text and url). Updated ulink to Firebird Doc + Index (text and url). Updated link to Firebird Book and added + notice about first edition being out of print. Removed Note about + Using Firebird and Firebird + Reference Guide. + + How to give help: Updated Firebird + Foundation url. + + The Firebird Project: Added + terminating slash to ulink (text and url). + + Firebird Server Architectures: In + comparison table, added para in Multiprocessor / multicore row for + Classic/SuperClassic. Edited final two paragraphs. + + Document history: Link to CVS + changed, points directly to document log view in manual module + now. + + License notice: Copyright end year + now 2011. + + + + + 4.4 + + 26 Sep 2011 + + PV + + + articleinfo, + About this guide: Added 2.5.1 to covered + versions. + + Classic, SuperClassic or + Superserver?: Fixed typo in first para: Firebid -> + Firebird. + + Server configuration and management :: User + management: gsec :: Appointing co-administrators :: Differences + between co-administrators and + SYSDBA: Slightly changed wording + of 2nd listitem. + + Server configuration and management :: + Administration tools: Inspect -> Explore. In ulink + text: Downloads -> Download. + + Working with databases :: Firebird SQL :: + Expressions involving NULL :: The + DISTINCT keyword comes to the + rescue!: Wrapped + DISTINCT in title in database + element. Slightly altered wording in 2nd listitem. + + + + + 5.0 + + 11 Apr 2016 + + PV + + + Top-level sections up to and including Working + with databases extensively reworked to bring them up + to date with Firebird 3. Some sections have been moved or + completely removed. Mild reworking in other sections. + + + + + 5.1 + + 14 Apr 2016 + + PV + + + Installing Firebird :: Installing the Firebird + server :: Installing on Windows: corrected erroneous + figure dash. + + Server configuration and management :: User + management :: Adding Firebird user accounts :: + Examples: removed = + from set password =. + + Working with databases :: Connection strings :: + URL-style connection strings: changed indexterm + URL-style to URL-style connection + strings. Added same indexterm before the listing of local + URL-style connection strings in the earlier subsection + Local connection strings. + + + + + 5.2 + + .. Apr 2016 + + PV + + + Installing Firebird :: Installation + kits: changed/corrected the package names and added a + para after the blockquote explaining about build and packaging + number. + + Installing Firebird :: Installing the Firebird + server :: Installing on Windows: updated image link + (now points to installer screenshot as it is in final 3.0.0 + release). + + Installing Firebird :: Installing the Firebird + server :: Installing on Linux and other Unix-like + platforms: Removed Note about Firebird 3 still being + in RC2 stage. + + Server configuration and management :: Security + :: Disable embedded connections: mash mark -> hash + mark. + + Working with databases :: Creating a database + using isql :: Creating a database as a non-privileged + user: Added other than in embedded mode + to first para. Prepended xnet:// + to database path in example creation attempt. Added (and + Engine12 enabled!) to last para. + + + + + + + <indexterm> + <primary>License notice</primary> + </indexterm>License notice + + The contents of this Documentation are subject to the Public + Documentation License Version 1.0 (the License); you may + only use this Documentation if you comply with the terms of this License. + Copies of the License are available at http://www.firebirdsql.org/pdfmanual/pdl.pdf + (PDF) and http://www.firebirdsql.org/manual/pdl.html + (HTML). + + The Original Documentation is titled Firebird Quick Start + Guide. + + The Initial Writer of the Original Documentation is: IBPhoenix + Editors. + + Copyright (C) 2002-2004. All Rights Reserved. Initial Writer + contact: hborrie at ibphoenix dot com. + + Contributor: Paul Vinkenoog - see document history. + + Portions created by Paul Vinkenoog are Copyright (C) 2004-2016. All + Rights Reserved. Contributor contact: paul at vinkenoog dot nl. + + + + Alphabetical index + +
From 3ceb895f56dacd70fc2c0c4d87a6438aebc60219 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Mon, 25 Apr 2016 01:17:46 +0000 Subject: [PATCH 25/33] Added correct date to latest revision in revhistory (Release branch commit) --- src/docs/firebirddocs/quickstartguide-3.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/firebirddocs/quickstartguide-3.xml b/src/docs/firebirddocs/quickstartguide-3.xml index 94e09f0a..f5dd60aa 100644 --- a/src/docs/firebirddocs/quickstartguide-3.xml +++ b/src/docs/firebirddocs/quickstartguide-3.xml @@ -4129,7 +4129,7 @@ to turn FW on themselves. This must be in the general forced writes section (not 5.2 - .. Apr 2016 + 25 Apr 2016 PV From d5bf2927dfd8f62752902f7634e5679930052be5 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Tue, 10 May 2016 23:50:10 +0000 Subject: [PATCH 26/33] Removed erroneous include of html/param-refdocs.xsl --- src/docs/xsl/monohtml-refdocs.xsl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/docs/xsl/monohtml-refdocs.xsl b/src/docs/xsl/monohtml-refdocs.xsl index 9bc140ba..3a1c3abc 100644 --- a/src/docs/xsl/monohtml-refdocs.xsl +++ b/src/docs/xsl/monohtml-refdocs.xsl @@ -15,6 +15,7 @@ - + + From a02bde5cb3ded5d3f1bbcc849c237841a438cf4e Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Tue, 10 May 2016 23:51:26 +0000 Subject: [PATCH 27/33] Extended section ToCs in multi-page HTML build of documents in the refdocs set --- src/docs/xsl/html/param-refdocs.xsl | 33 ++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/src/docs/xsl/html/param-refdocs.xsl b/src/docs/xsl/html/param-refdocs.xsl index fdd43dbe..c261fb13 100644 --- a/src/docs/xsl/html/param-refdocs.xsl +++ b/src/docs/xsl/html/param-refdocs.xsl @@ -8,7 +8,7 @@ + + + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + chapter toc,title + part toc,title + preface toc,title + qandadiv toc + qandaset toc + reference toc,title + sect1 toc,title + sect2 toc + sect3 toc + sect4 toc + sect5 toc + section toc,title + set toc,title + + + + 2 + 2 + 2 + + From 5e5fa139b2681b8a314516e73fc9bd998988d507 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Mon, 13 Jun 2016 01:08:07 +0000 Subject: [PATCH 28/33] Updated some ulinks and removed Atkin section. --- src/docs/firebirddocs/docwriting-howto.xml | 89 ++++++++++------------ 1 file changed, 39 insertions(+), 50 deletions(-) diff --git a/src/docs/firebirddocs/docwriting-howto.xml b/src/docs/firebirddocs/docwriting-howto.xml index 242efe68..2f6f94b8 100644 --- a/src/docs/firebirddocs/docwriting-howto.xml +++ b/src/docs/firebirddocs/docwriting-howto.xml @@ -1,4 +1,6 @@ +
Firebird Docwriting Guide @@ -9,7 +11,7 @@ Vinkenoog - 5 May 2007 – Document version 1.3 + 12 Juni 2016 – Document version 1.4
http://www.firebirdsql.org/index.php?op=devel&sub=doc + url="http://www.firebirdsql.org/en/devel-docs/">http://www.firebirdsql.org/en/devel-docs/
It contains news about our activities, links to the docs we've @@ -190,42 +192,6 @@ parts of the guide that are of special importance to them.--> the list robot within minutes. Follow the instructions in that message and you're on the list. - -
- The Atkin news interface - - There's also a news interface for this and other Firebird-related - mailing lists. Sometimes it works a little problematically – or not at - all, although that's rare – and I wouldn't use it to post messages if I - were you, but it's great for archiving and browsing purposes. The - retention is pretty long too, so if you grab all messages that are on - the server you'll have a nice piece of list history from before you - joined. - - To access these newsgroups, point your favourite newsreader - to: - -
- news.atkin.com -
- - and get the groups list. Subscribe to the groups you like. Notice - that the firebird-docs list maps to the group sourceforge.firebird-doc - (without s) on the Atkin news server. - - Depending on the newsreader or browser you use, this link may also - get you straight to the group: - -
- news://news.atkin.com/sourceforge.firebird-doc -
- - You can post to the newsgroup even if you're not subscribed to the - mailing list, but in that case your message will be held for approval by - a human moderator. This means that your message will be delayed by up to - a day (or more, on rare occasions). -
@@ -2002,11 +1968,11 @@ Doth thy life destroy. LinuxQuestions.org poll: Database of the year 2003 - + - + - + @@ -2845,7 +2811,7 @@ your documentation. documentation to learn how to use it; that's one thing this guide doesn't cover. - +
@@ -3085,20 +3051,20 @@ your documentation.
http://developer.postgresql.org/cvsweb.cgi/pgsql-server/doc/src/sgml/ + url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=tree;f=doc/src;hb=HEAD">https://git.postgresql.org/gitweb/?p=postgresql.git;a=tree;f=doc/src;hb=HEAD
- Or check out the entire CVS tree, docs and all. For - instructions, go to: + Or clone the entire Git tree, docs and all. For instructions, go + to:
http://developer.postgresql.org/docs/postgres/cvs.html + url="https://www.postgresql.org/docs/devel/static/sourcerepo.html">https://www.postgresql.org/docs/devel/static/sourcerepo.html
-
+
Your copyright and the PDL If you contribute to the Firebird documention subproject, your @@ -3625,7 +3591,7 @@ your documentation. number of links contained in the other pages. But PDFs are often downloaded by the reader, and having files called qsg2.pdf or ubusetup.pdf in a - download directory or on ones desktop doesn't + download directory or on one's desktop doesn't really help to identify them as Firebird manuals. So here are some guidelines for the file names: @@ -4214,6 +4180,29 @@ fr:/pdfmanual/fr/Deinstaller-Firebird.pdf 2004–2007. + + + 1.4 + + 12 Jun 2016 + + PV + + + Where the docmakers meet :: The subproject + homepage: updated URL. + + Where the docmakers meet :: The Atkin news + interface: Removed this subsection. + + Copyright issues :: Using material written by + others :: PostgreSQL docs: updated the last two URL's + and the text line in between. + + License notice: (C) 2004–2007 -> + 2004–2016. + + @@ -4235,7 +4224,7 @@ fr:/pdfmanual/fr/Deinstaller-Firebird.pdf The Initial Writer of the Original Documentation is: Paul Vinkenoog. - Copyright (C) 2004–2007. All Rights Reserved. Initial Writer + Copyright (C) 2004–2016. All Rights Reserved. Initial Writer contact: paulvink at users dot sourceforge dot net. -
\ No newline at end of file + From 7b9a1d1d5d6fc415170eafaa9f8693733fae3ba8 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Mon, 13 Mar 2017 16:09:15 +0000 Subject: [PATCH 29/33] Committed version 1.4 of nbackup guide (updates and additions by Mark Rotteveel) to Release branch --- src/docs/firebirddocs/nbackup.xml | 594 ++++++++++++++++++++++++++++-- 1 file changed, 570 insertions(+), 24 deletions(-) diff --git a/src/docs/firebirddocs/nbackup.xml b/src/docs/firebirddocs/nbackup.xml index c2ecf9fd..63ff5107 100644 --- a/src/docs/firebirddocs/nbackup.xml +++ b/src/docs/firebirddocs/nbackup.xml @@ -1,33 +1,46 @@ - +
Firebird's nbackup tool + Paul + Vinkenoog - 19 Sep 2011 — Document version 1.2 + + + Mark + + Rotteveel + + + September 2014 — Document version 1.4 +
Introduction + Nbackup is a backup utility included in the Firebird download packages since version 2.0. It offers possibilities not present in gbak – Firebird's pre-existing backup tool – but doesn't replace the latter. Both programmes have their strengths and weaknesses; they will likely coexist for some time to come.
+
Nbackup features – an overview + With nbackup, you can perform two different kinds of tasks: + Making and restoring of both full and incremental backups. An incremental backup only contains the mutations since some specific previous backup. + Locking the main database file so you can subsequently back it up yourself with copying or backup tools of your own choice. In this mode, nbackup doesn't back up anything; @@ -35,52 +48,64 @@ a provision for restoring here, too. + Both modes can operate on an active database, without hindering connected users. The backup created will always reflect the state of the database at the beginning of the operation. Furthermore, only SYSDBA and the database owner (and sometimes OS admins) can make a backup, but every user can restore a backup to a new database. In these respects nbackup doesn't differ from gbak. +
Advantages of nbackup + Both modes: high speed (as high as hardware and OS will allow), because nbackup doesn't look at the actual data. In backup mode the contents are written more or less blindly to the backup file. + Backup/restore mode: time and disk space savings, because you don't need to make a full backup every time. This can make a huge difference with databases in the gigabyte range. + Lock/unlock mode: total freedom in your choice of backup, copy, and/or compression tools.
+
Limitations of nbackup + Nbackup will not sweep and compact your database the way gbak does. + You can't change the database owner with an nbackup backup/restore cycle, like you can with gbak. + Nbackup can't make transportable backups, that is: backups you can restore on an incompatible platform or under another server version. + At this moment, nbackup should not be used on multi-file databases. + Nbackup itself can only back up local databases. However, in Firebird 2.5 and above its backup and restore tasks can also be performed remotely through the Services Manager. + Except when the Services Manager is used (in Firebird 2.5+) backing up with nbackup requires direct access to the database file. With gbak this is not the case. @@ -88,166 +113,244 @@
+
Functions and parameters + The following table gives an overview of nbackup's parameters. If the field Added is empty, the parameter has existed since nbackup's introduction in Firebird 2.0. + Nbackup parameters + - - - + + + + + + Parameter + Function + Added + -B n <database> [<filename>] + Make level-n backup of database to file - + + + -R <database> [<filename> ...] + Restore database from backup file(s) - + + + -L <database> + Lock database - + + + -N <database> + Unlock locked database - + + + -F <database> - Unlock self-restored database - + + Unlock user-restored database + + + -S + Give size in database pages (with -L) + 2.1 + -T + Suppress database triggers (with -B, -L, -N) + 2.1 + -D on|off + Direct I/O on/off (with -B) + 2.1.4 + -U <username> + Supply user name (with -B, -L, -N) - + + + -P <password> + Supply password (with -B, -L, -N) - + + + -FE <filename> + Fetch password from file (with -B, -L, -N) + 2.5 + -Z + Version info (by itself or with -B, -R, -L, -N, -F) + 2.5 + -? + Help (switches off all other parameters) + 2.5
+ Depending on the chosen main function (-B, -R, -L, -N or -F), nbackup may require different types of access to the database: a Firebird server connection, direct file access, or both. The following table gives the details: + Access required + - - - + + + + + + Parameter + Function + Access + -B + Backup + server + file + -R + Restore + file + -L + Lock + server + -N + Unlock (undo -L) + server + -F - Unlock after self-restore + + Unlock after user restore + file
+ Where server access is required (with -B, -L and -N), the user must either provide a Firebird username and password (with -U and -P/-FE or through the environment variables ISC_USER and ISC_PASSWORD), or be admitted by the server on other grounds (e.g. as root under Posix or by trusted authentication under Windows). + Where filesystem access is required (with -B, -R and -F), the user must have sufficient read and/or write privileges to the database file. + Where filesystem access is required exclusively (with -R and -F), the user need not have a Firebird login and a running Firebird server need not be present. + Please notice: The above table and text concern access to the database. Access to the backup file is – obviously – always on the filesystem level.
+
Making and restoring backups + To begin with: nbackup.exe is located in the bin subdirectory of your Firebird folder. Typical locations are e.g. C:\Program Files\Firebird\Firebird_2_0\bin (Windows) or /opt/firebird/bin (Linux). Just like most of the tools that come with Firebird, nbackup has no graphical interface; you launch it from the command prompt or call it from within a batch file or application. + Under heavy-load circumstances in some environments, nbackup 2.0.3 and below may cause problems that will lead to deadlocks or even corrupted databases. While these problems aren't @@ -255,53 +358,69 @@ to use nbackup comfortably. If it concerns large databases under Posix, the use of direct I/O may also make a difference. More about this in the section Direct I/O. + +
Full backups +
Making full backups + To make a full database backup, the command syntax is: +
nbackup [-U <user> -P <password>] -B 0 <database> [<backupfile>]
+ For instance: +
C:\Data> nbackup -B 0 inventory.fdb inventory_1-Mar-2006.nbk
+ Comments: + The parameter -B stands for backup (gee!). The backup level 0 indicates a full backup. Backup levels greater than 0 are used for incremental backups; we'll discuss those later on. + Instead of a database filename you may also use an alias. + Instead of a backup filename you may also specify stdout. This will send the backup to standard output, from where you can redirect it to e.g. a tape archiver or a compression tool. + The -U (user) and -P (password) - parameters may be omitted if at least one of the following condtions is met: + parameters may be omitted if at least one of the following conditions is met: + The environment variables ISC_USER and ISC_PASSWORD have been set, either to SYSDBA or to the owner of the database. + You are logged on as root on a Posix system. This makes you SYSDBA by default. + Under Windows: Trusted authentication is enabled in firebird.conf, and you are logged on to the Windows account that owns the database. This is possible in Firebird 2.1 and above. + Under Windows: Trusted authentication is enabled in firebird.conf, and you are logged on as a Windows @@ -311,9 +430,11 @@ the database. + For clarity and brevity, the -U and -P parameters are not used in the examples. + Starting with Firebird 2.5, instead of -P <password> you may also use -FE @@ -323,12 +444,14 @@ otherwise pick it up via the command history, the w command on Unix or from a script or batchfile. + In Firebird 2.1 and up, the firing of database triggers can be prevented by specifying the -T option. For more information, see Suppressing database triggers. + Starting with Firebird 2.1.4, it is possible to force direct I/O on or off by specifying -D on or @@ -336,12 +459,14 @@ Direct I/O, elsewhere in this manual. + The different parameters (-B, -U etc.) may occur in any order. Of course each parameter should be immediately followed by its own argument(s). In the case of -B there are three of them: backup level, database, and backup file - in that order! + If the -B parameter comes last, you may leave out the name of the backup file. In that case nbackup @@ -350,32 +475,39 @@ commands of the same level are issued in the same minute. + Do not use nbackup for multi-file databases. This can lead to corruption and loss of data, despite the fact that nbackup will not complain about such a command. +
A word on the inner workings + Note: What follows here is not necessary knowledge to use nbackup. It just gives a rough (and incomplete) impression of what happens under the hood during execution of nbackup -B: + First of all, the main database file is locked by changing an internal state flag. From this moment on, any and all mutations in the database are written to a temporary file - the difference file or delta file. + Then the actual backup is made. This isn't a straight file copy; restoring must be done by nbackup as well. + Upon completion of the backup, the contents of the delta file are integrated with the main database file. After that, the database is unlocked (flag goes back to normal) and the delta is removed. + The functionality of steps 1 and 3 is provided by two new SQL statements: ALTER DATABASE BEGIN BACKUP and ALTER DATABASE END BACKUP. Contrary to what the names suggest, these statements do @@ -385,38 +517,50 @@ right moments.
+
Restoring a full backup + A full backup is restored as follows: +
nbackup -R <database> [<backupfile>]
+ For instance: +
C:\Data> nbackup -R inventory.fdb inventory_1-Mar-2006.nbk
+ Comments: + You don't specify a level for a restore. + When restoring, the -R parameter must come last, for reasons that will become clear later. + Instead of a database filename you may also use an alias. + If the specified database file already exists, the restore fails and you get an error message. + Here too, you may omit the name of the backup file. If you do, nbackup will prompt you for it. (Attention! In Firebird 2.0 this interactive restore feature is broken, leaving you with an error message and a failed restore. Fixed in 2.0.1.) + Restoring works purely on the filesystem level and can even be done without a Firebird server running. Any credentials supplied via the -U and @@ -428,64 +572,90 @@
+
Incremental backups + The incremental backup facility was entirely broken in Firebird 2.1, and fixed again in 2.1.1. + +
Making incremental backups + To make an incremental (differential) backup we specify a backup level greater than 0. An incremental backup of level N always contains the database mutations since the most recent level N-1 backup. + Examples: + One day after the full backup (level 0), you make one with level 1: +
C:\Data> nbackup -B 1 inventory.fdb inventory_2-Mar-2006.nbk
+ This backup will only contain the mutations of the last day. + One day later again, you make another one with level 1: +
C:\Data> nbackup -B 1 inventory.fdb inventory_3-Mar-2006.nbk
+ This one contains the mutations of the last two days, since the full backup, not only those since the previous level-1 backup. + A couple of hours on we go for a level-2 backup: +
C:\Data> nbackup -B 2 inventory.fdb inventory_3-Mar-2006_2.nbk
+ This youngest backup only contains the mutations since the most recent level-1 backup, that is: of the last few hours. + All the comments that have been made about full backups also apply to incremental backups. + Again: do not use nbackup for multi-file databases.
+
Restoring incremental backups + When restoring incremental backups you must specify the entire chain of backup files, from level 0 through the one you wish to restore. The database is always built up from the ground, step by step. (It is this stepwise adding until the database is restored that gave rise to the term incremental backup.) + The formal syntax is: +
nbackup -R <database> [<backup0> [<backup1> [...] ] ]
+ So restoring the level-2 backup from the previous example goes as follows: +
C:\Data> nbackup -R inventory.fdb inventory_1-Mar-2006.nbk inventory_3-Mar-2006.nbk inventory_3-Mar-2006_2.nbk
+ Of course the line has been split here for layout reasons only - in reality you type the entire command and only hit Enter at the end. + Comments (in addition to the comments with restoring a full backup): + Because it is not known beforehand how many filenames will follow the @@ -493,13 +663,16 @@ considers all arguments after the -R to be names of backup files. It is for this reason that no other parameter may follow the list of filenames. + There is no formal limit to the number of backup levels, but in practice it will rarely make sense to go beyond 3 or 4. +
Non-connecting links + What happens if you accidentally leave out a file, or specify a series of files that don't all belong together? You could imagine that you specify inventory_2-Mar-2006.nbk by mistake instead of @@ -507,6 +680,7 @@ backup files, so in both cases we get a nice 0, 1, 2 level series. But our level-2 file is incremental to the level-1 backup of 3 March, not to the one of 2 March. + Fortunately such a mistake can never lead to an incorrectly restored database. Each backup file has its own unique ID. Furthermore, each backup file of level 1 or above contains the ID of the backup on which it is based. When restoring, nbackup checks these @@ -515,8 +689,10 @@
+
Backing up raw-device databases + Firebird databases need not be files; they can also be placed on a so-called raw device, for instance a disk partition without a file system. The question where the delta has to be placed in @@ -526,13 +702,16 @@ as /dev/hdb5.delta. In light of the nature and purpose of the /dev directory and its often limited available space, this is undesirable. + As of Firebird 2.1, nbackup refuses to operate on raw-device databases unless an explicit location for the delta file has been set. The way to do this is discussed in Setting the delta file, later on in this manual.
+
Suppressing database triggers (Firebird 2.1+) + Firebird 2.1 introduced the concept of database triggers. Certain types of these triggers can fire upon making or breaking a database connection. As part of the backup process, nbackup opens a regular connection to the database (in some versions even more @@ -541,8 +720,10 @@ gbak and isql are called -nodbtriggers (we love diversity, here at Firebird).
+
Direct I/O (Firebird 2.1.4+) + Originally, nbackup used direct I/O only when making a backup under Windows NT (and successors like 2000, 2003 etc.) On all other OS'es, direct I/O was off. This caused problems on some Linux systems, so in versions 2.0.6 and 2.1.3 direct I/O was switched on under Linux @@ -550,12 +731,15 @@ 2.1.4 and 2.5 the original behaviour was restored, but this time as a default that was overridable by a newly added parameter: -D. Its use is as follows: +
nbackup -B 0 cups.fdb cups.nbk -D on -- direct I/O on nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off
+ Just like the option letters themselves, the arguments ON and OFF are case-insensitive. + Direct I/O is only applied when making a backup, not during a restore. Under Windows it is realized by setting FILE_FLAG_NO_BUFFERING. On other systems, O_DIRECT and POSIX_FADV_NOREUSE are used. The latter @@ -563,22 +747,28 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off Even if the user specified -D on explicitly, this doesn't lead to a warning or error message.
+
Informational options (Firebird 2.5+) + Apart from the already mentioned -FE and -D parameters, Firebird 2.5 also saw the introduction of the following two: + -Z + Shows single-line version information. This option can be used independently, but also in combination with other parameters, such as -B, -R, -L etc. + -? + Shows a summary of nbackup's usage and command-line parameters. Attention: If this option is present, all the other parameters are ignored! @@ -586,8 +776,10 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off
+
Backups on remote machines (Firebird 2.5+) + Nbackup itself only operates on local databases. But in Firebird 2.5 and up, nbackup-type backups and restores can also be performed remotely via the Services Manager. For this, the program fbsvcmgr.exe on the local machine is used; it is @@ -596,6 +788,7 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off hostname:service_mgr, with hostname being the name of the remote server. Other available parameters are: +
-user username -password password @@ -607,30 +800,39 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off -nbk_no_triggers -nbk_direct on|off
+ Making a full backup on the remote machine frodo goes like this: +
fbsvcmgr frodo:service_mgr -user sysdba -password masterke -action_nbak -nbk_level 0 -dbname C:\databases\countries.fdb -nbk_file C:\databases\countries.nbk
+ And a subsequent incremental backup: +
fbsvcmgr frodo:service_mgr -user sysdba -password masterke -action_nbak -nbk_level 1 -dbname C:\databases\countries.fdb -nbk_file C:\databases\countries_1.nbk
+ To restore the whole shebang: +
fbsvcmgr frodo:service_mgr -user sysdba -password masterke -action_nrest -dbname C:\databases\countries_restored.fdb -nbk_file C:\databases\countries.nbk -nbk_file C:\databases\countries_1.nbk
+ Notice: Each of the above commands should be typed as a single sentence, without line breaks. The hyphens before the parameter names may be omitted, but especially with long commands like these it may be helpful to leave them in, so you can easily identify the individual parameters (the arguments don't get a hyphen). + Comments: + The Services Manager always requires authentication, be it automatic (root under @@ -639,6 +841,7 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off variables ISC_USER and ISC_PASSWORD are not used. AUTO ADMIN MAPPING in the database has no effect when connecting remotely (though this may also depend on the configuration of the network). + Note: When Windows trusted authentication is in effect, the account name of the user on the local machine is passed to the Services Manager on the remote machine. If the owner of the remote database is a Windows account (e.g. necessarily the same person as user PAUL on another machine. + Restoring (-action_nrest) also requires authentication, but once verified the credentials are not used in any way. Hence, the user need not be the database owner, SYSDBA or superuser. In the case of Windows trusted authentication, the user need not exist at all on the remote machine (where the database is located). + This weak authentication implies another potential security risk. Suppose a sensitive database is nbackupped, and the backups are well protected on the filesystem level. An average user can't restore the database with nbackup then, because nbackup runs @@ -665,6 +870,7 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off calls the Firebird server, which may have file-level access to the backup. Of course there are solutions to this, but it's important to be aware of the risk. + The Services Manager can also be used locally; in that case the first argument becomes service_mgr, without hostname. When used locally, @@ -675,6 +881,7 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off rights, then it's more practical to use nbackup itself, with its much shorter commands. + Specifying -nbk_no_triggers or -nbk_direct with -action_nrest leads to an @@ -682,106 +889,138 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off -T and -D parameters if they are used in the wrong context. + Instead of a database filename you may also use an alias.
+
A practical application + An nbackup-based incremental backup scheme could look like this: + Each month a full backup (level 0) is made; + Each week a level-1; + A level-2 backup daily; + A level-3 backup hourly. + As long as all backups are preserved, you can restore the database to its state at any hour in the past. For each restore action, a maximum of four backup files is used. Of course you schedule things in such a way that the bigger, time-consuming backups are made during off-peak hours. In this case the levels 0 and 1 could be made at weekends, and level 2 at night. + If you don't want to keep everything for eternity, you can add a deletion schedule: + Level-3 backups are deleted after 8 days; + Level-2s after a month; + Level-1s after six months; + Full backups after two years, but the first one of each year is kept. + This is only an example of course. What's useful in an individual case depends on the application, the size of the database, its activity, etc.
+
Read on? + At this point you know everything you need in order to make and restore full and/or incremental backups with nbackup. You only need to read any further if you want to use backup tools of your own choice for your Firebird databases (see Locking and unlocking), or if you want to override the default name or location of the delta file (see Setting the delta file). + If you have no craving for any of that: good luck in your work with nbackup!
+
Locking and unlocking + If you prefer to use your own backup tools or just make a file copy, nbackup's lock-unlock mode comes into view. Locking means here that the main database file is frozen temporarily, not that no changes can be made to the database. Just like in backup mode, mutations are directed to a temporary delta file; upon unlocking, the delta file is merged with the main file. + As a reminder: nbackup.exe lives in the bin subdir of your Firebird folder. Typical locations are e.g. C:\Program Files\Firebird\Firebird_2_0\bin (Windows) or /opt/firebird/bin (Linux). There's no GUI; you launch it from the command prompt or call it from within a batch file or application. +
- Locking the database and backing up yourself + Locking the database and making the backup yourself + A typical session in which you make your own backup goes as follows: + Lock the database with the -L (lock) switch: +
nbackup [-U <user> -P <password>] -L <database>
+ Now copy/backup/zip the database file to your heart's content, with your own choice of tools. A simple file copy is also possible. + Unlock the database with -N (uNlock): +
nbackup [-U <user> -P <password>] -N <database>
+ The last command will also cause any mutations - which have been written to the delta file - to be merged into the main file. + The backup you made contains the data as they were at the moment the database was locked, regardless how long the locked state has lasted, and regardless how long you may have waited before making the actual backup. + Comments: + Instead of a database filename you may also specify an alias. + The -U and -P parameters may be omitted if the envars ISC_USER and ISC_PASSWORD are set, if @@ -789,11 +1028,13 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off a detailed description see the comments under Making full backups. + Starting with Firebird 2.5, instead of -P <password> you may also use -FE <filename>. + Both -L and -N make a regular connection to the database, so in Firebird 2.1 and above it may be wise to add the @@ -801,68 +1042,84 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off linkend="nbackup-backups-dbtriggers">Suppressing database triggers). + If you're locking a raw-device database with Firebird 2.1 or above, the -S option can be very helpful; see Locking raw-device databases. + You can optionally add -Z to have version information printed on the first line of the output. + What goes for backup/restore also applies to the lock/unlock switches: do not use them on multi-file databases. Until things have changed, don't let nbackup loose on multi-file databases at all!
+
Restoring a backup made after <quote>nbackup -L</quote> + An copy of a locked database is itself a locked database too, so you can't just copy it back and start using it. Should your original database get lost or damaged and the self-made copy needs to be restored (or should you wish to install the copy on another machine), proceed like this: + Copy/restore/unzip the backed-up database file yourself with the necessary tools. + Now unlock the database, not with the -N switch, but with -F (fixup): +
nbackup -F <database>
+ Here too, you can optionally use an alias instead of a filename, and add -Z for version info. Other options make no sense. + Why are there two unlock switches, -N and -F? + -N first sees that any changes made since the locking by -L are merged into the main database file. After that, the database goes back into normal read/write mode and the temporary file is deleted. + - -F only changes the state flag of the self-restored database + -F only changes the state flag of the user-restored database to normal. + So you use: + -N after having made a copy/backup yourself (to reverse the -L issued earlier); + -F after having restored such a backup yourself. + It is a bit unfortunate that the last switch should be called -F for Fixup. After all, it doesn't fix anything; it only @@ -873,46 +1130,61 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off Flag-only.
+
Under the hood + Note: This section doesn't contain any necessary knowledge, but provides some extra information which could deepen your understanding of the various switches. + + nbackup -L does the following: + Connect to the database; + Start a transaction; + Call ALTER DATABASE BEGIN BACKUP (this statement has been discussed in the extra information on nbackup -B); + Commit the transaction; + Disconnect from the database. + nbackup -N follows the same steps, but with ...END BACKUP in step 3. + nbackup -F works as follows: + The restored database file is opened; + Within the file, the state flag is changed from locked (nbak_state_stalled) to normal (nbak_state_normal); + The file is closed again. + nbackup -F operates purely on file level and can therefore also be performed without a Firebird server running. Any credentials supplied via the @@ -920,14 +1192,17 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off parameters are ignored, just as with nbackup -R.
+
Locking raw-device databases + As discussed in Backing up raw-device databases, problems can arise if a delta has to be created for a database located on a raw device. Therefore, in Firebird 2.1 and up, nbackup refuses to operate on raw-device databases unless an explicit location for the delta file has been set previously. For the procedure, see Setting the delta file, a little further down. + There's also another problem if you lock and copy a raw device: you don't know the actual size of the database! The raw device may be 10 GB, but the database might only take up 200 MB of that space. To prevent having to copy the entire device just to be on the safe side @@ -942,30 +1217,40 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off count.
+
Setting the delta file + By default, the delta file lives in the same directory as the database itself. The file name is also the same, but with .delta appended. This is usually not a problem, but sometimes it is desirable or even necessary to change the location, e.g. when the database is stored on a raw device. Nbackup itself has no provision for setting the location; this must be done through SQL. + Make a connection to the database with any client that allows you to enter your own SQL statements and give the command: +
alter database add difference file 'path-and-filename'
+ The custom delta file specification is persistent in the database; it is stored in the system table RDB$FILES. To revert to the default behaviour, issue the following statement: +
alter database drop difference file
+ You can also specify a custom delta location while creating a new database: +
create database 'path-and-dbname' difference file 'path-and-deltaname'
+ Notes + If you specify a bare file name with [ADD] DIFFERENCE FILE, the @@ -973,10 +1258,12 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off database, but in the current directory as seen from the server. On Windows this may e.g. be the system directory. The same logic applies to relative paths. + The entire directory path must already exist. Firebird doesn't attempt to create any missing directories. + If you want to change your custom delta specification, you must first DROP the old one and then ADD the new @@ -985,72 +1272,272 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off
+ +
+ Backup history + + The firebird database keeps a history of all nbackup activity in the system table + RDB$BACKUP_HISTORY. This information is used by nbackup + itself for internal housekeeping, but can also be used to find out when the last backup was + done, on which level and what the filename is. + + For example, to see the last 5 backups you can use: + +
+ SELECT RDB$BACKUP_ID, RDB$TIMESTAMP, RDB$BACKUP_LEVEL, RDB$GUID, + RDB$SCN, RDB$FILE_NAME +FROM RDB$BACKUP_HISTORY +ORDER BY RDB$TIMESTAMP DESC +ROWS 5 +
+ + The columns of RDB$BACKUP_HISTORY are: + + + + + + Column + + Description + + + + + + RDB$BACKUP_ID + + Primary key + + + + RDB$TIMESTAMP + + Time and date of backup + + + + RDB$BACKUP_LEVEL + + Backup level + + + + RDB$GUID + + GUID of the backup (used to check dependencies between files) + + + + RDB$SCN + + Highest page marker in the backup + + + + RDB$FILE_NAME + + Filename of the backup + + + + + + For an explanation of the field RDB$SCN see the section + . + + The contents of the table RDB$BACKUP_HISTORY are not + backed up and restored by gbak; see the section for details. +
+ +
+ Technical background information + + Nbackup performs a physical backup of the database pages by copying pages that have been + modified since the last backup of the immediately preceding level. A level 0 + backup copies all pages, while a level 1 copies only those pages that have + been modified after the most recent level 0. To be able to find the modified + pages, Firebird uses a marker that is called the SCN (short for page + scan). This number is incremented at each backup state change. For each backup with nbackup + there are three state changes: + + + + nbak_state_normal (no backup) to + nbak_state_stalled (database writes to delta file) + + + + nbak_state_stalled to nbak_state_merge + (merging delta file back into database) + + + + nbak_state_merge to nbak_state_normal (no + backup) + + + + + These three state changes occur even if the backup fails. + + + The SCN of the database before the start of the backup is recorded together with the + backup. The very first backup gets SCN 0, the second 3, + etc. This number is independent from the level of the backup. The SCN is used to mark the pages + of a database. So for example: + + + + + + + + + + SCN + + Explanation + + + + + + 0 + + Pages before any backup + + + + 1 + + Pages written/updated into the delta file during the backup + + + + 2 + + Pages written/updated during the merge of delta file into main backup + + + + 3 + + Pages written/updated after ending first backup+merge + + + + + + When a level 1 backup is made, nbackup looks for the last level + 0 backup and backs up all pages with an SCN higher than the SCN of that level + 0 backup (and so on). + + A backup and restore with gbak does not restore the content of the RDB$BACKUP_HISTORY table and it resets the SCN of all pages back to + 0. The reason for this is that gbak creates a logical backup instead of a + physical backup. So a restore using gbak will rewrite the entire database (and can even change + the page size). This renders previous backups with nbackup meaningless as a starting point for + subsequent backups: you need to start with a fresh level 0. +
+ Document history + The exact file history is recorded in the manual module in our CVS tree; see http://firebird.cvs.sourceforge.net/viewvc/firebird/manual/src/docs/firebirddocs/nbackup.xml?view=log + 0.1 + 21 Oct 2005 + PV + First edition. + 1.0 + 1 Dec 2006 + PV + Removed beta reference in edition info. Changed warning against specifying backup file names interactively with nbackup -R. Removed (or will be) from first sentence in Document History. + Changed C:\Databases to C:\Data in the examples, just to keep the lines from running out of the shaded screen areas in the PDF. + Added section Setting the delta file, and changed section Read on? accordingly. + 1.1 + 5 May 2008 + PV + Making and restoring backups: Added warning about heavy-load risks with nbackup 2.0.0–2.0.3. + Restoring a full backup: Corrected wrong statement that nbackup will overwrite an existing database if there are no active connections. Changed italic text about interactive restore failure to a Note and mentioned its fix in 2.0.1. + Incremental backups: Inserted warning that incremental backups are broken in 2.1. + Suppressing database triggers (Firebird 2.1+): New section. + Read on?: Fixed typo (you -> your). + 1.2 + 19 Sep 2011 + PV + Document source formatting: Changed max. line length to 100, without open lines. + All sections and subsections now have an id. + Introduction: Edited first sentence. + Nbackup features - an overview: First sentence: groups -> kinds. Edited last para before first subsection: mentioned that only SYSDBA, owner and sometimes OS admins can make a backup. + Nbackup features - an overview :: Limitations of nbackup: Edited previously last listitem to mention Services Manager. Added listitem about direct file access. Removed last para. + Functions and parameters: New section. + Making and restoring backups: Slightly altered last sentence of first para. Extended warning: added info on the role of direct I/O with large databases under Posix. + Making and restoring backups :: Full backups :: Making full backups: Corrected and extended listitem on -U and -P parameters. Added listitems on -FE @@ -1059,58 +1546,112 @@ nbackup -B 0 mugs.fdb mugs.nbk -D off -- direct I/O off starting with The different parameters, the parenthesized text now reads (-B, -U etc.), because many new parameters have been added. + Making and restoring backups :: A word on the inner workings: Small edit (image -> impression). + Making and restoring backups :: Full backups :: Restoring a full backup: Removed parameters -U and -P from specification. Added listitem on aliases. Changed separate Note about interactive restore failure back to italic text inside the listitem itself. Added listitem about non-necessity of running server and ignoring credentials. + Making and restoring backups :: Incremental backups: Edited Warning: mentioned fix in 2.1.1. + Making and restoring backups :: Incremental backups :: Restoring incremental backups: Removed parameters -U and -P from formal syntax and 1st listitem. + Making and restoring backups :: Backing up raw-device databases: New section. + Making and restoring backups :: Suppressing database triggers: Edited and extended this section, but removed the SYSDBA and owner only remark. + Making and restoring backups :: Direct I/O (Firebird 2.1.4+): New section. + Making and restoring backups :: Informational options (Firebird 2.5+): New section. + Making and restoring backups :: Backups on remote machines (Firebird 2.5+): New section. + Locking and unlocking: Slightly altered last sentence of second para. + Locking and unlocking :: Locking the database and backing up yourself: Added Comments (para + itemizedlist). + Locking and unlocking :: Restoring a backup made after nbackup -L: Added info on use of alias and -Z to step 2 of procedure. In next para, translated en (leftover from Dutch original) -> and. Added sentence to Note about reading -F as Flag-only. + Locking and unlocking :: Locking raw-device databases: New section. + Locking and unlocking :: Under the hood: Edited Note. + Setting the delta file: 1st para largely rewritten; now refers to raw-device databases. Split off last sentence into a para of its own. Added info (para + programlisting) about setting delta with CREATE DATABASE. 1st listitem in Notes: ADD -> [ADD]. + Document history: Changed ulink to CVS (both text and url); now points directly to document. - License notice: End year in copryright mention now + + License notice: End year in copyright mention now 2011. + + + 1.3 + + 12 Oct 2011 + + PV + + + Functions and parameters: In first table: self-restored + -> user-restored. In second table: self-restore -> user restore. + + Locking and unlocking :: Locking the database and backing up + yourself: Section renamed Locking the database and making the + backup yourself. + + Locking and unlocking :: Restoring a backup made after nbackup + -L: 2nd listitem in 1st itemizedlist: self-restored -> + user-restored. + + + + + 1.4 + + 18 Sep 2014 + + MR + + + Backup history: New section + + Technical background information New section + + + License notice + The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the License); you may only use this Documentation if you comply with the terms of this License. Copies of the License are available at (PDF) and http://www.firebirdsql.org/manual/pdl.html (HTML). + The Original Documentation is titled Firebird's nbackup tool. + The Initial Writer of the Original Documentation is: Paul Vinkenoog. + Copyright (C) 2005–2011. All Rights Reserved. Initial Writer contact: <firstname> at <lastname> dot nl. + + Contributor(s): Mark Rotteveel
From 68f223e264d7d85b2efcf8c763924d6ef53f6fc0 Mon Sep 17 00:00:00 2001 From: Paul Vinkenoog Date: Mon, 30 Oct 2017 19:02:56 +0000 Subject: [PATCH 30/33] Added param keep.relative.image.uris (value 1) to prevent incorrect image path references in the .fo file when source docs in subdirs are xi:included, causing some images not to appear in the PDF builds. --- src/docs/xsl/fo/param.xsl | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/docs/xsl/fo/param.xsl b/src/docs/xsl/fo/param.xsl index a3b901b5..9ffd54ee 100644 --- a/src/docs/xsl/fo/param.xsl +++ b/src/docs/xsl/fo/param.xsl @@ -20,6 +20,10 @@ + + From cfb3b3756de5ad44c7f3b51ae34d7e8c0e5d5e0c Mon Sep 17 00:00:00 2001 From: Mark Rotteveel Date: Sun, 12 Nov 2017 11:40:02 +0100 Subject: [PATCH 31/33] Add .gitignore and .gitattributes and updated affected files --- .gitattributes | 15 +++++++++++++++ .gitignore | 9 +++++++++ src/build/build.bat | 0 3 files changed, 24 insertions(+) create mode 100644 .gitattributes create mode 100644 .gitignore mode change 100755 => 100644 src/build/build.bat diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..166fbe95 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,15 @@ +* text=auto +*.xml text +*.xsl text +*.docbook text +*.css text +*.bat text eol=crlf +*.sh text + +*.bmp binary +*.gif binary +*.ico binary +*.jar binary +*.jpg binary +*.jpeg binary +*.png binary diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..8bdb377a --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +lib/* +!lib/_readme_libs.txt + +tools/* +!tools/_readme_tools.txt +!tools/get_tools_linux.sh + +dist/ +inter/ diff --git a/src/build/build.bat b/src/build/build.bat old mode 100755 new mode 100644 From c316c34134a188258c80715b41507c565f087ec4 Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Tue, 20 Feb 2018 20:20:52 +0000 Subject: [PATCH 32/33] DOC-129 Resolved. Copied to B_Release. --- src/docs/firebirddocs/fbutil_gfix.xml | 35 ++++++++++++++++++--------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/src/docs/firebirddocs/fbutil_gfix.xml b/src/docs/firebirddocs/fbutil_gfix.xml index 0444edac..18acf41b 100644 --- a/src/docs/firebirddocs/fbutil_gfix.xml +++ b/src/docs/firebirddocs/fbutil_gfix.xml @@ -15,7 +15,7 @@ Dunbar - 09 April 2013 – Document version 1.4 + 13 February 2018 – Document version 1.5
@@ -1007,14 +1007,14 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 The default sweep interval for a new database is 20,000. The sweep interval is the difference between the - oldest interesting transaction or OIT and the next - transaction number. + Oldest Snapshot Transaction, or OST and the + Oldest Interesting Transaction or OIT. This doesn't mean that every 20,000 transaction a sweep will take place. It will take place when the - difference between the OIT and the next - transaction is greater than the sweep interval. + difference between the OST and the OIT is greater + than the sweep interval. An interesting transaction is one which has not yet committed. It @@ -1033,10 +1033,10 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 You can check if a manual sweep may be required by running the gstat utility to check the database header - page and extract the oldest and next transaction numbers from the - output. If the gap is small (less than the sweep interval) then a manual - sweep may be in order. Alternatively, the SHOW - DATABASE command in + page and extract the Oldest Transaction (OIT) and Oldest Snapshot (OST) + numbers from the output. If OST - OIT is small (less than the sweep + interval) then a manual sweep may be in order. Alternatively, the + SHOW DATABASE command in isql will also show the details you need. @@ -1895,7 +1895,7 @@ has been prepared. 1.4 - 09 April 1013 + 09 April 2013 ND @@ -1905,6 +1905,19 @@ has been prepared. onwards. + + + 1.5 + + 13 February 2018 + + ND + + + DOC-129 - Updated to correct details of the Sweep Interval and how to + check what the current interval is. + + @@ -1926,7 +1939,7 @@ has been prepared. The Initial Writer of the Original Documentation is: Norman Dunbar. - Copyright (C) 2007–2009. All Rights Reserved. Initial Writer + Copyright (C) 2007–2018. All Rights Reserved. Initial Writer contact: NormanDunbar at users dot sourceforge dot net. From 904a58dc34dfc02f767c006e078fc27f93e702de Mon Sep 17 00:00:00 2001 From: Norman Dunbar Date: Thu, 21 Nov 2019 16:42:23 +0000 Subject: [PATCH 33/33] Gfix manual updated - gargabe section. --- src/docs/firebirddocs/fbutil_gfix.xml | 222 ++++++++++++++++++++++---- 1 file changed, 192 insertions(+), 30 deletions(-) diff --git a/src/docs/firebirddocs/fbutil_gfix.xml b/src/docs/firebirddocs/fbutil_gfix.xml index 18acf41b..c30a7235 100644 --- a/src/docs/firebirddocs/fbutil_gfix.xml +++ b/src/docs/firebirddocs/fbutil_gfix.xml @@ -15,7 +15,7 @@ Dunbar - 13 February 2018 – Document version 1.5 + 21 November 2019 – Document version 1.6
@@ -893,42 +893,103 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 This is basically a copy of the row(s) from the table(s) that were being updated (or deleted) by the transaction prior to the rollback. + Almost all garbage is created by committed transactions. Since + around V2.5 transactions that rollback are cleaned up immediately - + assuming that Firebird is still running. + + The major cause of garbage build-up is long running transactions + that require Firebird to keep old versions of records that are + frequently updated. Another source of garbage is an application strategy + that deletes records and never revisits them. + + What actually happens on delete is that Firebird stores a "deleted + stub" with the full record as a back version. Until the delete is mature + - meaning that all active transactions started + after the delete was committed - the old version + must be preserved. + + Imagine a table that's indexed and accessed by date. On some + schedule, records age out and are deleted. In the application, records + are accessed by date and the deleted records are so old no query every + asks for them. So there they sit, taking up space and doing no good to + anyone. Even with a garbage collect thread, some active transaction has + to stumble over deleted records or records with + unneeded back versions before the record will be garbage collected. + + + In cooperative garbage collection, that particular record will be + cleaned up immediately (or at least when the transaction gets some + cycles). The dedicated garbage collection thread should clean up all the + records on a page, but not until an active transaction tells it that + there's a page that needs cleaning. + Because Firebird uses multi-generational architecture, every time a row is updated or deleted, Firebird keeps a copy in the database. These copies use space in the pages and can remain in the database for - some time. - - In addition to taking up space in the database, these old copies - can lead to increased transaction startup times. + some time, especially if there are no active transactions stumbling + across them! - There are two types of garbage: + There are a number of causes of garbage: - Remnants from a committed transaction. + Remnants from a committed transaction. This is the main + cause of garbage since around Firebird version 2.5. + + + + Remnants from an aborted (rolled back) transaction + may exist in Firebird versions prior to 2.5, + newer versions perform immediate clean up after a rollback + however, if the Firebird Server, the Operating System or the + physical server crashed, then these remnants may still exists, + even in later versions of Firebird. - Remnants from an aborted (rolled back) transaction. + Applications, described above, which delete database + records, but then, subsequently, never revisit those deleted + versions to garbage collect them automatically. - These remnants are simply older copies of the rows that - were being updated by the respective transactions. The differences are - that: + + + With regard to the remnants from aborted or rolled back + transactions, Firebird (now) carries out record keeping to facilitate + save points. This housekeeping allows Firebird to identify and, if + necessary, undo all changes made by a transaction in the event that it + is rolled back, or which failed due to a lost connection. + + If a failed transaction is rolled back in either manner, its state + is set to committed as there are no differences + between a failed transaction and one in which it committed after making + no changes. + + These remnants are simply older copies of the rows that were being + updated by the respective transactions. The differences are that: Whenever a subsequent transaction reaches garbage from a committed transaction, that garbage is - automatically cleared out. + automatically cleared out, but see above for reasons where this + may not take place often enough. - Rolled back garbage is never - automatically cleared out. + Rolled back garbage looks just like record versions created + by active transactions. Those records can be accessed either + sequentially (during a full table scan) or by index - assuming + that the index entry was made before the crash that left the + garbage around. The index entries will exist in the case of all + but the last change made. When one transaction reads a record + version created by a transaction that's listed in the transaction + bit vector as active, the reader attempts to get a lock on the + apparently active transaction id. If the lock request succeeds, + then the other transaction is dead and the reader will either + clean up the mess or notify the garbage collect thread to do + so. - This means that on a database with a lot of rolled back - transactions, there could be a large build up of old copies of the rows - that were updated and then rolled back. + Firebird will automatically sweep through the database and remove the remnants of rolled back transactions and this has two @@ -936,8 +997,10 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 - The database size is reduced as the old copies of rows are - deleted. + The space recovered is made available for reuse by the same + table, however, if this results in the page becoming completely + empty, then it can be used for any purpose within the + database. @@ -948,7 +1011,14 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 One other method of clearing out old rolled back transactions' - garbage is simply to carry out a database backup. + garbage is simply to carry out a database backup. + Gbak reads every table sequentially and + thus visits every row in every table. Applications which also visit + every row in one or more tables, will also cause the garbage in those + tables to be collected. + + Neither will affect the database's OIT (Oldest Intersting + Transaction) or OST (Oldest Snapshot) settings however. In the Super Server version of Firebird 2.0, garbage collection @@ -965,14 +1035,37 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 garbage collection. +
+ Record Versions + + Normally, when a "back" or old version of a row in a table is + created, it will be stored on the same page as the newset version. + This is usually fine as the back version is not normally a complete + copy of the old version, merely a list of differences from the newest + version. Enough information is retained in the old version, to be able + to recreate it, if necessary. + + If the database is suffereing from a lack of garbage colecting, + either deliberately, or down to the application design, then it is + possible that there will be a build up of enough back versions to fill + the target page. When the chain of old versions gets too big, Firebird + has to move the old versions to a diffreent page which, if it occurs + as part of an UPDATE statement, as it normally will, the UPDATE will + run a lot slower than usual and will greatly increase the cost of + subsequent garbage collection againts that table. +
+
Cooperative Garbage Collection This is the default setting, indeed the only setting, that Classic Server uses. In this mode, the normal operation - as described above - takes place. When a full scan is performed (perhaps during a - backup) old versions of the rows are deleted at that point in - time. + backup) old versions of the rows are deleted at that point in time. + Record versions which are old enough that no active transactions have + any interest in them will be removed, as will any versions created by + failed transactions, if there are any present. (Which there shouldn't + be!)
@@ -983,7 +1076,11 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 collector about old versions of updated and deleted rows when they are ready to be cleaned up. This helps avoid the need to force a full scan of each record in the database tables to get the garbage collector to - remove these old versions. + remove these old versions. An active transaction has to recognize the + need for garbage collection and notify the server which puts that + record id on a list for the garbage collect thread. So an unvisited + record will not attract the garbage collector unless another record on + that page is read and does need cleanup. When all rows in a table are read by the server, any old record versions are flagged to the garbage collector as being ready to be @@ -1007,7 +1104,7 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 The default sweep interval for a new database is 20,000. The sweep interval is the difference between the - Oldest Snapshot Transaction, or OST and the + Oldest Snapshot Transaction, or OST and the Oldest Interesting Transaction or OIT. @@ -1018,7 +1115,8 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 An interesting transaction is one which has not yet committed. It - may be still active, in limbo or may have been rolled back. + may be still active, in limbo or may have been rolled back. (Limbo + transactions are never garbage collected.) The sweep facility runs through the database and gets rid of old rows in tables that are out of date. This prevents the database from @@ -1035,11 +1133,52 @@ Client SQL dialect is set to: 2 and database SQL dialect is: 3 gstat utility to check the database header page and extract the Oldest Transaction (OIT) and Oldest Snapshot (OST) numbers from the output. If OST - OIT is small (less than the sweep - interval) then a manual sweep may be in order. Alternatively, the + interval) then a manual sweep may be in order. The SHOW DATABASE command in isql will also show the details you need. + Alternatively, another idea is to run + gstat with the switches set to show old + record versions. If that shows a problem, then it may be a good idea to + start looking for long running transactions. + + The options for this are: + + + + gstat <database> -r[ecord] + + + + gstat <database> -d[ata] + -r[ecord] + + + + gstat <database> -r[ecord] -t[able] + <table_names> + + + + For example: + + tux> gstat test.fdb -r -t NORMAN + +... +Analyzing database pages ... +NORMAN (142) + Primary pointer page: 268, Index root page: 269 + Average record length: 0.00, total records: 15 + Average version length: 9.00, total versions: 15, max versions: 1 + Data pages: 1, data page slots: 1, average fill: 16% +... + + The information is shown in the 'record versions' statistic. In + this example, there are 15 versions and as the 'total records' is also + 15, then all the records have been deleted and need gargabge + collecting. + A manual sweep can be run by using the -s[weep] command. (See below). @@ -1071,13 +1210,23 @@ Sweep interval: 1000 This command will force the garbage left over from old rolled back transactions to be removed, reducing the database size and improving the - performance of new transactions. + performance of new transactions. .Rolled back transactions are less of a + problem than old versions from committed transactions, however, when the + newest versions is being used by all current and future active + transactions. The -i[gnore] option may be supplied. This forces Firebird to ignore checksum errors on database pages. This is not a good idea and should rarely need to be used, however, if your database has suffered some problems it might be necessary to use it. + + Checksums have not been used for a number of years as it was + found that a significant percentage of CPU was consumed by check + summing to find partial page writes - none of which were ever found! + + + The following example shows a manual database sweep being implemented: @@ -1914,8 +2063,21 @@ has been prepared. ND - DOC-129 - Updated to correct details of the Sweep Interval and how to - check what the current interval is. + DOC-129 - Updated to correct details of the Sweep Interval + and how to check what the current interval is. + + + + + 1.6 + + 21 November 2019 + + ND + + + Updated the Garbage section to better explain garbage causes + etc. Courtesy of Ann Harrison. @@ -1939,7 +2101,7 @@ has been prepared. The Initial Writer of the Original Documentation is: Norman Dunbar. - Copyright (C) 2007–2018. All Rights Reserved. Initial Writer + Copyright (C) 2007–2019. All Rights Reserved. Initial Writer contact: NormanDunbar at users dot sourceforge dot net.