Add project & script Markdown documentation

README.md

@@ -0,0 +1,9 @@
+# oracle-scripts
+
+This repository is intended to hold BASH, SQL, and PL/SQL scripts for working with Oracle databases. They may require elevated privileges or non-default object grants, and so will primarily be of interest to DBAs and Developers.
+
+[BASH scripts](bash/BASH.md)
+
+[SQL & PL/SQL scripts](sql/SQL.md)
+
+These scripts have been tested, where applicable, using Oracle 11.2.0.4 and 12.2.0.1. They are expected to run successfully against any 11.2.x and 12.x release.

bash/BASH.md

@@ -0,0 +1,26 @@
+# BASH scripts
+
+Please note that these scripts don't shy away from Bash-specific syntax, since those capabilities often make scripts simpler to write and maintain... plus, at this point I've found Bash to be ubiquitous for a number of years. While they may well work under similarly capable shells such as Ksh and Zsh, breakage is most definitely expected when using standard /bin/sh implementations.
+
+### dbping
+
+This gives timing information similar to the Oracle *tnsping* utility, which is often unavailable since it isn't included in the Instant Client. The primary difference is that it attempts database authentication using SQL*Plus (which is expected to always fail, although the functionality doesn't depend upon this), whereas tnsping stops at the listener and never touches the DB itself. So it's a more thorough connectivity test, which is expected to return somewhat longer times.
+
+Usage:
+
+```
+dbping connection_string [count]
+```
+The first parameter is required, and can be any connection identifier which SQL*Plus is able to interpret... typically a tnsnames entry or EZConnect string. The second, optional, parameter is an integer in the range of 1-20, and indicates how many times the test should be performed.
+
+### upload_to_MOS
+
+This uploads one or more diagnostic files to a specified Service Request on My Oracle Support (MOS), using the HTTPS protocol. This process is documented in Doc ID 1682567.1 on the MOS website.
+
+Usage:
+```
+upload_to_MOS file1 [[file2]...] sr_number
+```
+This requires a minimum of two parameters, with all leading parameters indicating files to be uploaded. The final parameter is the target SR number for the upload data.
+
+Your MOS username can be set either by updating the "mos_account=" line near the top of the script, or setting the *MOS_ACCOUNT* environment (which will override the former). The script will prompt for your MOS password, when is then provided to cURL once per file being upload. This value is not saved, or used in any other manner.

sql/SQL.md

@@ -0,0 +1,26 @@
+# SQL & PL/SQL scripts
+
+### cursor_xplan.sql
+
+This is intended as a RAC-aware replacement for the DBMS_XPLAN.DISPLAY_CURSOR function, meaning that it does not require you to be connected to the same instance which parsed the cursor of interest.
+
+Usage:
+```
+@cursor_xplan [sql_id] [sql_child_number] [instance_number] [format]
+```
+All 4 parameters are optional, and will default to reasonable values. Please note, however, that the default value for *format* is different than what DBMS_XPLAN.DISPLAY_CURSOR uses.
+* **sql_id** - Defaults to the previously executed statement.
+* **sql_child_number** - Defaults to 0 if *sql_id* was specified, otherwise the last executed statement.
+* **instance_number** - Defaults to the current database instance.
+* **format** - Defaults to "ALL LAST PEEKED_BINDS -PROJECTION"
+
+Unspecified trailing parameters can simply be omitted. If you want to use the default for a leading parameter, however, you need to use a pair of double-quotes as a placeholder. For example:
+```
+@cursor_xplan "" "" "" TYPICAL
+```
+The invoking user will require the following object privileges:
+
+* SELECT on V$SESSION
+* SELECT on GV$SQL
+* SELECT on GV$SQL_PLAN_STATISTICS_ALL
+* EXECUTE on DBMS_XPLAN