From fc130b8e2d38bc710dbfc052a46ca9e017a5cb02 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Thu, 14 Jul 2022 16:19:45 -0400
Subject: [PATCH] doc:  add documentation about ecpg Oracle-compatibility mode

Reported-by: Takeshi Ideriha

Discussion: https://postgr.es/m/TYCPR01MB7041A157067208327D8DAAF9EAA59@TYCPR01MB7041.jpnprd01.prod.outlook.com

Backpatch-through: 11
---
 doc/src/sgml/ecpg.sgml | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index 7f8b4dd5c0..999b7ca0ae 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -1890,7 +1890,8 @@ EXEC SQL SELECT b INTO :val :val_ind FROM test1;
 </programlisting>
     The indicator variable <varname>val_ind</varname> will be zero if
     the value was not null, and it will be negative if the value was
-    null.
+    null.  (See <xref linkend="ecpg-oracle-compat"/> to enable
+    Oracle-specific behavior.)
    </para>
 
    <para>
@@ -9799,6 +9800,42 @@ risnull(CINTTYPE, (char *) &i);
   </sect2>
  </sect1>
 
+ <sect1 id="ecpg-oracle-compat">
+  <title><productname>Oracle</productname> Compatibility Mode</title>
+  <para>
+   <command>ecpg</command> can be run in a so-called <firstterm>Oracle
+   compatibility mode</firstterm>. If this mode is active, it tries to
+   behave as if it were Oracle <productname>Pro*C</productname>.
+  </para>
+
+  <para>
+   Specifically, this mode changes <command>ecpg</command> in three ways:
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      Pad character arrays receiving character string types with
+      trailing spaces to the specified length
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      Zero byte terminate these character arrays, and set the indicator
+      variable if truncation occurs
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      Set the null indicator to <literal>-1</literal> when character
+      arrays receive empty character string types
+     </para>
+    </listitem>
+   </itemizedlist>
+  </para>
+ </sect1>
+
  <sect1 id="ecpg-develop">
   <title>Internals</title>