Misc doc updates

Author: bengsig

docs/INTRODUCTION.md

@@ -41,16 +41,19 @@ $include:"rwltest.rwl"
 # Declare some variables, and possibly initialize them
 integer empno, deptno:=10, numemps:=0; $useroption:deptno
 string ename, dname;
-double monthsal;
+double monthsal, comm;
 
 for # execute a cursor loop
-  select e.ename, d.dname, e.sal/12 monthsal
+  select -- names in select list match variables
+    e.ename, d.dname
+  , e.sal/12 monthsal, comm
   from emp e join dept d
   on e.deptno = d.deptno
-  where d.deptno = :deptno
+  where d.deptno = :deptno -- bind matches variable
   /
-loop # Execute a cursor loop
-  printf "%s works in %s and makes %.2f monthly\n", ename, dname, monthsal;
+loop 
+  printf "%-10s works in %10s and makes %6.2f monthly plus %t5.0f annual commission\n"
+  , ename, dname, monthsal, "no", comm;
   numemps += 1; # count the number of rows
 end loop;
 

docs/NEWS30.md

@@ -82,7 +82,7 @@ In previous versions, it was necessary to have two rwl statements
 associated with each sql; the first would declare the sql as 
 a variable, and the second would execute this variable as is
 (for e.g. DML, PL/SQL or single row queries) or as a cursor
-loops for queries with an unknown number of rows.
+loop for queries with an unknown number of rows.
 In version 3, you can now combine these into one for immediate
 execution.
 
@@ -128,7 +128,7 @@ end loop;
 To prevent having passwords in clear text in either .rwl files or on the command line
 (from where rwloadsim does overwrite the memory), you can now use external authentication
 via wallets.
-This is achieved by declaraing a database with a connect string that matches a name in the wallet
+This is achieved by declaring a database with a connect string that matches a name in the wallet
 but neither the username nor password attributes,
 or alternatively by giving empty username and password using /@name to the -l option
 similar to how SQL*Plus does it.

docs/PRINTF.md

@@ -2,7 +2,7 @@
 The printline and associated statements are useful to provide
 simple output with default formatting, that can be generally
 modified using the $dformat or $iformat directives for 
-respectivele double and integer.
+respectively double and integer.
 
 For more advanced output, you can use the fprintf statement
 or the sprintf statement to output to a string.
@@ -17,11 +17,13 @@ but using a syntax that include ||, the formatted output
 will append to the string.
 
 All statements work like their C equivalents but do additionally have
-a flag 'z', 'b', 'n' or 'N' that control how a NULL integer or double
+a flag 'z', 'b', 'n', 'N' or 't' that control how a NULL integer or double
 value is formatted.
 By default, if an integer or double is NULL, an empty string will be output.
 Using the 'z' flag, a NULL will be output as zero, using 'b' blanks will be
 used and using 'n' or 'N', the text null or NULL will be used.
+Using 't', the subsitution text will be taken from an argument to the printf 
+statement.
 
 Some examples are shown here
 ```
@@ -32,6 +34,7 @@ string s := "fourtytwo";
 # Show 0-padding and output of null
 printf ">%07d|%d<\n", a, b; 
 printf ">%07d|%nd<\n", a, b;
+printf "%td\n", "no value", b;
 
 b:=4;
 # Show how field width and precision
@@ -48,6 +51,7 @@ which will generate this output:
 ```
 >0000042|<
 >0000042|null<
+no value
 >12.3457       <
 fourtytwo=42  |
 ```

docs/SQL.md

@@ -239,10 +239,11 @@ to modify any of its attributes, you can use a syntax that immediately executes
 your sql statement.
 The syntax combines the declaration - although with the keyword ```execute```
 in stead of a name - with the execution as shown in the following examples.
-Note that implicit bind and define is automatically enabled for immediate SQL.
+Note that implicit bind and define is automatically enabled for immediate SQL, so
+the $implicit directive is not required.
 
 Effectively, immediated SQL has most of the simplicity of embedded SQL without
-having the constriants such as lack of output bind.
+having the constraints such as lack of output bind.
 
 Immediately execute an insert with a returning clause
 ```
@@ -302,7 +303,7 @@ it _will_ be treated as a dynamic SQL and will also have the implicit bind and
 define done.
 Doing so implies array dml cannot be used, as the sql statement potentially could
 changed for each execution inside a loop.
-If you need dynmically generated dml to use an array, use declared dynamic SQL.
+If you need dynamically generated dml to use an array, use declared dynamic SQL.
 
 Declaration and use of dynamic SQL variables, where the sql text and possibly
 bind/define are done at runtime is described in [DYNAMICSQL.md](DYNAMICSQL.md).

docs/WORKING.md

@@ -7,7 +7,9 @@ interface and is primarily targeted at scripting environments, where
 sqlplus together with things like shell, sed, awk and other Unix tools 
 doesn't allow sufficient control of how to execute SQL statements or a 
 mix of concurrently executing SQL statements.
-Rwloadsim has several ways to specify random values for SQL or PL/SQL 
+
+As a simulation tool, rwloadsim has several ways to specify random
+values for SQL or PL/SQL 
 with bind variables, and it can control things like frequency of 
 execution, mix of "transactions", several connection mechanisms 
 including session pooling, while it also may gather run-time execution 
@@ -17,6 +19,13 @@ schema to allow for reporting.
 The rwloadsim language is also sufficient to allow automatic generation 
 of awr reports.
 
+In addition to actual workload simulations, rwloadsim is a relatively 
+powerful scripting tool. 
+One example of such usage is that database administrators easily can
+create scripts, which combine execution of SQL with procedural logic.
+If you only use it for its scripting capabilities, there is no need for 
+the repository database that stores execution statistics.
+
 Some of the rwloadsim behavior is controlled via options to the 
 executable, and the actual RWL program is specified in text files that 
 are read by rwloadsim; several options can be set globally using 
@@ -33,11 +42,6 @@ It is also possible to include rwl files within others similar to using
 the @ clause in SQL\*Plus or #include in C,
 and you can conditionally include code similar to #if in C.
 
-In addition to actual workload simulations, rwloadsim is a relatively 
-powerful scripting tool.
-If you only use it for its scripting capabilities, there is no need for 
-the repository database, that stores execution statistics.
-
 ### Manual pages
 
 Your distribution includes reference documentation in the form of manual

docs/refman/printfstatement.html

@@ -86,7 +86,7 @@ text null or the user provided text "nothing":
 .P
 .nf
 integer a; 
-printf "|%Nd|%td|\n", a, "nothing", a;
+printf "|%Nd|%td|\\n", a, "nothing", a;
 .fi
 .P
 which will produce the following output: