Mention PL/SQL named param syntax. See issue #420

Author: cjbj

doc/api.md

@@ -5922,20 +5922,30 @@ a [`maxArraySize`](#executebindParams) property is also required
 The [`results`](#executecallback) parameter of the `execute()`
 callback contains an [`outBinds`](#execoutbinds) property with the
 returned OUT and IN OUT bind values.
-If [`bindParams`](#executebindParams) was passed as an array, then
-`outBinds` is returned as an array, with the same order as the binds
-in the statement.  If `bindParams` was passed as an object, then
-`outBinds` is returned as an object.
 
-Here is an example program showing the use of binds:
+Given the creation of the PL/SQL procedure `TESTPROC`:
+
+```sql
+CREATE OR REPLACE PROCEDURE testproc (
+p_in IN VARCHAR2, p_inout IN OUT VARCHAR2, p_out OUT NUMBER)
+AS
+BEGIN
+  p_inout := p_in || p_inout;
+  p_out := 101;
+END;
+/
+show errors
+```
+
+The procedure `TESTPROC` can be called with:
 
 ```javascript
 var oracledb = require('oracledb');
 . . .
 var bindVars = {
   i:  'Chris', // default direction is BIND_IN. Data type is inferred from the data
   io: { val: 'Jones', dir: oracledb.BIND_INOUT },
-  o:  { type: oracledb.NUMBER, dir: oracledb.BIND_OUT },
+  o:  { dir: oracledb.BIND_OUT, type: oracledb.NUMBER },
 }
 connection.execute(
   "BEGIN testproc(:i, :io, :o); END;",
@@ -5946,27 +5956,21 @@ connection.execute(
   });
 ```
 
-Given the creation of `TESTPROC` using:
+Since `bindParams` is passed as an object, the `outBinds` property is
+also an object.  The Node.js output is:
 
-```sql
-CREATE OR REPLACE PROCEDURE testproc (
-p_in IN VARCHAR2, p_inout IN OUT VARCHAR2, p_out OUT NUMBER)
-AS
-BEGIN
-  p_inout := p_in || p_inout;
-  p_out := 101;
-END;
-/
-show errors
+```
+{ io: 'ChrisJones', o: 101 }
 ```
 
-The Node.js output would be:
+PL/SQL allows named parameters in procedure and function calls.  This
+can be used in `execute()` like:
 
 ```
-{ io: 'ChrisJones', o: 101 }
+  "BEGIN testproc(p_in => :i, p_inout => :io, p_out => :o); END;",
 ```
 
-An alternative to the 'bind by name' syntax is 'bind by array' syntax:
+An alternative to node-oracledb's 'bind by name' syntax is 'bind by array' syntax:
 
 ```javascript
 var bindVars = [
@@ -5976,6 +5980,14 @@ var bindVars = [
 ];
 ```
 
+When [`bindParams`](#executebindParams) is passed as an array, then
+`outBinds` is returned as an array, with the same order as the OUT
+binds in the statement:
+
+```
+[ 'ChrisJones', 101 ]
+```
+
 Mixing positional and named syntax is not supported.  The following
 will throw an error:
 

examples/plsqlfunc.js

@@ -50,6 +50,8 @@ oracledb.getConnection(
     };
     connection.execute(
       "BEGIN :ret := testfunc(:p1, :p2); END;",
+      // The equivalent call with PL/SQL named parameter syntax is:
+      // "BEGIN :ret := testfunc(p1_in => :p1, p2_in => :p2); END;",
       bindvars,
       function (err, result) {
         if (err) {

examples/plsqlproc.js

@@ -51,6 +51,8 @@ oracledb.getConnection(
     };
     connection.execute(
       "BEGIN testproc(:i, :io, :o); END;",
+      // The equivalent call with PL/SQL named parameter syntax is:
+      // "BEGIN testproc(p_in => :i, p_inout => :io, p_out => :o); END;",
       bindvars,
       function (err, result) {
         if (err) {