Misc. copy editing

Author: mrotteveel

Diff for: src/docs/asciidoc/reference/connection/clientinfoproperties.adoc

@@ -6,15 +6,15 @@ Client info properties allow you to set properties on a connection for informati
 [#ref-client-info-jb5]
 ==== Support in Jaybird 5 and earlier
 
-Support for client info properties was introduced in Jaybird 2.2, storing properties in the `USER_SESSION` context of `RDB$GET/SET_CONTEXT`.
+Support for client info properties was introduced in Jaybird 2.2, storing properties in the `USER_SESSION` context of https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-functions.html#fblangref50-functions-workcontext[`RDB$GET/SET_CONTEXT`].
 Support is quite limited, allowing you to:
 
 * Set properties individually or collectively using a `Properties` object (`Connection#setClientInfo(String,String)`, `Connection#setClientInfo(Properties)`)
 * Clear properties individually (setting them to `null`) (`Connection#setClientInfo(String,String)`
 * Get individual properties (`Connection#getClientInfo(String)`)
 
 Properties are always stored in `USER_SESSION`.
-Properties are retrieved from `USER_TRANSACTION`, falling back to `USER_SESSION` if the property was not present in `USER_TRANSACTION.
+Properties are retrieved from `USER_TRANSACTION`, falling back to `USER_SESSION` if the property was not present in `USER_TRANSACTION`.
 
 Absent is support to:
 
@@ -93,7 +93,7 @@ The `ClientUser` and `ClientHostname` properties are considered application-spec
 If you use a connection pool populated from `org.firebirdsql.ds.FBConnectionPoolDataSource` or `org.firebirdsql.ds.FBXADataSource`, the known properties are reset each time the connection is handed out by the pool.
 This assumes the pool uses `getConnection()` from `PooledConnection`/`XAConnection` each time it hands out the connection.
 This reset only removes the property name from the list of known properties of the connection, it does not clear the property values from `USER_SESSION`.
-If properties contain _sensitive_ values you will need to explicitly clear them.
+If properties contain _sensitive_ values, you will need to explicitly clear them.
 
 This reset is not applied when using a connection pool which is populated by different means (e.g. from `DriverManager` or from a normal `javax.sql.DataSource` like `org.firebirdsql.ds.FBSimpleDataSource`).
 If your connection pool implementation supports custom code to reset a connection, and you need known properties to reset when a connection is reused, make it call `FirebirdConnection.resetKnownClientInfoProperties()`, or call it yourself:

Diff for: src/docs/asciidoc/reference/connection/datatypebind.adoc

@@ -14,7 +14,7 @@ The value of this connection property is a semicolon-separated list of data type
 
 A data type bind definition is of the form `<from-type> TO <to-type>`.
 A definition is the same as the second half of a `SET BIND` statement after the `OF`.
-See the Firebird documentation of `SET BIND` for more information.
+See the Firebird 5.0 documentation of https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-management.html#fblangref50-management-setbind[`SET BIND`] for more information.
 Invalid values or impossible mappings will result in an error on connect.
 
 When using the `dataTypeBind` connection property in a JDBC URL, the semicolons of the list need to be encoded as `%3B`, as unescaped semicolons in the JDBC URL are an alternative to `&` as the separator between properties.
@@ -28,7 +28,7 @@ String jdbcUrl = "jdbc:firebirdsql://localhost/database?charSet=utf-8"
     + "&dataTypeBind=decfloat to varchar%3Btimestamp with time zone to legacy"
 ----
 
-When the property is set through a `Properties` object or a `DataSource` configuration, encoding the semicolon is not necessary and will result in errors.
+When the property is set through a `Properties` object or a `DataSource` configuration, you should not encode the semicolon as this will result in errors.
 
 For example:
 
@@ -40,4 +40,4 @@ props.setProperty("dataTypeBind",
     "decfloat to varchar;timestamp with time zone to legacy"
 ----
 
-Values set through this connection property will be the session default configuration, which means that they are retained (or reverted to) when executing `ALTER SESSION RESET`.
+Values set through this connection property will be the session default configuration, which means that they are retained (or reverted to) when executing https://firebirdsql.org/file/documentation/chunk/en/refdocs/fblangref50/fblangref50-management-session-reset.html#fblangref50-management-session-reset-alter[`ALTER SESSION RESET`].

Diff for: src/docs/asciidoc/reference/connection/firebirdautocommit.adoc

@@ -8,13 +8,13 @@ This functionality is experimental, and will remain so unless Firebird changes h
 
 Incorrect use of this functionality can result in excessive growth of the database due to increases in back-version chains of records, which can also cause performance degradation.
 Additionally, when used with an isolation level other than READ COMMITTED, the connection will only see changes committed at the time the initial transaction was started;
-the auto-commit barrier will not make new committed changes visible.
+the auto-commit barrier will not make new committed changes visible to the current transaction.
 ====
 
 This option is enabled by specifying the connection property `useFirebirdAutocommit=true`.
 
 With this option, a connection in auto-commit mode will configure the transaction to use `isc_tpb_autocommit`.
-This means that Firebird server will internally commit the transaction after each statement completion. 
+This means that Firebird server will internally commit the transaction after each statement completion using "`__commit retain__`".
 Jaybird itself will not commit until connection close (or disabling auto-commit).
 The exception is if the statement was of type `isc_info_sql_stmt_ddl`, in that case Jaybird will commit on statement success and rollback on statement failure (just like it does for all statements in normal auto-commit mode).
 The reason is that Firebird for some DDL commands only executes at a real commit boundary and relying on the Firebird auto-commit is insufficient.

Diff for: src/docs/asciidoc/reference/connection/processinfo.adoc

@@ -21,7 +21,7 @@ Native connections will always report the actual process ID, if a fbclient of Fi
 This cannot be overridden using the options below.
 
 Since Firebird 3.0, the `MON$ATTACHMENTS` table also includes the column `MON$CLIENT_VERSION`.
-Jaybird will report its full version (e.g. `Jaybird jaybird-5.0.1.java11`).
+Jaybird will report its full version (e.g. `Jaybird jaybird-{jaybird-example-version}`).
 
 It is possible to specify the process name and process id in two ways:
 

Diff for: src/docs/asciidoc/reference/statement/generatedkeys.adoc

@@ -27,14 +27,14 @@ Since Jaybird 4.0.8, Jaybird uses a custom parser and no longer requires ANTLR f
 If you previously relied on absence of ANTLR to disable generated keys support, the generated keys feature can be disabled by setting <<ref-generatedkeys-config,connection property `generatedKeysEnabled`>> to `disabled`.
 ****
 
-This functionality is available for `INSERT`, `UPDATE`, `UPDATE OR INSERT` and `DELETE`, and for `MERGE` ([.since]_Firebird 3.0_).
+This functionality is available for `INSERT`, `UPDATE`, `UPDATE OR INSERT`, `DELETE`, and -- [.since]_Firebird 3.0_ -- `MERGE`.
 
 Generated keys retrieval modifies the statement to add a `RETURNING`-clause.
 Firebird 4.0 and earlier only support `RETURNING` for DML operations that affect a single row.
 Attempting to use generated keys retrieval with a statement that affects multiple rows will yield the error _"multiple rows in singleton select"_.
 
-[.since]_Jaybird 5/Firebird 5.0_ Support for multi-row `RETURNING` is introduced in Firebird 5.0.
-Support for multi-row `RETURNING` is available in Jaybird 5.
+[.since]_Jaybird 5_ [.since]_Firebird 5.0_ Support for multi-row `RETURNING` is introduced in Firebird 5.0.
+Support for multi-row `RETURNING` is available since Jaybird 5.
 
 The examples in this section use the following (Firebird 3.0) table:
 
@@ -150,10 +150,10 @@ The values in the `int[]` parameter are the ordinal positions of the columns as
 [WARNING]
 ====
 In Jaybird 3 and earlier, a null or empty array was silently ignored and the statement was executed normally (not producing generated keys).
-In Jaybird 4, this behaviour has changed and instead will throw an exception with message _"Generated keys array columnIndexes was empty or null. A non-empty array is required."_
+In Jaybird 4, this behaviour has changed and instead will throw an exception with message "`__Generated keys array columnIndexes was empty or null. A non-empty array is required.__`"
 
 In Jaybird 3 and earlier, invalid ordinal positions are ignored and silently dropped: passing `new int[] { 1, 5, 6 }` will work, even if there is no sixth column.
-In Jaybird 4, this behavior has changed and instead will throw an exception with message _"Generated keys column position <position> does not exist for table <tablename>. Check DatabaseMetaData.getColumns (column ORDINAL_POSITION) for valid values."_
+Since Jaybird 4, this behavior has changed and instead will throw an exception with message "`__Generated keys column position <position> does not exist for table <tablename>. Check DatabaseMetaData.getColumns (column ORDINAL_POSITION) for valid values.__`"
 ====
 
 [[ref-generatedkeys-examples-column-index]]
@@ -201,7 +201,7 @@ As this is the second column in the result set, it is retrieved from the result
 [WARNING]
 ====
 In Jaybird 3 and earlier, the array of indices is sorted in ascending order before use: passing `new int[] { 4, 1, 3 }` will yield columns in order `ID`, `LASTNAME`, `BIRTHDATE`.
-In Jaybird 4, this sort is no longer applied, so columns will be in the order specified by the array: `BIRTHDATE`, `ID`, `LASTNAME`.
+Since Jaybird 4, this sort is no longer applied, so columns will be in the order specified by the array: `BIRTHDATE`, `ID`, `LASTNAME`.
 To avoid issues, we recommend specifying the columns in ascending order, or always retrieve them by name.
 ====
 
@@ -223,7 +223,7 @@ This method is the fastest as it does not retrieve metadata from the server.
 [WARNING]
 ====
 In Jaybird 3 and earlier, a null or empty array was silently ignored and the statement was executed normally (not producing generated keys).
-In Jaybird 4, this behaviour has changed and instead will throw an exception with message _"Generated keys array columnNames was empty or null. A non-empty array is required."_
+Since Jaybird 4, this behaviour has changed and instead will throw an exception with message "`__Generated keys array columnNames was empty or null. A non-empty array is required.__`"
 ====
 
 [[ref-generatedkeys-examples-column-name]]
@@ -312,4 +312,4 @@ But only on Firebird 3.0 and higher, for Firebird 2.5 this will behave as `ignor
 * `jdbc:firebird://localhost/testdb?generatedKeysEnabled=insert,update` will only enable insert and update support
 
 This feature can be used to circumvent issues with frameworks or tools that always use generated keys methods for prepare or execution.
-For example with `UPDATE` statements that touch multiple records and -- given the Firebird 4.0 and earlier limitations for `RETURNING` -- produce the error _"multiple rows in singleton select"_.
+For example with `UPDATE` statements that touch multiple records and -- given the Firebird 4.0 and earlier limitations for `RETURNING` -- produce the error "`__multiple rows in singleton select__`".

Diff for: src/docs/asciidoc/reference/types/datetime.adoc

@@ -223,7 +223,7 @@ In addition to the standard-defined types, it also supports the type names `TIME
 * Firebird 4.0 redefines `CURRENT_TIME` and `CURRENT_TIMESTAMP` to return a `WITH TIME ZONE` type.
 Use `LOCALTIME` and `LOCALTIMESTAMP` (introduced in Firebird 2.5.9 and Firebird 3.0.4) if you want to ensure a `WITHOUT TIME ZONE` type is used.
 * The database metadata will always return JDBC 4.2 compatible information on time zone types, even on Java 7, and even when legacy time zone bind is set.
-For Java 7 compatibility the JDBC 4.2 `java.sql.Types` constants `TIME_WITH_TIMEZONE` and `TIMESTAMP_WITH_TIMEZONE` are also defined in `org.firebirdsql.jdbc.JaybirdTypeCodes`.
+For Java 7 compatibility, the JDBC 4.2 `java.sql.Types` constants `TIME_WITH_TIMEZONE` and `TIMESTAMP_WITH_TIMEZONE` are also defined in `org.firebirdsql.jdbc.JaybirdTypeCodes`.
 * The default `sessionTimeZone` is set to the JVM default time zone, this may result in different application behavior for `DATE`, `TIME` and `TIMESTAMP`, including values generated in triggers and default value clauses.
 To prevent this, either switch those types to a `WITH TIME ZONE` type, or set the `sessionTimeZone` to `server` or to the actual time zone of the Firebird server.
 * As `CURRENT_TIME` uses the session time zone, which usually is a named zone, use in combination with `java.time.OffsetTime` can yield confusing results.

Diff for: src/docs/asciidoc/reference/types/decfloat.adoc

@@ -29,7 +29,7 @@ The available options are the same as documented in <<ref-decfloat-bind>>
 
 For example
 
-[[source,java]]
+[source,java]
 ----
 try (Connection connection = DriverManager.getConnection(..);
      Statement stmt = connection.createStatement()) {
@@ -45,7 +45,7 @@ WARNING: The effect of the `SET BIND` statement will be reset to the default whe
 
 Jaybird 3.0.9 added the connection property `dataTypeBind` to defining data type mappings.
 This can be used to configure conversion of `DECFLOAT` to a different datatype.
-When set Firebird will present columns or parameters of `DECFLOAT` as the specified type, allowing clients without support for `DECFLOAT` to read or set values.
+When set, Firebird will present columns or parameters of `DECFLOAT` as the specified type, allowing clients without support for `DECFLOAT` to read or set values.
 
 TIP: This property is also available in Jaybird 4, but we recommend to not use this property in Jaybird 4 and instead rely on the default behaviour (`native`) and support for `DECFLOAT`.
 
@@ -54,17 +54,18 @@ To map `DECFLOAT(16)` and `DECFLOAT(34)` to a string type, you can use:
 [source,java]
 .Map all decfloat types to string
 ----
-Properties props = new Properties();
-props.setProperty("dataTypeBind", "decfloat to varchar"
+var props = new Properties();
+props.setProperty("dataTypeBind", "decfloat to varchar");
 ----
 
 To map `DECFLOAT(16)` to `DOUBLE PRECISION` and `DECFLOAT(34)` to string, you can use:
 
 [source,java]
 .Map all decfloat types to string
 ----
-Properties props = new Properties();
-props.setProperty("dataTypeBind", "decfloat(16) to double precision;decfloat(34) to varchar"
+var props = new Properties();
+props.setProperty(
+    "dataTypeBind", "decfloat(16) to double precision;decfloat(34) to varchar");
 ----
 
 Firebird will convert a `DECFLOAT` type to the specified type using a cast to derive the value.
@@ -102,8 +103,7 @@ If you need to use the type code, we suggest you use these constants.
 If a `DECFLOAT` type constant gets added to the JDBC standard, we will update the value.
 The enum value will be deprecated when that version of JDBC has been released.
 
-Jaybird uses a local copy of the https://github.com/FirebirdSQL/decimal-java[FirebirdSQL/decimal-java^] library, with a custom package `org.firebirdsql.extern.decimal`.
-This to avoid additional dependencies. 
+To avoid additional dependencies, Jaybird uses a local copy of the https://github.com/FirebirdSQL/decimal-java[FirebirdSQL/decimal-java^] library, with a custom package `org.firebirdsql.extern.decimal`.
 
 [[ref-decfloat-precision-range]]
 ===== Precision and range

Diff for: src/docs/asciidoc/reference/types/decimal.adoc

@@ -4,15 +4,15 @@
 The JDBC types `DECIMAL` and `NUMERIC` are supported by Firebird and Jaybird and map to `java.math.BigDecimal`.
 
 NOTE: Behaviour in Firebird of `NUMERIC` is closer to the SQL standard `DECIMAL` behaviour. 
-The precision specified is the minimum precison, not the exact precision.
+The precision specified is the minimum precision, not the exact precision.
 
 [[ref-decimal-precision-range]]
 ==== Precision and range
 
 In Firebird 3.0 and earlier, the maximum precision of `DECIMAL` and `NUMERIC` is 18 with a maximum scale of 18.footnote:[In practice, values with precision 19 are possible up to the maximum value of the `BIGINT` backing the value.]
 
 [.since]_Firebird 4.0_ In Firebird 4.0 the maximum precision and scale of `DECIMAL` and `NUMERIC` have been raised to 38.
-Any `NUMERIC` or `DECIMAL` with a precision between 19 and 38 will allow storage up to a precision of 38.
+Any `NUMERIC` or `DECIMAL` with a precision between 19 and 38 will allow storage up to a precision of 38.footnote:[In practice, values with precision 39 are possible up to the maximum value of the `INT128` backing the value.]
 
 In the implementation in Firebird, this extended precision is backed by an Int128.