Add lastRowid example

Author: Christopher Jones

doc/api.md

@@ -3862,8 +3862,11 @@ readonly String lastRowid
 ```
 
 The ROWID of a row affected by an INSERT, UPDATE, DELETE or MERGE statement.
-For other statements, or if no row was affected, it is not set.  If more than
-one row was affected, only the ROWID of the last row is returned.
+For other statements, or if no row was affected, it is not set.
+
+If more than one row was affected, only the ROWID of the last row is returned.
+To get all ROWIDs of multiple rows see [DML RETURNING Bind
+Parameters](#dmlreturn).
 
 This property was added in node-oracledb 4.2.
 
@@ -11694,6 +11697,9 @@ const result = await connection.execute(
 console.log(result.outBinds.id);  // print the ID of the inserted row
 ```
 
+Instead of using application generated identifiers, you may prefer to use
+ROWIDs, see [`lastRowid`](#execlastrowid).
+
 ### <a name="cursors1000"></a> 16.2 Cursor Management
 
 A cursor is a "handle for the session-specific private SQL area that holds a

examples/README.md

@@ -58,8 +58,7 @@ File Name                                                 | Description
 [`dbmsoutputpipe.js`](dbmsoutputpipe.js)                  | Show fetching DBMS_OUTPUT by using a pipelined table
 [`demodrop.js`](demodrop.js)                              | Drops the schema objects created by the examples
 [`demosetup.js`](demosetup.js)                            | Used to create common schema objects for the examples
-[`dmlrupd1.js`](dmlrupd1.js)                              | Example of DML RETURNING with a single row match
-[`dmlrupd2.js`](dmlrupd2.js)                              | Example of DML RETURNING where multiple rows are matched
+[`dmlrupd.js`](dmlrupd.js)                                | Example of DML RETURNING where multiple rows are matched
 [`em_batcherrors.js`](em_batcherrors.js)                  | `executeMany()` example showing handling data errors
 [`em_dmlreturn1.js`](em_dmlreturn1.js)                    | `executeMany()` example of DML RETURNING that returns single values
 [`em_dmlreturn2.js`](em_dmlreturn2.js)                    | `executeMany()` example of DML RETURNING that returns multiple values
@@ -73,6 +72,7 @@ File Name                                                 | Description
 [`impres.js`](impres.js)                                  | Shows PL/SQL 'Implict Results' returning multiple query results from PL/SQL code.
 [`insert1.js`](insert1.js)                                | Basic example creating a table and inserting data.  Shows DDL and DML
 [`insert2.js`](insert2.js)                                | Basic example showing auto commit behavior
+[`lastinsertid.js`](lastinsertid.js)                      | Shows inserting a row and getting its ROWID.
 [`lobbinds.js`](lobbinds.js)                              | Demonstrates how to bind and query LOBs
 [`lobinsert1.js`](lobinsert1.js)                          | Shows inserting a file into a CLOB column
 [`lobinsert2.js`](lobinsert2.js)                          | Inserts text into a CLOB column using the RETURNING INTO method.

examples/demodrop.js

@@ -63,6 +63,8 @@ async function run() {
 
       `DROP TABLE no_purchaseorder_b PURGE`,
 
+      `DROP TABLE no_lastinsertid PURGE`,
+
       `DROP TABLE no_dmlrupdtab PURGE`,
 
       `DROP TABLE no_lobs PURGE`,

examples/dmlrupd2.js renamed to examples/dmlrupd.js

@@ -16,12 +16,12 @@
  * limitations under the License.
  *
  * NAME
- *   dmlrupd2.js
+ *   dmlrupd.js
  *
  * DESCRIPTION
  *   Example of 'DML Returning' with multiple rows matched.
  *   The ROWIDs of the changed records are returned.  This is how to get
- *   the 'last insert id'.
+ *   the 'last insert id' of multiple rows.  For a single row, use "lastRowid".
  *
  *   This example uses Node 8's async/await syntax.
  *

examples/dmlrupd1.js renamed to examples/lastinsertid.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -16,12 +16,11 @@
  * limitations under the License.
  *
  * NAME
- *   dmlrupd1.js
+ *   lastinsertid.js
  *
  * DESCRIPTION
- *   Example of 'DML Returning' with a single row match.
- *   The ROWID of the changed record is returned.  This is how to get
- *   the 'last insert id'.
+ *   Example of inserting a row and getting it's ROWID.
+ *   To return application generated identifiers, see dmlrupd.js.
  *
  *   This example uses Node 8's async/await syntax.
  *
@@ -53,13 +52,9 @@ async function run() {
     //
 
     const stmts = [
-      `DROP TABLE no_dmlrupdtab`,
+      `DROP TABLE no_lastinsertid`,
 
-      `CREATE TABLE no_dmlrupdtab (id NUMBER, name VARCHAR2(40))`,
-
-      `INSERT INTO no_dmlrupdtab VALUES (1001, 'Venkat')`,
-
-      `INSERT INTO no_dmlrupdtab VALUES (1002, 'Neeharika')`
+      `CREATE TABLE no_lastinsertid (id NUMBER, name VARCHAR2(40))`,
     ];
 
     for (const s of stmts) {
@@ -72,28 +67,21 @@ async function run() {
     }
 
     //
-    // Show DML Returning
+    // Execute the SQL statement
     //
 
-    // SQL statement.
-    // Note bind names cannot be reused in the DML section and the RETURNING section
-    const sql =
-          `UPDATE no_dmlrupdtab
-           SET name = :name
-           WHERE id = :id
-           RETURNING ROWID INTO :rid`;
+    const sql = `INSERT INTO no_lastinsertid VALUES (:id, :name)`;
 
     const result = await connection.execute(
       sql,
       {
-        id:    1001,
-        name:  "Krishna",
-        rid:   { type: oracledb.STRING, dir: oracledb.BIND_OUT }
+        id:    1000,
+        name:  "Chris"
       },
       { autoCommit: true }
     );
 
-    console.log(result.outBinds);
+    console.log("The ROWID is", result.lastRowid);
 
   } catch (err) {
     console.error(err);