Document JDBC 4.5 escape to disable escape processing

Author: mrotteveel

src/docs/asciidoc/chapters/statements/statements.adoc

@@ -831,3 +831,99 @@ The escaped syntax for this case identifies which character is used as an escape
 {escape '<escape character>'}
 ....
 
+[#stmt-escape-disable-proc]
+==== "`Disable escape processing`" escape
+
+since:[Jaybird 5.0.12/6.0.5]
+
+The "`disable escape processing`" escape (`++{\...\}++`) can be used to disable escape processing and parameter parsing within part of a statement text.
+
+.Syntax
+[listing]
+----
+<start>[<allowed-char>...]<end>
+
+<start> := {\
+
+<end> := \}
+
+<allowed-char> :=
+    <esc-backslash>
+  | !! any other character than backslash !!
+
+<esc-backslash> := \\
+----
+
+Within the escape, *all* occurrences of a backslash (`\`) *must* be escaped by doubling.
+Unescaped backslashes inside the escape will result in a `FBSQLParseException`.
+
+.Some examples
+[listing]
+----
+-- Input:
+select {\"N\\A"\} from SOME_TABLE
+-- Sent to server:
+select "N\A" from SOME_TABLE
+
+-- Input:
+select {\{fn EXP(2)}\} from SOME_TABLE
+-- Sent to server (results in a syntax error)
+select {fn EXP(2)} from SOME_TABLE
+----
+
+As Java string literals, the escape requires a *lot* of backslashes, see the example repeated below as Java string literals.
+
+.Same examples, but as Java string literals
+----
+-- Input:
+"select {\\\"N\\\\A\"\\} from SOME_TABLE"
+-- Sent to server:
+"select \"N\\A\" from SOME_TABLE"
+
+-- Input:
+"select {\\{fn EXP(2)}\\} from SOME_TABLE"
+-- Sent to server (results in a syntax error)
+"select {fn EXP(2)} from SOME_TABLE"
+----
+
+We think the use case for this escape is extremely limited, even non-existent, for Jaybird.
+Jaybird always offloads parameter parsing to Firebird, and Firebird currently has no syntax that could conflict with the definition of JDBC escapes.
+
+.Possible ambiguity for comments, literals, and delimited identifiers
+[CAUTION]
+====
+Given the backslash must be escaped everywhere inside the escape, the definition in the JDBC 4.5 specification can be interpreted to mean that the escape can end inside a comment, literal, or delimited identifier (quoted identifier).
+Allowing this would conflict with the fact that other JDBC escapes are not parsed inside comments, literals, and delimited identifiers.
+Discussion with the JDBC spec lead and others did not resolve this ambiguity.
+
+For Jaybird, we decide to reject attempts to end the escape in a comment, literal, or delimited identifier.
+Attempts to do so (e.g. `++{\ends/*in\}comment*/++`) will raise a `FBSQLParseException`.
+Valid alternatives would be:
+
+* End it before the comment: +
+`++{\ends\}/*in\}comment*/++`
+* End it after the comment and escape the backslash in the comment: +
+`++{\ends/*in\\}comment*/\}++`
+* Or, don't use the escape: +
+`++ends/*in\}comment*/++`
+
+If a consensus is reached in the JDBC Expert Group, or a community consensus arises, we may revisit this decision.
+
+Further details can be found in https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2026-03-jdbc-escape-to-disable-escape-processing.adoc[jdp-2026-03: JDBC escape to disable escape processing]
+====
+
+Given above ambiguity, and the lack of a real need to use it for Jaybird/Firebird, we recommend avoiding use of this escape unless absolutely necessary.
+If it is used, we recommend only using it for the shortest substring needed.
+
+For example, the last example (passing the JDBC escape `++{fn EXP(2)}++` unprocessed to the server) could also be achieved by only disabling escape processing for the braces:
+
+[listing]
+----
+-- Input:
+select {\{\}fn EXP(2){\}\} from SOME_TABLE
+-- Sent to server (results in a syntax error)
+select {fn EXP(2)} from SOME_TABLE
+----
+
+Alternatively, consider disabling escape processing for the `Statement` using https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/java/sql/Statement.html#setEscapeProcessing(boolean)[`Statement.setEscapeProcessing(boolean)`^] (not available for `PreparedStatement` and `CallableStatement`).
+// TODO Add link to connection property `escapeProcessing` once https://github.com/FirebirdSQL/jaybird/issues/930 is done