Documentation for usage of "tns" connection parameter

README.md

@@ -21,40 +21,81 @@
 
     `npm install oracle`
 
-# Example
+# Examples
+
+The simplest way to connect to the database uses the following code:
 
 ```javascript
 var oracle = require("oracle");
 
-oracle.connect({ "hostname": "localhost", "user": "test", "password": "test" }, function(err, connection) {
-  // selecting rows
-  connection.execute("SELECT * FROM person WHERE name = :1", ['bob smith'], function(err, results) {
-    // results will be an array of objects
+var connectData = { "hostname": "localhost", "user": "test", "password": "test", "database": "ORCL" };
+
+oracle.connect(connectData, function(err, connection) {
+    ...
+    connection.close(); // call this when you are done with the connection
   });
+});
+```
+The `database` parameter contains the "service name" or "SID" of the database. If you have an Oracle RAC or some other kind of setup, or if you prefer to use "TNS", you can do so as well. You can either provide a complete connection string, like:
 
-  // inserting with return value
-  connection.execute(
-    "INSERT INTO person (name) VALUES (:1) RETURNING id INTO :2",
-    ['joe ferner', new oracle.OutParam()],
-    function(err, results) {
-      // results.updateCount = 1
-      // results.returnParam = the id of the person just inserted
-    });
+```javascript
+var connString = 
+      "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=orcl)))";
+```
 
-  connection.setAutoCommit(true);
+or just the shortcut as declared in your `tnsnames.ora`:
 
-  connection.commit(function(err) {
-    // transaction committed
-  });
+    DEV =
+      (DESCRIPTION =
+        (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521))
+        (CONNECT_DATA =
+          (SERVER = DEDICATED)
+          (SERVICE_NAME = orcl)
+        )
+      )
 
-  connection.rollback(function(err) {
-    // transaction rolledback
-  });
+The connection parameter would then be:
+
+```javascript
+var connectData = { "tns": "DEV", "user": "test", "password": "test" };
+// or: var connectData = { "tns": connString, "user": "test", "password": "test" };
+```
+
+To access a table you could then use:
 
-  connection.close(); // call this when you are done with the connection
+```javascript
+oracle.connect(connData, function(err, connection) {
+
+  connection.setAutoCommit(true);
+
+  // selecting rows
+  connection.execute("SELECT * FROM person", [], function(err, results) {
+    if ( err ) {
+      console.log(err);
+    } else {
+      console.log(results);
+
+      // inserting with return value
+      connection.execute(
+        "INSERT INTO person (name) VALUES (:1) RETURNING id INTO :2",
+        ['joe ferner', new oracle.OutParam()],
+        function(err, results) {
+          if ( err ) { console.log(err) } else {
+            console.log(results);
+          }
+          // results.updateCount = 1
+          // results.returnParam = the id of the person just inserted
+          connection.close(); // call this when you are done with the connection
+        }
+      );
+    }
+
+  });
 });
 ```
 
+
+
 ## Out Params
 
 The following Out Params are supported in Stored Procedures: